Documentation

Stepwise Approvals for Jira: user guide

Everything the app does, in the order you will meet it: the Approval panel, rules, the workflow validator, JQL, the Approvals page and log, and the details admins ask about.

On this page
  1. Getting started
  2. How an approval works
  3. Request and review
  4. Rules by work type and status
  5. Block a transition until approved
  6. JQL reference
  7. The Approvals page and the log
  8. Premium features
  9. Permissions
  10. Limits
  11. Data and personal data
  12. Troubleshooting
  13. Not available yet

Getting started

Stepwise Approvals is a Jira Cloud app. A Jira admin installs it from the Atlassian Marketplace and approves its permissions (they are explained under Permissions). After that, the Approval panel is available in work items, in company-managed and team-managed spaces.

It is a separate app from Stepwise Approvals for Confluence: each is installed on its own.

Open the Approval panel

  1. Open any work item.
  2. Find the Approval panel. It shows the state, the steps with their reviewers, and the history of the work item.
A work item with the Approval panel: In review, 2 approvals missing, and the steps with their reviewers.
The Approval panel in a work item.

Jira admins also have a page for the app in Jira settings, under Apps → Stepwise Approvals.

How an approval works

Approval
One request for a work item: steps, order, who asked, a message and an optional due date. A work item has one current approval at a time. Earlier ones stay in the history, and the round number counts up: 1, 2, 3.
Step
A name, the reviewers (people and groups) and a quorum. A request has up to five steps. Steps run in sequence (the next step opens when the previous one is approved) or in parallel.
Quorum
Any one: one approval is enough. N: N approvals from different people. All: every named person and at least one member of every named group. One person counts once in a step.
Vote
Approve or Request changes, with an optional comment of up to 500 characters. A member of a group votes for the group.
Four eyes
The person who requested an approval cannot approve their own request.
StateWhat it means
PendingA request is open and reviewers are answering.
ApprovedEvery step reached its quorum.
Changes requestedA reviewer asked for changes. Request again when they are made.
CancelledThe request was cancelled by the person who made it or by a space admin.
NoneNothing has been requested.

Request and review

Request an approval

  1. Open the Approval panel of the work item.
  2. Choose Request approval.
  3. Pick a rule of the space, or build the request yourself: steps, reviewers (search for people and groups), quorum and order.
  4. Add a message and, if you like, a due date, and send it.

Reviewers get an email notification through Jira.

Review

  1. Open the work item. If you are a reviewer, the panel offers Approve and Request changes.
  2. Choose one. For Request changes, write what has to change.

When every step reaches its quorum the work item is Approved. A single Request changes ends the round as Changes requested.

Remind and cancel

  • Remind reviewers sends a Jira email notification to the people and groups of the open step, from you, at most once an hour.
  • The person who requested the approval, or a space admin, can Cancel request.

Rules by work type and status

Space admins manage rules in the Space settings. A rule starts an approval by itself. A space can have up to 30 rules.

  1. Open the space settings and the approval rules.
  2. Choose New rule and name it.
  3. Pick the work types. Leave it empty for all work types.
  4. Choose When to start: when a work item is created, when it enters one or more statuses, or both.
  5. Set the steps, the order and the quorum.
  6. Save.
  • When a matching event happens and no approval is running, the rule starts one. The person behind the event counts as the requester.
  • If several rules match, the first by name is used and the others are skipped, so there is only one approval at a time.

Block a transition until approved

The app adds a validator to Jira’s workflow editors: Stepwise: approval is complete. A validator sits on a transition, for example the one into Done, and stops the transition while its condition is not met.

SituationMessage people see
The approval is completeThe transition is allowed.
Approvals are still missingApproval required: 2 approvals are missing.
A reviewer asked for changesApproval required: changes were requested.
Nothing has been requestedApproval required: no approval has been requested yet. Open the Approval panel to request one.
The message MOB-142 can’t move to Done: Approval required, 2 approvals are missing, shown over a work item with two approval steps.
What people see when the validator holds a transition.

Add the validator to a transition

  1. Open the workflow of the work type you want to guard, in the space settings or in Jira’s workflow editor.
  2. Select the transition, for example In review → Done.
  3. Open the transition’s validators and choose to add one.
  4. Pick Stepwise: approval is complete.
  5. Publish or save the workflow.

Jira renames buttons in its workflow editors from time to time, so the labels on your site can differ slightly. The order stays the same: workflow, transition, add a validator, pick the Stepwise validator, publish.

The validator reads the approval from the app’s own storage, which cannot be changed through Jira’s REST API. If the approval cannot be read, the transition does not pass.

Combine the gate with rules: the rule starts the approval when the work item enters a status, the validator makes sure nothing moves on without it.

