Demo: the validator refuses the move to Done, the assignee ticks three items (two with evidence), DefinitionGuard refuses the assignee's tick and waiver of the peer review item, and the audit history shows each saved change. 88 seconds, no sound; captions are in the video.

1. Who this guide is for

  • Team members who tick items and add evidence. Read sections 3 and 4.
  • Reviewers and approvers who tick review items, waive items and reset checklists. Read sections 4 and 9.
  • Project administrators who write the checklists and check the gate. Read sections 5 and 6.
  • Jira administrators who install the app, add the validator and choose approver groups. Read sections 2, 6 and 12.

2. Install and first setup

  1. Install (Jira administrator). In Jira, open Apps > Explore more apps, search for DefinitionGuard and choose Get app. The app asks to read Jira work, users and workflows, to write issue properties, to store its own data, and to report personal data to Atlassian. It calls no server outside your Atlassian site.
  2. Check the checklists (project administrator). Every issue already has a built-in checklist for its type (section 5). Change it in Project settings > DefinitionGuard if you want.
  3. Add the gate (Jira administrator). Add the validator DefinitionGuard DoD Enforcement to each transition into a Done status (section 6). Without it, DefinitionGuard shows the checklist but does not block.
  4. Check the coverage (project administrator). In Project settings > DefinitionGuard > Gate coverage, every completion transition should read Gated.
  5. Choose approvers (Jira administrator, optional). In Jira settings > Apps > DefinitionGuard approvers, add the groups that may waive items and reset checklists (section 9).

Licence. When the licence is not active, the panel and the settings page show "Licence not active". The gate is off: moves to Done are not blocked, and checklist changes are not saved. Reading the checklist and its history still works.

3. The Definition of Done panel

Open an issue. If the panel is not shown, choose the issue's app button (below the title) and then Definition of Done.

The issue's app actions menu with Approval Seal, Definition of Done, Four Realities and Add apps.
Figure 1: The issue's app button opens the Definition of Done panel.
The Definition of Done panel on a new story: an Incomplete lozenge, the summary naming four open mandatory items, the next step, the approver line, the Complete DoD button, five items with Mandatory or Optional lozenges and Tick with evidence and Waive buttons, Reset checklist, and the collapsed Checklist audit history.
Figure 2: The panel on a new story, with the built-in Feature & Story checklist.
PartWhat it shows or does
Status lozengeDoD complete (green) or Incomplete (red).
RefreshReads the checklist again.
SummaryEither "This issue can be moved to Done", or the list of open mandatory items that block the move.
Next stepThe first open mandatory item, or "All mandatory criteria complete".
Approver lineWho can waive and reset on this site.
Complete DoDActs on the first unticked item only. It ticks that item, or opens its evidence form when it needs evidence. It does not tick the whole list.
Item checkboxTicks or unticks the item. On an item that needs evidence, it opens the evidence form instead.
LozengesMandatory or Optional, Needs evidence, Evidence attached, Waived.
Tick with evidenceTicks an item with a link or a note, even when evidence is not required.
WaiveShown on open mandatory items. Waives the item with a reason.
Show evidenceShows the link and the note of a ticked item.
Who and whenUnder a ticked or waived item: the person, "completed this" or "waived this", and the time.
Reset checklistAsks "Reset this checklist?" and then reopens every item. The reset is added to the history.
Checklist audit historyThe history, the chain check and the export (section 7).

A checklist is stored on the first change (a tick, a waiver or a reset). Before that, the panel shows the current template of the issue type.

4. Everyday tasks

Tick an item

Click the item's checkbox. Result: the item is ticked, with your name and the time. Untick it to reopen it; reopening an item drops its evidence.

Tick an item with evidence

  1. Click the checkbox of an item marked Needs evidence, or choose Tick with evidence on any open item.
  2. Enter a link that starts with http:// or https://, a note of up to 500 characters, or both.
  3. Choose Save and tick. It is active once the link or the note has text.
