A Jira workflow is the sequence of statuses an issue moves through from creation to completion, connected by transitions. Configure workflows via Settings → Issues → Workflows. Add statuses, connect them with transitions, then add conditions (who can execute a transition), validators (what data is required), and post functions (what happens automatically after). Associate the workflow with a workflow scheme, then assign the scheme to your project.
Most Jira teams start with the default workflow — To Do, In Progress, Done — and never touch it again. That works until it doesn’t: when QA needs its own stage, when you need to prevent issues from being closed without a resolution set, or when different issue types need different processes.
This guide covers everything you need to configure Jira workflows yourself — from creating a basic custom workflow to setting up conditions, validators, and post functions without breaking what already works.
A Jira workflow has four components:
| Component | What it is | Example |
|---|---|---|
| Status | A stage an issue can be in | To Do, In Progress, In Review, Done |
| Transition | A movement from one status to another | “Start Review” moves issue from In Progress → In Review |
| Condition | A rule that controls who can execute a transition | Only the assignee can move an issue to Done |
| Validator | A check that runs before a transition completes | Resolution field must be set before closing |
| Post function | An action that runs automatically after a transition | Set resolution to “Fixed” when moved to Done |
Workflows live at the global level in company-managed projects — they’re created in Settings, then linked to projects via a workflow scheme. In team-managed projects, workflow configuration is simpler and done directly from the board settings.
Before touching anything, check which project type you’re working with. The configuration paths are completely different.
| Company-managed | Team-managed | |
|---|---|---|
| Who can edit workflows | Jira administrator only | Project administrator |
| Where to edit | Settings → Issues → Workflows | Project Settings → Workflows (board columns) |
| Workflow scope | Shared across projects via scheme | Per-project only |
| Conditions and validators | Yes, full support | No — simplified only |
| Post functions | Yes, full support | No |
To check your project type: open the project → Project Settings → look for “Project type” or check whether you see an “Issue types” section (company-managed) or a simple board columns view (team-managed).
Statuses in Jira are global — they exist at the instance level and can be shared across workflows. When you add a status to a workflow, you’re referencing the global status, not creating a local one.
Adding a new global status:
Status categories matter more than status names. An issue in “In QA” won’t close the sprint report line unless “In QA” is mapped to the Done category. An issue in “Blocked” won’t stop counting as In Progress unless Blocked is explicitly in the In Progress category. Get this wrong and your Scrum reports will misrepresent actual delivery.
For a full breakdown of how status categories affect Jira’s native Scrum reports, see: Jira Scrum Reports: What Each One Shows and When to Use It.
A transition connects two statuses and defines the path an issue can take. Every transition has a name (what the user sees as a button), a source status (where the issue is now), and a destination status (where it goes).
Global transitions allow an issue to move to a status from any other status — useful for “Close” or “Reopen” transitions that should be accessible from anywhere in the workflow.
Directed transitions only appear when the issue is in a specific status — useful for sequential processes like code review that should only happen after development.
To add a transition in the workflow editor: hover over a status → drag the blue arrow to the destination status → name the transition. To create a global transition: right-click a status → “Allow all statuses to transition here.”
Each transition can optionally display a screen when executed — prompting the user to fill in fields before the transition completes. Common uses: requiring a resolution when closing, requiring a comment when rejecting, requiring an assignee when assigning to QA.
To attach a screen: click on the transition → Edit → select a screen from the dropdown. Screens are configured separately in Settings → Issues → Screens.
A condition is a rule that determines whether a user sees a transition button at all. If the condition is not met, the transition is hidden from that user — they can’t execute it.
Common conditions and when to use them:
| Condition | Use case |
|---|---|
| Only Assignee | Only the person assigned to the issue can move it to Done |
| User is in group | Only QA engineers (a specific group) can move issues to Approved |
| User has role in project | Only users with the Developer role can start work |
| Sub-tasks complete | Issue can’t be closed until all sub-tasks are Done |
| Permission condition | Restrict based on a specific Jira permission |
To add a condition: click on a transition in the workflow editor → Conditions → Add condition → select from the list → configure and save.
A validator runs after the user clicks a transition button but before the transition completes. If validation fails, the user sees an error message and the issue stays in its current status.
Unlike conditions (which hide the button), validators show the button to everyone but block execution until requirements are met.
Common validators:
| Validator | Use case |
|---|---|
| Field required | Resolution, Fix Version, or any custom field must be set before closing |
| Regular expression | A field value must match a specific format (e.g., a branch name pattern) |
| User permission | User must have a specific permission to proceed |
| Date field comparison | Due date must be set and in the future before scheduling |
To add a validator: click on a transition → Validators → Add validator → configure and save.
Post functions run automatically after a transition completes successfully. They execute in order — if one fails, subsequent post functions may not run.
Every transition has a set of default post functions that Jira adds automatically (updating issue history, firing events). Don’t delete these — they’re required for core Jira functionality.
Useful post functions to add:
To add a post function: click on a transition → Post Functions → Add post function → select and configure → position it correctly in the execution order using the up/down arrows.
Creating a workflow isn’t enough — you need to link it to a project via a workflow scheme.
A workflow scheme maps issue types to workflows. For example:
To create or edit a workflow scheme:
To associate a scheme with a project:
If you’re on a team-managed project, workflow configuration is much simpler — and more limited.
There are no conditions, validators, or post functions in team-managed projects. If you need those, the project needs to be a company-managed project — migration between project types is not straightforward and typically requires recreating the project.
After configuring workflows across hundreds of Jira implementations, the same mistakes come up repeatedly:
Workflow decisions have direct consequences for reporting. Three things to know:
Status categories drive Scrum reports. The burndown chart drops when issues move to the Done category — not when they move to a specific status name. If your “Deployed” status is mapped to In Progress rather than Done, those issues keep counting as open work on the burndown chart.
Time in status depends on workflow history. Every transition creates a timestamp in the issue’s history. If you need cycle time, lead time, or time-in-status reports, the workflow needs to accurately reflect when work actually moves between stages — not when someone remembers to update the status.
Scope change reports read sprint changes. Issues added to a sprint after it starts show as scope changes in the Sprint Report. Workflow transitions don’t affect this — but if your workflow has a “Pulled into Sprint” status that bypasses the standard flow, it can create gaps in sprint data.
For a complete guide to Jira’s native reporting and how your configuration choices affect each report, see: Jira Scrum Reports: What Each One Shows and When to Use It and Jira Metrics and Team Reports: What to Track and How to Get It.
Go to Settings → Issues → Workflows → click Add workflow to create a new one, or Edit on an existing one. Add statuses, connect them with transitions, then add conditions, validators, and post functions as needed. Publish the workflow, add it to a workflow scheme, and assign the scheme to your project.
A condition controls who can see and execute a transition — if the condition fails, the button is hidden. A validator checks whether issue data meets requirements before allowing the transition — if it fails, the user sees an error but the button remains visible. Use conditions to restrict access, validators to enforce data completeness.
A workflow scheme maps specific workflows to specific issue types within a project. For example, Stories use one workflow and Bugs use another. The scheme is then assigned to the project as a whole. Company-managed projects require workflow schemes; team-managed projects have simplified built-in workflow controls.
In team-managed projects, project administrators can add and rename board columns (statuses) without global admin access. In company-managed projects, workflow changes require Jira administrator access — project admins cannot modify workflows or workflow schemes directly.
In the workflow editor (Settings → Issues → Workflows → Edit), click Add status. You can create a new global status or reuse an existing one. After adding, connect it with transitions. Remember to also add the new status to the relevant board column in board settings — adding it to the workflow does not do this automatically.
A post function is an action that runs automatically after a transition completes. Common examples: setting the Resolution field when closing, assigning to current user when starting work, sending a notification, or triggering a webhook. Post functions run in sequence — position them carefully using the up/down arrows in the transition editor.
Jira workflow configuration gives you precise control over how issues move through your process — who can move them, what data is required, and what happens automatically. The four key elements are statuses (where issues can be), transitions (how they move), conditions (who can move them), and validators and post functions (what’s checked and automated along the way).
Start simple. A workflow with five well-named statuses and clear transitions is easier to maintain and less likely to create user confusion than one with fifteen statuses and complex conditions. Add complexity only when the team consistently needs something the current workflow can’t handle.
If you need help configuring Jira for your team’s specific workflow or want a review of your current setup, Grandia Solutions offers Jira administration and configuration services for teams that want it done right the first time.
Ready to Elevate Your Jira Setup?
Partner with Grandia Solutions to unlock expert configuration, reporting, and support services — tailored to your workflows. Whether you need custom dashboards, workflow automation, or long-term consulting, our team is here to make Jira work for you.