JQL reference

The app keeps the state of each approval in a work item property that Jira indexes, so you can search it in filters, boards, dashboards and automation. The property holds only the state, the number of missing approvals and the round number, never people.

FieldValueMeaning
stepwiseApprovalText, for example "pending"The state of the current approval
stepwiseApprovalsMissingNumberHow many approvals are still missing

Examples

FindJQL
Work items in reviewstepwiseApproval = "pending"
Work items that still need approvalsstepwiseApprovalsMissing > 0
One space, still missing approvalsproject = REL and stepwiseApprovalsMissing > 0
Releases waiting for approvalissuetype = Release and stepwiseApproval = "pending"

The property is a mirror for search. Decisions, such as the validator, are never taken from it.

The Approvals page and the log

Every space has an Approvals page. Everyone who can see the space can open it. It has two tabs.

Work items tab

The work items of the space that have an approval, with their state and how many approvals are missing.

Log tab

Every event of the space, newest first: the request, each vote, the decision, cancellations and rule changes. Each entry shows the time, the work item and its title, the round, who did it and the details such as step, decision and comment. The history of a single work item is also in its Approval panel.

Entries are linked into a chain with SHA-256, so the log of each space is tamper-evident. Checking the chain is part of Premium.

Premium features

Premium is the Advanced edition of Stepwise Approvals on the Atlassian Marketplace. It is for teams that have to prove what was approved, by whom and when.

Verify the log

Verification recalculates the chain of a space: every hash, every link to the entry before it, no gaps in the numbering and a match with the head of the chain. The answer is either Verified: 1,284 entries, no changes, or the number of the first entry that does not match. Any edit or deletion of an entry is detected. The log is tamper-evident, not a legal electronic signature.

Audit report export

  • Space log: the log of the space for a period as CSV: number, time (UTC), action, work item, person, details, hash and previous hash.
  • Work item report: every round of one work item.

Permissions

Who can do what

The app follows Jira.

ActionWho
See the Approval panel and the historyAnyone who can see the work item
Approve or request changesA reviewer named in the step, who can see the work item. The person who requested cannot approve their own request.
Cancel a requestThe person who requested it, or a space admin
Manage the rules of a spaceSpace admins, in Space settings
Add the validator to a workflowWhoever may edit that workflow in Jira: Jira admins for company-managed spaces, space admins for team-managed spaces
Open the Approvals page of a spaceAnyone who can see the space

What the app is allowed to do

When the app is installed, Jira asks the admin to approve five permissions:

PermissionWhy the app needs it
read:jira-workTo show the Approval panel, to fill the Approvals page of a space, and to ask Jira what the current person may see
write:jira-workTo write the approval state and counters for JQL, and to send the email notification to reviewers
read:jira-userTo search for people and groups when you pick reviewers, to show names at the moment they are displayed, and to know which groups a voting person belongs to
storage:appTo keep approvals, rules and the log in Atlassian-hosted app storage
report:personal-dataTo report stored account IDs to Atlassian every week, as the Marketplace requires

Limits

ItemLimit
Steps in one approval5
Reviewers (people and groups) in one step20
Rules per space30
Comment of a vote, message of a request500 characters each
Name of a rule / name of a step80 / 60 characters

Data and personal data

  • Approvals, rules and the log are stored in Atlassian-hosted app storage (Forge storage), separately for your site.
  • The only thing written to a work item is the property for search: the state, the number of missing approvals and the round number. No names or account IDs.
  • Nothing is sent to any other server. There are no external services, no analytics and no third parties. The data follows your Jira data residency.
  • To know who signed, the app stores the Atlassian account IDs of requesters and reviewers. In approvals, rules and the log a random reference stands in for the ID. It does not store names or emails: names are shown as Atlassian returns them at the moment of display.
  • Account IDs are reported to Atlassian every week. When Atlassian tells the app that an account has been closed, the account ID is erased. The person’s earlier actions stay in the log as “Former user” and the chain still verifies.

More detail: Security and data. Legal wording: Privacy policy.

Troubleshooting

A transition is blocked and I do not know why
Read the message: it says whether approvals are missing, changes were requested or nothing has been requested. Open the Approval panel to act.
I cannot approve my own request
That is by design: the person who requested cannot approve. Ask another reviewer.
A rule did not start an approval
An approval was already running, or another rule matched first by name. Only one approval runs at a time.
JQL does not find a work item
Jira updates its search index shortly after a change. Run the search again in a moment.
Reviewers did not get an email
Check the notification settings of your Jira site and of the reviewer. Press Remind reviewers to send it again.

Not available yet

These are not in the app today. We list them so that you know what not to look for yet. There are no dates attached.

Missing something else? Tell us.