The evidence form under the item Automated test suite passes with zero regressions: a link to a CI build, the note Build 1482: 412 tests passed, 0 failed, and the Save and tick and Cancel buttons.
Figure 3: Ticking an item with a link and a note.

Result: the item shows Evidence attached. DefinitionGuard checks the link's format only, not what it points to.

Waive an item that does not apply

  1. Choose Waive on the open mandatory item.
  2. Write why the item does not apply, 10 to 500 characters.
  3. Choose Waive item.
The waive form under Static analysis and dependency vulnerability scan clear, with a reason and the Waive item and Cancel buttons.
Figure 4: Waiving an item with a reason.

Result: the item shows Waived, and it counts as done for the gate. The reason is kept in the history. Unticking a waived item reopens it; that needs the same right as a waiver.

The panel with 3 of 5 items done: one ticked item, one ticked item with Evidence attached showing its link and note, one open mandatory item, one Waived item, and one open optional item. The summary names the one open mandatory item.
Figure 5: A checklist in progress. One mandatory item still blocks the move to Done.

The not-the-assignee rule

An item marked Not the assignee, for example a peer review, cannot be ticked or waived by the current assignee, or by anyone who was the assignee since the item was last opened. DefinitionGuard reads this from the issue's change history. The panel shows "The assignee cannot complete this item. Ask a reviewer." The validator checks the rule again at the move into Done.

Reset a checklist

Choose Reset checklist, then Reset checklist again in the warning. Every item becomes open. Nothing in the history is removed.

5. Write the checklists (project administrator)

Open Project settings > DefinitionGuard. You need Administer projects, or Jira administrator.

The Definition of Done templates section for issue type Task: template name Payments task DoD and five items, each with Mandatory, Evidence required and Not the assignee checkboxes, a permission select, a category select, and Move up, Move down and Remove buttons.
Figure 6: A project template for the issue type Task.
  1. Choose the issue type in the first field.
  2. Type a template name, for example "Team DoD".
  3. For each item, set the title and the rules:
    • Mandatory: the gate blocks Done while this item is open and not waived.
    • Evidence required: the item can be ticked only with a link, a note, or both.
    • Not the assignee: the assignee, now or since the item was opened, cannot tick or waive it.
    • Permission: No extra permission, Resolve issues, Transition issues or Administer projects. The user needs it to tick the item.
    • Category: Testing, Code quality, Security, Compliance or Documentation.
  4. Set Who else can waive: Administer projects (the default), Resolve issues or Transition issues. Approvers can always waive. Users with the chosen Jira permission on the issue can waive too, and reopen a waived item. The template saves this choice, and a later save keeps it.
  5. Use Move up, Move down and Remove. Type a title in New item title and choose Add item; a new item is Mandatory and in Testing.
  6. Choose Save template. Result: "Template "NAME" version n saved." Each save adds 1 to the version.
  7. Open issues keep their version. To move them, choose Re-sync open issues. Result: "Re-synced n open issues to version v. Ticks on unchanged items were kept." New items start open. A re-sync never reopens a ticked item.

Built-in templates

Without a project template, DefinitionGuard picks a built-in template by the issue type name: Service Desk Request, IT Help Desk, Bug Fix (bug, defect, incident, problem), Feature & Story (story, feature, enhancement), Technical Task (chore, refactor, maintenance), or the Standard Engineering Definition of Done for any other type, Task included.

Statuses the gate lets through

The gate blocks moves into Done-category statuses. Tick the Done-category statuses that are not completions, such as Canceled or Declined, and choose Save statuses. Moves into those statuses are not gated.

Statuses the gate lets through: the explanation, a Done checkbox and the Save statuses button.
Figure 7: Statuses the gate lets through. This project has one Done-category status, Done, which stays gated.

6. The Done gate (the workflow validator)

