A state-machine engine for tracking work at any scale
Jira is Atlassian's work-tracking platform. Under the hood it is a sophisticated issue tracker with a configurable state-machine engine: every piece of work (a bug, a story, a task) is an issue that moves through a workflow of statuses. Teams configure exactly who can move it, under what conditions, and what happens automatically when they do.
Everything in Jira is organised hierarchically: a Site contains Projects, projects contain Issues, issues can have Sub-tasks. Above issues sit Epics and optionally Initiatives. Configuration lives at every level — global schemes trickle down to project-level overrides.
Jira offers two project types: Company-managed (classic — full configuration control, workflow schemes, permission schemes) and Team-managed (next-gen — simpler, self-contained, fewer knobs). Most enterprises use company-managed.
Why the state-machine model matters
In a spreadsheet you can type any status. In Jira only defined transitions can move an issue between statuses. This creates an auditable, enforced process — validators block bad transitions before they happen, post-functions automate work after they succeed.
This is the key insight: Jira is not just a list of tickets. It is a process enforcement engine wrapped in a collaboration interface.
// Jira entity hierarchy
Feature
Jira
Linear
GitHub Issues
Custom workflows
Full state-machine
Structured but simpler
Labels only
Validators / Conditions
Yes (per transition)
No
No
Post-functions
Yes (automation)
Automation rules
Actions / webhooks
Scrum boards
Native
Native
Third-party
Permission schemes
Granular
Role-based only
Repo/org roles
JQL / advanced queries
Full JQL language
Filter syntax
Search syntax
02 / Issue Hierarchy & Types
Everything is an issue — but not all issues are equal
Jira's fundamental unit is the issue. Issues have a type that determines their hierarchy level, available fields, workflow, and behaviour on boards. The hierarchy is Epic → Story → Task/Bug → Sub-task, with Initiatives above epics in Jira Align / Advanced Roadmaps.
A large body of work spanning multiple sprints. Epics group related Stories. They have their own status tracking and appear on roadmaps. Story Points don't apply directly — epics track progress via child completion.
Example: "Q2 Mobile Payments Overhaul" — contains 8 Stories, tracked on Roadmap view.
Story
A user-facing feature or requirement written from the user's perspective. The primary unit of sprint planning. Stories have Story Points for estimation and belong to an Epic. "As a [user] I want [feature] so that [benefit]."
Example: "As a shopper, I want to filter products by price so that I can find items in my budget."
Task
A technical work item not necessarily user-facing. Used for infrastructure work, DevOps tasks, refactoring, research spikes. Can be standalone or linked to a Story. Also supports Story Points.
Example: "Upgrade PostgreSQL from 14 to 16 across all staging environments."
Sub-task
A child issue of a Story, Task, or Bug. Breaks work into granular pieces assignable to different team members. The parent issue is only "done" when all sub-tasks are resolved (enforced by validators).
A defect in existing functionality. Bugs typically have their own workflow with extra statuses like "Testing" and "Verified". They have additional fields: Affected Version, Environment, Steps to Reproduce.
Example: "BUG-247 — Login button unresponsive on iOS 17.2 with dark mode enabled."
Incident
Jira Service Management issue type for production incidents. Has SLA fields, responder roles, and severity levels. Linked to Problem records. Triggers on-call notifications via Opsgenie integration.
Full details, screenshots, code blocks. Supports @mentions, smart links.
Assignee
User Picker · Single
Who is responsible for completing the issue. Can be required by validators on transitions.
Reporter
User Picker · Auto-set
Who created/raised the issue. Auto-set to current user. Used in post-function notifications.
Priority
Priority Picker
Blocker / Critical / Major / Minor / Trivial. Used in JQL filters and SLA routing.
Status
Workflow-controlled
Current workflow state. Changed only via transitions — never edited directly.
Resolution
Resolution Picker
Set on Done-category transitions. Fixed / Won't Fix / Duplicate / Cannot Reproduce / Done.
Labels
Label Picker · Multi
Free-form tags. Searchable via JQL. Not hierarchical — use Components for structure.
Components
Component Picker · Multi
Sub-areas of the project (Frontend, API, Auth). Can have default assignees per component.
Fix Version
Version Picker · Multi
Which release will include this fix. Used for release notes and burndown by version.
Story Points
Number (custom field)
Fibonacci-scale estimate of complexity. Summed for sprint velocity. Not hours.
Sprint
Sprint Picker
Which sprint this issue is in. Set during sprint planning. Used by Scrum board filtering.
Linked Issues
Issue Link
blocks / is blocked by / relates to / duplicates / is cloned by. Validators can check these.
Due Date
Date Picker
Deadline. Used by SLA rules in Service Management. Highlighted red when breached.
Watchers
User List
Users notified on changes. Post-functions can send notifications to all watchers.
Time Tracking
Original / Remaining / Logged
Estimated vs logged hours. Remaining estimate updates as work is logged.
Priority Levels
Priority
Meaning
Response SLA
Blocker
Stops work completely. No workaround.
Immediate
Critical
Major function broken, workaround exists.
Same day
Major
Significant impact, degraded functionality.
Next sprint
Minor
Small impact, cosmetic or edge case.
Backlog
Trivial
Nice-to-have, minimal user impact.
Icebox
Resolution States
Resolution
When Used
Fixed
The defect/story was implemented and verified.
Done
General-purpose "completed" — for tasks/stories.
Won't Fix
Valid issue but intentionally not being fixed.
Duplicate
Another issue already tracks this. Link to original.
Cannot Reproduce
Could not replicate the reported problem.
Incomplete
Insufficient information to proceed.
Deferred
Valid, pushed to a future release/sprint.
03 / The Workflow Engine
Workflows: the heartbeat of Jira
A Jira workflow is a finite state machine attached to an issue type. It defines the set of statuses (nodes) an issue can be in, and the transitions (directed edges) that move it between them. Every transition is a gate — it can be guarded by conditions, validated before execution, show a screen, and fire automated actions afterward.
// Software bug workflow — state machine diagram
The Anatomy of a Transition
Every transition has four configurable components that fire in order when a user attempts to move an issue:
Pillar 01
Conditions
"Who is allowed to do this?"
Conditions determine who can see and trigger a transition. If a condition fails, the transition button is hidden from that user — they don't even know it exists. Checked before the transition dialog opens.
Only users in role: Developer
Only the current assignee
Only users with RESOLVE permission
User is a member of group: qa-team
Issue has no unresolved sub-tasks
Sub-task of parent has specific status
Pillar 02
Validators
"Is the issue ready for this?"
Validators run when the user submits the transition. If validation fails, an error is shown and the issue stays in the current status. Unlike conditions, the user sees the button — validation catches data quality issues.
Field required: Fix Version, Assignee
Field has value: Story Points > 0
At least one comment required
All subtasks must be resolved
Regex validator: Summary matches pattern
Permission validator: has RESOLVE_ISSUES
User is watcher on issue
Pillar 03
Screens
"What data to collect?"
A screen defines which fields are shown in the transition dialog. Different transitions can show different fields. Screens are configured separately and linked to transitions via Transition Screens in the workflow editor.
No screen (silent transition)
Resolution + Comment fields
Assignee + Original Estimate
Fix Version + Priority
Comment (reason for rejection)
Custom fields for QA sign-off
Pillar 04
Post-functions
"What happens automatically after?"
Post-functions execute after a successful transition. They automate downstream work — updating fields, sending notifications, triggering webhooks, creating linked issues. Always include "Update issue status" as the first post-function.
Update issue status (required, first)
Set Resolution field = Fixed
Assign issue to current user
Fire webhook to CI/CD pipeline
Send email to reporter/watchers
Copy field value to another field
Create/trigger sub-task
Log work with comment
Deep dive: Validators vs Conditions — the key difference
Conditions are evaluated when the page renders — the button is hidden if the condition fails. The user has no awareness that the transition exists. Use conditions to restrict who can act (role-based, permission-based).
Validators run at submission time — the user sees the button, opens the dialog, fills in fields, and then validation happens. Errors are shown inline. Use validators to enforce data quality (required fields, business rules, dependency checks).
A common mistake: using validators for role checks. This creates a confusing UX — users see a transition they can't complete. Always use conditions for permission/role gating, validators for data/state validation.
Built-in Validators (no scripting required)
Field Required Validator — Ensures a specified field has a value before the transition completes. Most common validator. E.g., "Fix Version must be set before resolving."
Permission Validator — Checks that the user has a specified Jira permission (e.g., RESOLVE_ISSUES, CLOSE_ISSUES). Different from conditions — this still shows the button but blocks non-permitted users at submit time.
User Permission Validator — Checks the user stored in a field (e.g., Assignee) has a specific permission.
ScriptRunner / Groovy Validators — With the ScriptRunner plugin, you can write arbitrary Groovy: "All sub-tasks resolved", "Story points > 0", "Fix version exists and is unreleased", "PR is merged in Bitbucket" etc. These are the most powerful — any business rule you can express in code.
Workflow Schemes — connecting workflows to projects
Workflows don't attach directly to projects. Instead, a Workflow Scheme acts as a mapping table: it specifies which workflow to use for each issue type. The scheme is then attached to a project. Multiple projects can share the same scheme.
// Workflow scheme — mapping chain
Status Categories
Every status belongs to one of three status categories. Categories control how issues are counted on reports, burndown charts, and boards. You can rename statuses but you cannot change their category once set.
To Do
Work not yet started. Shows as grey on boards and charts. Examples: Open, To Do, Backlog, Reopened, Reported, New. Issues in this category have no "in progress" date set.
In Progress
Work actively being done. Shows as blue on boards. Examples: In Progress, In Review, Testing, Under Investigation, Waiting for Customer. Jira tracks "time in status" for these.
Done
Work complete. Shows as green, counted in velocity and burndown. Examples: Resolved, Closed, Done, Won't Fix, Duplicate. A resolution should always be set when reaching Done category.
04 / Roles & Permissions
Who can do what — and where it's controlled
Jira has a two-tier permission model: global permissions (site-wide, set by Jira Admins) and project permissions (per project, configured in Permission Schemes). Within projects, project roles are the bridge between users/groups and permission grants.
// Jira role and permission hierarchy
Project Role Capabilities
Permission
Proj Admin
Developer
SD Team
Reporter
Viewer
Browse / View Project
✓
✓
✓
✓
✓
Create Issues
✓
✓
✓
✓
✗
Edit Issues
✓
✓
✓
own only
✗
Assign Issues
✓
✓
✓
✗
✗
Transition Issues
✓
✓
✓
limited
✗
Resolve Issues
✓
✓
✓
✗
✗
Close Issues
✓
✗
✓
✗
✗
Delete Issues
✓
✗
✗
✗
✗
Manage Sprints
✓
start/complete
✗
✗
✗
Administer Project
✓
✗
✗
✗
✗
Add Comments
✓
✓
✓
✓
✗
Log Work
✓
✓
✓
✗
✗
View Dev Tools
✓
✓
✗
✗
✗
Set Issue Security
✓
✗
✗
✗
✗
Move Issues
✓
if permitted
✗
✗
✗
Issue Security Schemes
Beyond project-level permissions, Jira supports Issue Security Levels that hide individual issues from users who don't have that security level. Example: a "Confidential" level only visible to Project Admins and Reporters. Set via the Issue Security Scheme attached to the project. Individual issues have a "Security Level" field. Critical for GDPR/compliance use cases.
How Permission Schemes work in practice ▼
A Permission Scheme is a named list of (permission → grantee) mappings. Grantees can be: a project role, a group, a specific user, "Current Assignee", "Reporter", "Project Lead", "Any logged-in user", or "Anyone" (public). The scheme is attached to one or more projects. Changing the scheme instantly affects all linked projects. You can clone a scheme before modifying — this is best practice when only one project needs a change.
Global Permissions vs Project Permissions ▼
Global permissions are site-wide: "Jira Administrators" can configure everything. "Jira Software Users" can access Jira Software at all. "Jira Service Management Agents" gives access to the service desk. Project permissions are per-project and controlled by the permission scheme. The interaction: a user must first have global access, then project permissions determine what they can do within that project.
Custom project roles ▼
Jira Admins can create custom project roles beyond the defaults (Administrators, Developers, Service Desk Team, etc.). Example: "QA Engineers" role with Resolve Issues + Add Comments but not Close Issues. Role membership is per-project — the same person can be a Developer in SHOP but a Viewer in INFRA. This is key: roles are templates, memberships are project-specific.
05 / Boards: Scrum vs Kanban
Two philosophies for visualising and managing flow
Jira boards are views over issues, not separate data stores. The same issues exist in the project — the board simply filters and presents them by status. Scrum boards are time-boxed (sprint-based); Kanban boards are continuous flow. You choose based on how your team works.
Scrum BoardSprint-based
⏱
Time-boxed sprints (1–4 weeks)
Each sprint has a goal, a start date, and an end date. Work is committed to the sprint during planning.
📋
Backlog + Active Sprint views
Issues live in the backlog until moved to a sprint. Backlog can be groomed (estimated, prioritised) separately from the board.
⚡
Story Points & Velocity
Team's average story points completed per sprint = velocity. Used to forecast future sprints.
🔥
Sprint Burndown Chart
Shows remaining story points over sprint days. Ideal burndown is a straight diagonal line.
At sprint end, incomplete issues can be moved to the next sprint or returned to backlog.
Kanban BoardContinuous flow
∞
No sprints — continuous delivery
Work flows in as capacity allows. No fixed time boxes. Good for support, ops, or teams with unpredictable work.
🚦
WIP (Work In Progress) Limits
Each column has a max WIP limit. When reached, the column highlights red. Forces finishing before starting new work. Core lean principle.
📊
Cumulative Flow Diagram
Shows issues in each status over time. Widening bands = bottleneck in that stage. Ideal: parallel bands (steady flow).
⏳
Cycle Time & Lead Time
Lead time = from creation to done. Cycle time = from start to done. Lower and more consistent = better.
🏊
Swimlanes
Horizontal lanes by Assignee, Epic, Label, Priority, or custom JQL query. Help visualise work distribution.
🔄
Backlog is optional
Kanban can have a backlog column or not. Backlog issues don't appear on the board until explicitly moved to an active column.
// Scrum sprint ceremony cycle
Board Configuration
Column Mapping ▼
Columns are logical containers — multiple workflow statuses can map to the same column. Example: "In Progress" column can contain both "In Progress" and "Blocked" statuses. This decouples the board display from the underlying workflow. Board columns are configured in Board Settings → Columns.
Swimlanes ▼
Swimlanes create horizontal lanes across the board. Options: by Assignee (each person gets a row), by Epic (group stories by epic), by Label, by Priority, or a custom JQL query. Example: swimlane "Bugs" uses JQL issuetype = Bug. Unmatched issues fall to "Everything Else" lane.
Quick Filters ▼
Buttons above the board that filter visible cards. Configured as JQL expressions. Example: "My Issues" = assignee = currentUser(), "Blockers" = priority = Blocker. Multiple filters combine with AND. Very useful for standups and focus sessions.
Card Layout ▼
Configures what fields appear on issue cards on the board. By default: summary, issue type, priority, assignee avatar, story points. You can add up to 3 extra fields: e.g., components, labels, due date, fix version. More data visible = less clicking into issues.
Scrum vs Kanban — When to Use
Factor
Scrum
Kanban
Work predictability
Predictable, plannable
Unpredictable / ad-hoc
Team type
Product dev team
Support / ops / infra
Delivery cadence
Fixed sprint release
Deploy on completion
Estimation
Required (story points)
Optional
Ceremonies
Planning, review, retro
None mandated
WIP limits
Implicit (sprint cap)
Explicit per column
Progress metric
Velocity, burndown
Cycle time, CFD
Backlog grooming
Critical, regular
Optional
06 / JQL — Jira Query Language
SQL for your project data
JQL (Jira Query Language) is Jira's query language for searching issues. Every filter, board, dashboard gadget, and automation trigger uses JQL under the hood. It follows a simple field operator value grammar, supports boolean logic, ordering, and a rich library of built-in functions.
// JQL query anatomy
Operators
Operator
Meaning
Example
=
Exact match
status="In Progress"
!=
Not equal
priority!=Trivial
IN
In a list
statusIN("Open","In Progress")
NOT IN
Not in list
assigneeNOT IN("alice","bob")
~
Contains (text)
summary~"login button"
!~
Does not contain
description!~"TODO"
> < >= <=
Comparison
created>=-7d
IS
Is null/empty
fixVersionISEMPTY
IS NOT
Is not null
assigneeIS NOTEMPTY
WAS
Was ever in state
statusWAS"In Review"
WAS IN
Was ever in list
statusWAS IN("Blocked","Parked")
CHANGED
Field changed
assigneeCHANGEDAFTER-3d
Built-in Functions
Function
Returns
currentUser()
The logged-in user's username
membersOf("group")
All members of a Jira group
now()
Current datetime
startOfDay() / endOfDay()
Start/end of today
startOfWeek() / endOfWeek()
Start/end of this week
startOfMonth()
First day of this month
openSprints()
All currently active sprints
closedSprints()
All completed sprints
futureSprints()
Sprints not yet started
latestReleasedVersion("PROJ")
Most recent released version
unreleasedVersions("PROJ")
All unreleased versions
issueHistory()
Issues recently viewed by user
watchedIssues()
Issues current user watches
votedIssues()
Issues current user voted on
linkedIssues("key","type")
Issues linked by link type
Real-world JQL Queries
-- My open work this sprint project=SHOPANDsprintINopenSprints()ANDassignee=currentUser()ANDstatus!=DoneORDER BYpriorityASC
-- Blockers and criticals needing attention now priorityIN(Blocker, Critical)ANDstatusNOT IN(Resolved, Closed, Done)ANDprojectIN(SHOP, API, MOBILE)ORDER BYupdatedDESC
-- Issues that moved to Done in the last 7 days (sprint velocity report) project=SHOPANDstatusCHANGEDTO"Done"AFTER-7dANDissuetypeIN(Story, Bug, Task)
-- Tech debt backlog items without a fix version labels="tech-debt"ANDfixVersionISEMPTYANDstatusNOT IN(Done, Closed)ORDER BYcreatedASC
-- Bugs that were ever in "In Review" for a specific version — regression check issuetype=BugANDstatusWAS"In Review"ANDaffectedVersion="2.4.0"ANDproject=SHOP
-- Issues assigned to my team and overdue (SLA breach risk) assigneeINmembersOf("backend-squad")ANDdueDate<now()ANDstatusNOT IN(Resolved, Closed, Done)ORDER BYdueDateASC
-- Issues resolved in last sprint but with no fix version set (missing release tag) sprintINclosedSprints()ANDstatusIN(Resolved, Done)ANDfixVersionISEMPTYORDER BYresolvedDESC