How can I set up a custom workflow in Jira Software for my project?

SUCCESS K IHEANACHO

I’m working on a Jira Software project and need to create a workflow that includes custom statuses (e.g., In Review, QA Testing, Ready for Release). I’ve tried editing the default workflow, but I’m running into issues where transitions don’t appear as expected. I’d like guidance on:  

- Best practices for creating custom workflows  

- How to ensure transitions are visible to all team members  

- Any limitations I should be aware of when modifying workflow

s  

Sebastian Quesada Ocampo

When working with Jira workflows, the behavior you’re seeing is quite common. Here are some best practices and key things to check: 

Best practices for creating custom workflows 

• Copy the default workflow instead of editing it directly. This avoids unexpected side effects, especially if it’s shared across projects.
• Keep workflows as simple as possible—too many statuses or transitions can confuse users.
• Name statuses clearly and consistently (e.g., In Review, QA Testing, Ready for Release).
• Use transition screens only when needed (for required fields, approvals, etc.). 

 

Ensuring transitions are visible to all team members

If transitions are not appearing, check the following:

• Transition conditions: If a transition has conditions (e.g., “Only users in role X”), users who don’t meet them won’t see the transition.
• Workflow status category: Make sure custom statuses are mapped correctly to To Do, In Progress, or Done.
• Issue type workflow scheme: Confirm the issue type you’re testing is actually using the workflow you modified.
• Permissions: Users must have Transition Issues permission (usually included by default, but worth verifying). 

Limitations and things to be aware of 

• Active workflows cannot be fully edited. Structural changes require creating a draft and publishing it, which may affect existing issues.
• If the workflow is shared across projects, changes will impact all of them.
• Publishing workflow changes may require re-mapping statuses for existing issues.
• Some transitions may appear hidden simply because they are not valid from the current status. 

Pro tip

If a transition doesn’t show up: 

• If you’re an admin. Log in as a user who can’t see it and inspect the transition’s conditions, validators, and post-functions.
• Temporarily remove conditions to confirm whether visibility is the issue.