DefinitionGuard blocks a move only on transitions where a Jira administrator added its validator. The app cannot add it for you.

  1. Open the project's workflow in the Jira workflow editor.
  2. Select a transition into a Done-category status.
  3. Add the validator DefinitionGuard DoD Enforcement. It has no options. It works in company-managed and team-managed projects.
  4. Repeat for every transition into Done, then publish the workflow.
  5. In Project settings > DefinitionGuard > Gate coverage, choose Check again. Each transition shows Gated, Not gated or Exempt.
Gate coverage before the validator is added: a warning that 0 of 1 completion transitions are gated, the Done transition marked Not gated, and the Check again button.
Figure 8: Gate coverage in its state before the validator is added. The warning tells you which transition still needs the validator. After you add it and choose Check again, the transition reads Gated.

What the validator does

  • It lets the move through when every mandatory item is done or waived, with evidence where it is required, and not ticked by an excluded assignee.
  • It lets through moves to statuses that are not in the Done category, and moves to exempt statuses.
  • An issue with no stored checklist is checked against its template, with every item open. So once the validator is on, such an issue cannot reach Done.
  • If DefinitionGuard cannot read what it needs, it blocks the move (it fails closed).
  • With an inactive licence, it lets every move through.

When it blocks, Jira shows:

Definition of Done is not complete. Open mandatory items: <titles>. Open the Definition of Done panel on this issue (from the View app actions button if it is not shown) to finish them.

7. Audit history and export

  1. Open Checklist audit history in the panel and choose Load audit history.
  2. Read the chain result: Chain intact or Chain broken, and the signature result: Property signed or Property not signed.
  3. Read the events: who, when, the action (Checklist created, Completed, Reopened, Waived, Checklist reset), the item, the reason and the evidence. The panel lists the history 100 events at a time, oldest first. While more events follow, it shows "Showing n of m events, oldest first." and Show more, which adds the next 100. The chain check and the export cover every event.
  4. Project and Jira administrators choose Export history. Copy the JSON and save it as KEY-definitionguard-history.json. There is no download button.
The Checklist audit history with 4 events: Chain intact, Property signed with a note naming the key, and the events Checklist created, two Completed events (one with its evidence link and note) and a Waived event with its reason.
Figure 9: The audit history. This test site signs with a development key; a Marketplace installation signs with dg-prod-2026-11.
The history export header: Checklist history export: PAY-28-definitionguard-history.json, the instruction to copy the JSON and save it under that name, and the start of the JSON.
Figure 10: The export, ready to copy.

What the checks mean

  • The chain. Each event holds the SHA-256 hash of the event before it. The check shows edits, removals and reordering of the stored history. It does not stop someone who can rewrite all of the app's stored data and the chain with it, and that includes the app vendor.
  • The signed property. On every change, DefinitionGuard writes the issue property definitionguard-dod: a summary of the checklist (counts, open mandatory item ids, the chain head), signed with Ed25519. The public keys are on the Signing keys page. FourRealities checks this signature for its Process gate. "Property signed" in the panel means the site has a signing key; the panel itself does not check the signature.

8. Permissions

ActionWho can do it
See the panel, the history and the evidenceUsers with Browse projects on the issue.
Tick or untick an itemUsers with Edit issues, plus the item's extra permission. Not the assignee, for items marked Not the assignee.
Waive an itemApprovers: project administrators, Jira administrators and members of the approver groups. Also users with the template's waiver permission (Who else can waive, default Administer projects). Not the assignee, for items marked Not the assignee.
Reopen a waived itemUsers with Edit issues who can also waive the item.
Reset a checklistApprovers.
Export the historyProject administrators and Jira administrators.
Edit templates, statuses, re-sync, see coverageProject administrators and Jira administrators. Changes need an active licence.
Choose approver groupsJira administrators.

Every check asks Jira as the user and fails closed: if Jira does not answer, the change is not saved.

