Checklist

Checklists on the issue with statuses, due dates and mandatory items, searchable in JQL and enforceable on a transition.

What it does. Holds one or more named checklists on a single field. Items carry a status, not just a tick, so “not started”, “in progress” and “skipped” stop being the same thing.

Jira issue OPS-4412 → Release checklist (Checklist field)Illustration

Release checklist

3 of 5 complete

Edit Checklist

Change request approvedDoneMR

Rollback plan attachedDoneMR

Load test signed offDoneJL

Customer notifiedMandatoryOverdue · 2 daysOpenAS

Status page updatedDue todayOpen

Item capabilities: switch on only what you need

Setting	What it adds	When to enable
Allow Descriptions	Collapsible description text on each item.	When items need detail that does not fit in the title.
Allow Due Dates	A date badge per item, coloured for overdue, due today and future.	For checklists with real deadlines.
Allow Mandatory Items	Users can flag items as mandatory. Mandatory items can be enforced on a transition.	Whenever you plan to use the validator.
Allow Assignees (@mentions)	Items can be assigned to a person.	For checklists worked by several people.
Max Items per Checklist	A ceiling. `0` means unlimited.	Leave at 0 unless people abuse it.
Lock Checklist	Users can only tick and untick. They cannot add, edit, reorder or delete items.	For a compliance checklist that must be identical on every issue. Combine it with Default Items.

Statuses

Status Display Mode decides how people set item state: Checkbox only, Status dropdown, or Both. Four statuses ship with the app — Open, In Progress, Done and Skipped — and you can add your own under Custom Statuses.

The “Marks complete” flag is the important one

Each custom status declares whether it counts as complete. A Blocked status that does not mark complete keeps the item in the incomplete count, so a validator keeps blocking the transition. A Waived status that does mark complete lets the work move on. That is how you model exceptions without pretending the work is finished.

Default items

Default Items pre-fill the checklist the first time the field is used on an issue, and each one can be flagged mandatory. Combined with Lock Checklist, the field becomes a fixed procedure instead of a blank box.

Jira → Settings → Issues → Custom fields → Checklist → Contexts → Edit configurationIllustration

Checklist configuration

Save Configuration

Validation Mode

Mandatory only

Minimum items to complete

Important: you must also add the “Checklist Completion Validator” to the desired workflow transition.

Status Display Mode

Both

Max Items per Checklist

0 = unlimited

Item capabilities

Allow Descriptions

Allow Due Dates

Allow Mandatory Items

Allow Assignees (@mentions)

Lock Checklist

Custom Statuses

OpenIn progressDoneSkippedBlocked

“Blocked” added by an administrator · Marks complete: no

Default Items

Pre-populate this checklist when the field is first used on an issue.

1Change request approvedMandatory

2Rollback plan attachedMandatory

3Customer notified

Editing on the issue

Add item appends to the current checklist. Add Checklist starts a second named list on the same field.
Edit Checklist opens the full editor in a dialog, for reordering and bulk changes.
Bulk Edit (Markdown) takes the whole checklist as Markdown text. This is the fastest way to paste a procedure from a runbook or a Confluence page.

Blocking a transition until the checklist is done

This takes two steps. The field defines what “complete” means; the workflow validator applies it when the issue moves.

1In the field configuration, set Validation Mode: None, At least N (with a minimum number), Mandatory only, or All items.
2Go to Jira → Settings → Issues → Workflows, edit the workflow, open the transition, and add the Checklist Completion Validator.
3Publish the workflow. The transition now fails with a message naming the checklist and the items still open.

Jira → Workflows → Edit workflow → Transition “Ready for release” → Validators → Add validatorIllustration

Checklist Completion Validator

Blocks the transition if checklist items are not completed according to the validation rules.

Fields checked by this validator

Release checklist ✓Definition of Done ✓+ add field

Each field applies the Validation Mode set in its own field configuration.

What the user sees when the transition is blocked

Release checklist: 1 mandatory item is not complete — “Customer notified”.

```mermaid · flowchartExample

flowchart TD T[User attempts the transition] --> V{validator on<br/>this transition?} V -->|no| OK[Transition allowed.<br/>Nothing is enforced.] V -->|yes| M{Validation Mode<br/>on the field context} M -->|None| OK M -->|At least N / Mandatory only / All items| C{items satisfied?} C -->|yes| OK C -->|no| NO[Blocked, naming the<br/>checklist and the open items] classDef good fill:#DFFCF0,stroke:#216E4E classDef bad fill:#FFECEB,stroke:#AE2A19 class OK good class NO bad

Two switches in two different places, and the transition only blocks when both are set. The left-hand branch is what almost every support question about this field turns out to be.

Setting a Validation Mode on its own does nothing

Without the validator on the transition, nothing is enforced. The field configuration screen says so too. This is the single most common support question about this field.

Searching checklists in JQL

The app publishes checklist progress as searchable values, so you can report on checklist state like any other field.

JQL name	What it holds
`Checklist-Total-Items`	How many items exist.
`Checklist-Completed-Items`	How many are in a status that marks complete.
`Checklist-Progress`	Completion percentage, 0 to 100.
`Checklist-Has-Incomplete`	`1` when at least one item is not complete.
`Checklist-Has-Mandatory-Incomplete`	`1` when at least one mandatory item is not complete.
`Checklist-Item-Texts`	The text of the items, for keyword search.

Example queries

-- Work blocked on a mandatory checklist item
project = OPS AND "Checklist-Has-Mandatory-Incomplete" = 1

-- Nearly finished, for a stand-up
"Checklist-Progress" >= 80 AND "Checklist-Has-Incomplete" = 1

-- Every issue whose checklist mentions a rollback
"Checklist-Item-Texts" ~ "rollback"

Note

Two practical notes: put the name in quotes, and remember the values are refreshed shortly after a checklist changes. A query run in the same second as an edit can still see the previous numbers.