Skip to main content

How to Add a Checklist to Jira — and Block Transitions Until Done

· 5 min read
NGPilot

Every team has a definition of done. The problem is that in Jira, "done" is one button press — nothing checks whether the release notes were written, the tests passed, or the customer was notified. A checklist fixes the remembering; enforcement fixes the skipping. This guide covers three ways to add a checklist to Jira issues, from a two-minute bullet list to required items that physically block the Done transition.

Quick answer: Jira has no native checklist panel. For enforcement — the part most teams actually want — install Checklist Workflow Automation for Jira, flag items as required, and have a Jira admin add the Checklist required items complete validator to the workflow's Done transition. From then on, Jira refuses to close an issue while any required item is unfinished. Free for up to 10 users.

Method 1 — Bullets in the Description (Zero Setup, Zero Enforcement)​

Type - [ ] item lines into the issue description or a comment. It renders as a list, anyone can edit it, and it takes thirty seconds.

Good for: ad-hoc personal notes on a ticket.

What's missing: nothing is checked automatically, nothing is searchable, and nothing prevents the issue from being closed with every box unticked. The checklist lives in free text, so JQL can't see it, reports can't count it, and a careless edit can delete it. It records intent; it enforces nothing.

Method 2 — Subtasks (Visible, Heavyweight, Still Not Enforced)​

Create each checklist item as a subtask. You get per-item assignees and statuses, and the items show on the board.

Good for: work that genuinely needs its own owner and lifecycle.

What's missing for a checklist: subtasks are separate work items — one definition-of-done list becomes five board cards, five assignee pings, and a cluttered backlog. And Jira's standard workflow never blocks the parent's transition on subtask state: close the parent and Jira happily leaves subtasks open. Using subtasks as a checklist adds process weight without adding the one thing checklists are for — the guarantee that done means done.

Method 3 — a Checklist Panel with Required Items (Recommended)​

Checklist Workflow Automation for Jira adds a checklist panel to every issue: type tasks, press Enter, and flag any row as required. The checklist is stored on the issue itself — it survives moves, copies when you clone, and shows up in JQL.

The part that changes team behavior is enforcement:

  1. A Jira admin opens Project settings → Workflows, edits the workflow, and on the transition into Done adds the validator Checklist required items complete (category: Forge apps).

  2. From then on, transitioning an issue with an unfinished required item is refused, with the offenders named:

    Complete required checklist items before transitioning: "Book venue", …

  3. Optionally, the same transition gets the Complete required checklist items post function, which auto-completes required items after the transition — useful when the checklist documents review steps rather than work.

Two rules make the enforcement predictable: only exactly Done satisfies a requirement (custom statuses like Waiting on vendor still block), and if the app ever can't read a checklist, the validator fails open — a broken app must never brick a workflow.

A Definition-of-Done Checklist You Can Copy​

Save this as a project template (the ⋯ menu on any issue) and apply it to new issues in one click:

Design review approved
Test plan written
  Unit tests pass
  Integration tests pass
Release notes updated
Customer communication drafted
Monitoring dashboard checked

Mark the first, second, and last items required and closing an issue without them becomes impossible. Prefer a spreadsheet? Import/export round-trips CSV with the nesting intact:

Item Text,Status,Order,Level
Design review approved,Done,1,0
Test plan written,To Do,2,0
Unit tests pass,To Do,3,1
Integration tests pass,To Do,4,1
Release notes updated,To Do,5,0

Find the Work That Isn't Actually Done​

The checklist is indexed for JQL, so "what's still owed before Done" becomes a saved filter or a dashboard gadget:

issue in hasIncompleteRequired()
cwaIncompleteRequired > 0 AND assignee = currentUser() AND sprint in openSprints()
cwaOverdueRequired > 0

Pair it with overdue reminders — a daily sweep comments on issues where a required item is past its due date, mentioning the assignee, at most once every 7 days per issue.

Which Method Should You Use?​

NeedUse
Personal notes on one ticketDescription bullets
Work with its own owner and board cardSubtasks
A definition of done the team cannot skipChecklist with required items + validator

For the third row — release checklists, incident response, onboarding steps — the setup cost is one workflow edit, and it pays back the first time Jira stops an issue from closing half-done. Install Checklist Workflow Automation for Jira, flag the non-negotiables as required, and make "done" mean done.

Related guides