9. Approver groups (Jira administrator)

  1. Open Jira settings > Apps > DefinitionGuard approvers.
  2. Search for a group in Find Jira groups to grant authority, then choose Add.
  3. Choose Save changes. Result: "Saved. The approver groups apply to every project on this site."
The DefinitionGuard approvers page with one approver group, its Remove button, Save changes, and the group search field.
Figure 11: The DefinitionGuard approvers page with one group.

At most 20 groups. A search shows at most 20 results and takes at most 100 characters.

10. Data stored and where

  • Where: in the Forge storage of your site, and in one issue property per issue. DefinitionGuard sends nothing outside your Atlassian site.
  • In Forge storage: each issue's checklist state and its history events (status, reason, evidence link and note); project templates; exempt statuses; approver groups.
  • On the issue: the signed property definitionguard-dod. It holds no personal data.
  • People: each person is stored as a random pseudonym. The Atlassian account id is kept only in one link record per person. The app reports these ids to Atlassian every week and deletes the link of each closed account; the history then shows "A deleted user", and the chain still checks.
  • Free text: evidence links, notes and waiver reasons are kept as typed and may name people.
  • Retention: records stay until the issue is deleted or the app is uninstalled. Deleting an issue deletes its checklist and history.

See the privacy policy.

11. Limits

  • Items per template: 1 to 50. Template size: 32 KiB. Template name: 100 characters. Item title: 200 characters.
  • Evidence link: http or https, at most 2,000 characters. Evidence note: 500 characters. Waiver reason: 10 to 500 characters.
  • Exempt statuses: 50. Approver groups: 20.
  • The panel lists the first 100 history events.
  • The assignee history reads at most 10,000 changelog entries; beyond that the change is refused.

12. Troubleshooting and messages

MessageWhat it means and what to do
"Definition of Done is not complete. Open mandatory items: ..."The validator blocked the move. Finish or waive the named items.
"DefinitionGuard could not check the Definition of Done, so this move is blocked. Try again..."The validator could not read what it needs. Try again; if it keeps failing, ask your Jira admin.
"The assignee cannot complete this item. Ask a reviewer."The item is marked Not the assignee. Another person must tick it.
"You need Edit issues permission to change this checklist."Ask a project administrator for Edit issues.
"You need the <Perm> Jira permission to complete this item."The item needs an extra permission.
"Only users with the <Perm> Jira permission can waive this item."Ask an approver to waive it.
"Only a project admin can reset this checklist."Ask an approver.
"Add a link or a note. This item needs evidence before it counts as done."Use the evidence form.
"The evidence link must start with http:// or https://."Fix the link.
"Give a reason of 10 to 500 characters for the waiver."Write a longer or shorter reason.
"Someone else changed this checklist. Refresh and try again."Choose Refresh and make your change again.
"Your DefinitionGuard licence is not active. Ask your Jira admin."The licence must be renewed under Manage apps.
"DefinitionGuard could not <action>. Refresh the page and try again..."A general error. Refresh; if it keeps failing, ask your Jira admin.
"DefinitionGuard could not read the project workflows..."Gate coverage could not read workflows. A Jira admin checks the app's access.
"History check failed at event N (...)"The stored history does not match its chain. Ask your Jira admin to review the issue.
Gate coverage shows "Not gated"Add the validator to that transition and choose Check again.

Still stuck? Write to [email protected].

13. Uninstall and data removal

  1. Remove the validator DefinitionGuard DoD Enforcement from your workflows first, so no transition depends on it.
  2. A Jira administrator opens Jira settings > Apps > Manage apps and uninstalls DefinitionGuard.
  3. Atlassian keeps the app's Forge storage for 28 days and then deletes it: checklists, history, templates and settings.
  4. The issue property definitionguard-dod stays on each issue until the issue is deleted.

For other requests, write to [email protected].

14. Related pages

[ } Eliya Eliya Jira Governance Jira Governance Dial Dial
YouTube Privacy Security
[ }
[ }