Guide · Jira

How to block a Jira transition until a checklist is done

Checklist Flow for Jira 3.1.1 is the production version (1 November 2026). Last updated 1 November 2026. On the Atlassian Marketplace.

By Bartosz Stankiewicz, founder, Stanki Guild.

You want Jira to refuse the move to Done while a checklist is unfinished. Not warn, not comment: refuse. This guide covers the mechanisms Jira Cloud offers, what each one can and cannot check, and the traps that make a gate look enforced when it is not.

The short answer: put a workflow validator on the transition into Done. A validator is the one workflow mechanism that makes Jira refuse the move. Jira's built-in validators cannot read checklist items, so your options are a proxy field, a scripted validator, or a checklist app that ships its own validator, such as Checklist Flow (ours). Whichever you choose, test it on a sandbox work item with one item left open.

Three workflow mechanisms touch transitions in a company-managed Jira workflow:

• Conditions decide whether a user can perform a transition at all. If a condition fails, the user does not see the transition. Conditions cannot validate input.
• Validators check the input before the transition is performed. If a validator fails, the work item stays in its status. This is the gate.
• Post functions run after the transition has happened. They can update fields, but they cannot stop anything.

Atlassian describes all three in Configure advanced work item workflows.

So the recipe is always the same: a validator on the specific transition. The only question is what the validator can read.

The built-in validators check fields and permissions; the one most teams use is the Field Required validator, which checks that a field has a value. None of them can read:

• native action items (the [] checkboxes in descriptions),
• the state of individual items in any checklist,
• counts such as "5 of 7 items checked".

The related requests are open in Atlassian's tracker: Automation access to action items (JRACLOUD-96783) and a checklist field type (JRACLOUD-94964). On plain Jira your enforceable options are therefore:

1. A proxy field. A checkbox or select field such as "Quality gate passed", required by the Field Required validator. The gate is real, but what it checks is one self-reported field; the checklist itself stays advisory.
2. A scripted validator, with a scripting app such as ScriptRunner. It can check almost anything, at the cost of an extra licence and a script you maintain.
3. A checklist app that ships its own workflow validator. This is the gap the checklist app category exists to fill.

1. In Jira settings, create a custom field of type Checkboxes with a single option, for example "Quality gate passed".
2. Add the field to the screen used by the transition into Done (a transition screen makes the requirement visible at the moment it matters).
3. Edit the project's workflow, select the transition into Done, and add the Field Required validator for the new field.
4. Publish the workflow and test it on a sandbox work item.

Be honest about what this enforces: that someone ticked one box, not that the checklist items were done.

Using Checklist Flow, our app, as the concrete example:

1. Open a work item, open the Apps button in the work item view and choose Checklist Flow to open the checklist panel. Add your items and switch on Required for the ones that are non-negotiable.
2. Optionally click Name this checklist and call it "Definition of Done". The title belongs to that work item's checklist; save the items as a template to reuse them.
3. As a Jira administrator, open the workflow the project uses in the workflow editor.
4. Select the transition into Done.
5. Add a validator and pick Checklist Definition of Done.
6. Publish the workflow.
7. Test on a sandbox work item: leave a Required item open and try to move it to Done. Jira refuses with a message that names the open item, for example "Definition of Done not met: 1 required checklist item still open: "Tests pass"." Check the item and try again: it passes.

How the validator decides: if any item is marked Required, only the Required items count; if none is, every item counts. An item marked N/A counts as satisfied. If the check itself cannot be completed, the transition stays blocked and the user is asked to try again: the gate fails closed. Ask every vendor about this, because a validator that lets work through during an outage is not a control.

Team-managed projects have their own simplified workflow rules, such as "Restrict who can move a work item" and "Validate that people have a specific permission" (Available workflow rules in team-managed spaces). None of them can check a checklist. Forge app validators are available in company-managed projects by default, and in team-managed projects only when the app declares it. Checklist Flow's validators are declared for team-managed projects too, and we tested them live in a team-managed project on 17 October 2026: the transition to Done was refused until the required items were checked. Add the rule in Project settings, Work types, Edit workflow: select the transition, Add rule, Checklist Flow.

A checklist validator can only block work items that have a checklist. In Checklist Flow, a work item with no checklist, or an empty one, is never blocked. Two ways to make sure every relevant work item carries one:

• Auto-apply by issue type: map an issue type to a saved template, and the template is added to every new work item of that type. In Checklist Flow this is a paid feature, set by a Jira administrator on the Templates tab of Checklist Flow settings.
• Global checklists: a list defined once by an administrator that appears on every matching work item, enforced by its own Global checklist done validator. Also a paid feature in Checklist Flow.

The validator catches the problem at the transition. The quieter win is knowing in advance which work items will bounce. Checklist Flow writes the checklist state to JQL fields, so a saved filter such as dodMet = "false" AND sprint in openSprints() is your "about to be blocked" queue. The DoD Health project page (paid) shows the same state for a whole project, the open sprints, one sprint or one epic.

Checklist Flow is our app. It adds the checklist panel, Required items, and the Checklist Definition of Done validator that blocks the transition and fails closed. The validator, the JQL fields and the full history work without a paid licence; auto-apply, global checklists and DoD Health need one. Every check, uncheck and edit is recorded in an append-only, hash-chained history that no role can clear in the app, exportable as CSV or JSON.

Checklist Flow is free for up to 10 users with every feature, then from USD 0.80 per user per month for the first 100 users, lower in larger tiers. Read the documentation, browse the checklist templates or see how it compares.

Can I block a transition with plain Jira, no app?

Yes, with the Field Required validator on a proxy field such as a "Quality gate passed" checkbox. Understand what that enforces: that someone ticked one box, not that the checklist items were done.

What is the difference between a condition and a validator?

A condition decides who can perform the transition, and hides it from everyone else; a validator checks an attempted transition and decides whether it succeeds. To block work items that are not ready, rather than people, you want a validator.

Do checklist validators work in team-managed projects?

Only if the app supports them: Forge validators work in company-managed projects by default, and an app has to opt in to team-managed projects. Checklist Flow's validators are declared for team-managed projects too, and we have tested them live in team-managed and company-managed workflows; the built-in team-managed rules cannot read a checklist.

Can the block be overridden in an emergency?

In Checklist Flow there is no override inside the app: the path through the gate is finishing the Required items or marking them N/A, and both are recorded in the history. A Jira administrator can still change the workflow itself. Decide whether your process needs a documented break-glass rule around that.

• Checklist Flow for Jira documentation
• Jira checklist templates
• Checklist Flow compared with other Jira apps
• How to enforce a Definition of Done in Jira
• Definition of Done vs acceptance criteria, with Jira examples
• Jira checklist: what to look for in a checklist app
• Jira checklists vs subtasks: when to use which
• Jira Automation with checklists: apply a template, add and check items, read status
• Checklist history and audit in Jira: who checked what, and when
• Checklist Flow with ScriptRunner for Jira Cloud: read checklist state in scripts
• Apply a checklist template to existing Jira work items
• Where does a Jira checklist app store your data, and can you export it?
• Testing a Definition of Done gate: does a required item really block Done?
• Smart Checklist Free end of support on 15 December 2026