Automating Jira Status Transitions from GitHub Pull Requests, Labels and Milestones

Last updated: November 2026

To automate Jira status transitions from GitHub, put the Jira issue key in every branch name, pull request title or commit message, connect GitHub to Jira so development events are visible, and then map each pull request event to a workflow transition: opened moves the issue to In Review, merged moves it to Done, and reverted or reopened moves it back. Labels and milestones can be synced to Jira components and fix versions with the same event-driven approach. The result is a Jira GitHub integration where nobody updates tickets by hand and the board always reflects what is actually happening in code. For two-way sync of GitHub Issues and Jira issues, ZigiOps, the no-code integration platform by ZigiWave, configures the same mapping in a guided UI.

Most teams that connect GitHub and Jira stop at linking: the development panel shows branches and pull requests, but statuses are still changed by hand, and boards drift. This guide covers the event-to-transition mapping, label and milestone alignment, and the edge cases that break naive automation.

How GitHub events reach Jira

Before designing any rules, it helps to understand the data path. There are three common ways to connect GitHub and Jira, and each exposes events differently.

Ways to connect GitHub and Jira for automated transitions

Approach	How events arrive	Typical use	Main limitation
GitHub for Jira app plus Jira Automation	The app links development data to issues by key; Jira Automation offers development triggers such as "Branch created", "Pull request created" and "Pull request merged"	Teams on Jira Cloud that want rules without code	Logic lives in Jira rules; syncing labels and milestones as fields needs extra rule design
Smart commits	Commit messages containing an issue key plus commands such as #comment, #time or #transition are processed by Jira	Developer-driven updates from the command line	Depends on developers typing commands correctly; transitions are triggered by commits, not by pull request events
Integration platform (for example ZigiOps) or custom webhook service	GitHub webhooks (for example pull_request, issues, label and milestone events) are received and translated into Jira REST API calls	Multi-organization setups, two-way sync of GitHub Issues and Jira issues, governance requirements	Needs hosting or a subscription, plus ownership of the mapping logic

Whichever path you choose, the integration has to answer the same question for every event: which Jira issue does this belong to? The answer is almost always the issue key, so key discipline comes first.

Step 1: Make the Jira issue key impossible to miss

Every automated transition depends on the integration finding a Jira key such as PAY-412 in the GitHub data. If the key is missing, nothing happens, and the issue silently stays in the wrong status. Agree on a convention and enforce it.

• Branch names: start with the key, for example PAY-412-fix-refund-rounding. Branches created from the Jira issue's development panel follow this pattern automatically.
• Pull request titles: include the key at the start, for example "PAY-412 Fix refund rounding". The title survives squash merges, which matters later.
• Commit messages: include the key in at least the first commit. With squash merges, the final commit message is usually generated from the pull request title, so a key in the title is usually enough.

To enforce the convention, add a lightweight check in GitHub Actions or a branch protection rule that fails a pull request when no key pattern is found in the title or branch name. A simple regular expression such as an uppercase project prefix, a hyphen and a number covers most cases. Keep an escape hatch, for example a "no-ticket" label for typo fixes and dependency bumps, so the check does not become a reason to invent fake tickets.

Step 2: Map pull request events to Jira transitions

The core of the design is a table that maps GitHub events to Jira workflow transitions. Write it down before building any rules, and agree it with the team that owns the Jira workflow. The table below assumes a common software workflow: To Do, In Progress, In Review, Done, with Reopened as an optional status.

GitHub pull request event to Jira transition mapping

GitHub event	Webhook detail	Jira transition	Condition
Branch created with issue key	create event (ref_type is branch) or "Branch created" trigger	To Do to In Progress	Only if the issue is in To Do
Draft pull request opened	pull_request opened, draft is true	No transition, add a comment	Keep the issue in In Progress
Pull request opened or marked ready	pull_request opened (draft false) or ready_for_review	In Progress to In Review	Only if the issue is in In Progress
Changes requested in review	pull_request_review submitted, state changes_requested	In Review to In Progress (optional)	Only if the team wants review loops visible on the board
Pull request merged	pull_request closed with merged true	In Review to Done, set resolution	Only if the target branch is the main or release branch
Pull request closed without merge	pull_request closed with merged false	In Review to In Progress	Add a comment explaining the pull request was closed
Pull request reopened	pull_request reopened	In Progress to In Review	Only if the issue is not already Done
Revert merged	New pull request titled "Revert ..." merged	Done to Reopened	Match the original key in the revert title

Why conditions matter

Every row has a condition, and that is deliberate. Without a status check, a late event can move an issue backwards. A classic example is a pull request reopened after the issue was already closed by a different fix. Another is a developer creating a second branch for an issue that is already in review. Always transition from a specific status, never from "any status". In ZigiOps, trigger conditions play the same role: an operation runs only when the source record matches the conditions you set, and conditional mapping decides the target Jira status. In Jira Automation, add an "Issue fields condition" on status before the "Transition issue" action. In a custom service, read the issue's current status and the available transitions through the Jira REST API before calling the transition endpoint.

Target branch filtering

Merging into a feature branch or a long-lived integration branch does not mean the work is done. Filter the merged event by the base branch. A typical rule is: transition to Done only when the base branch is main, master or matches a release pattern such as release/*. For teams that deploy from main several times a day, Done can mean "merged to main". For teams with a release train, consider an intermediate status such as "Merged" or "Ready for Release", and move to Done only when a deployment or release event arrives.

Setting resolution and other fields on Done

In many Jira workflows, moving to Done requires a resolution. If the transition screen asks for a resolution and your automation does not set one, the transition fails or the issue ends up Done with no resolution, which skews reports. Set the resolution in the transition action, usually "Done" or "Fixed". If your workflow has validators that require other fields, such as a fix version, handle them in the same action or relax the validator for the integration user.

Step 3: Sync GitHub labels with Jira components and labels

Labels in GitHub and components or labels in Jira often describe the same thing: the area of the product, the type of work or a priority signal. Keeping them aligned saves triage time, but only if you decide which system owns each value.

GitHub label to Jira field mapping example

GitHub label	Jira field	Jira value	Direction
area:payments	Component	Payments	Jira to GitHub (Jira owns components)
area:mobile	Component	Mobile App	Jira to GitHub
type:bug	Issue type	Bug	Read only in GitHub; never change issue type from a label
needs-qa	Label	needs-qa	Both ways
security	Label plus security level	security, restricted level	GitHub to Jira, with a manual check before widening visibility
blocked	Flagged field	Impediment	Both ways

Rules for label sync

1. Use prefixes. Prefixed labels such as area: and type: make mapping deterministic and keep unrelated labels out of Jira.
2. Map, do not copy. GitHub labels are free text. Copying them into Jira creates near-duplicates such as "Payments", "payments" and "payment". Maintain an explicit mapping table and ignore labels that are not in it.
3. Decide ownership per field. Components are usually managed by a Jira admin, so Jira should own them. Workflow labels like needs-qa can be edited in both places.
4. Handle removal. GitHub sends labeled and unlabeled actions on pull requests and issues. Remember to process unlabeled events, otherwise a removed label stays in Jira forever.

How this works in ZigiOps: once GitHub and Jira are connected, ZigiOps loads both schemas, so labels, components and fix versions are selectable from dropdown lists. Conditional mapping in ZigiOps translates prefixed GitHub labels into Jira components, and labels without a matching condition are simply not sent.

Step 4: Sync GitHub milestones with Jira fix versions

GitHub milestones and Jira fix versions both answer "which release does this belong to?". Syncing them gives release managers one view of scope, but versions have more structure in Jira, including release dates and released or unreleased state.

How this works in ZigiOps: ZigiOps maps the GitHub milestone title to the Jira fixVersions field with an expression or a conditional mapping table. Changes made by the integration user itself are ignored, so a version written to Jira does not bounce back to GitHub as a new update.

GitHub milestone to Jira fix version mapping

GitHub milestone property	Jira version property	Notes
Title, for example "v4.2"	Version name "4.2" or "v4.2"	Normalize the naming once and keep it; mismatched prefixes are the most common cause of duplicates
Due date	Release date	Choose one owner; release managers usually prefer Jira
State open	Unreleased	New milestones can create unreleased versions if your process allows it
State closed	Released	Do not release a Jira version automatically if it still contains open issues
Milestone set on a pull request	Fix version added to the linked issue	Add, do not replace, if the issue can ship in several versions

Two practical warnings. First, automatically creating Jira versions from GitHub milestones can clutter projects with test milestones and typos. A safer pattern is to create versions in Jira and only match existing names from GitHub. Second, closing a milestone is not the same as shipping. If you release a Jira version from a milestone event, add a check that no linked issues remain unresolved, and send a message to the release owner instead of releasing if the check fails.

Edge cases that break naive automation

Squash merges

With squash merging, the individual commits disappear from the main branch and are replaced by a single commit. If your rules depend on keys in commit messages, the key may be lost when the squash message is edited. The pull request title and branch name are more reliable sources. Configure your rule to read keys from the pull request title first, then the branch name, then commits.

Pull requests that reference several issues

A pull request titled "PAY-412 PAY-415 Refactor refund service" can match two issues. Decide whether merging it should close both. A common rule is: transition every issue found in the title, but only those found in the title, not keys mentioned in commit messages or the description, which often reference related work for context. Document this so developers know that putting a key in the title is a statement that the pull request completes it.

One issue, several pull requests

Larger stories often need several pull requests, sometimes across repositories. Moving the issue to Done on the first merge is wrong. Options include using sub-tasks, one per pull request, so each sub-task closes on merge and the parent closes when all sub-tasks are done; or adding a convention such as a "partial" label that suppresses the Done transition. Jira Automation can check whether all linked pull requests are merged before transitioning, but test this carefully with your specific setup.

Reverts

GitHub's revert button creates a new pull request whose title starts with "Revert" and includes the original title. If the original title contained the issue key, the revert does too. Add a rule that detects the revert pattern and transitions the issue from Done to Reopened, with a comment linking to the revert by name. Without this rule, a revert-merge can even trigger your "merged to Done" rule again, which does nothing visible but hides the fact that the fix was rolled back.

Smart commits: useful, but not your main engine

Smart commits such as "PAY-412 #comment fixed rounding #time 2h #transition In Review" are handy for logging time from the terminal. As a transition engine they are fragile: developers must type exact transition names, they fire on commits rather than merges, and the author's email must match a Jira user. Let pull request events drive the workflow instead.

Testing checklist

Test in a sandbox Jira project and a test repository before rolling out. Run through each scenario and record the expected and actual status.

• Create a branch from the Jira issue: the issue moves from To Do to In Progress.
• Open a draft pull request: the issue stays In Progress and receives a comment.
• Mark the pull request ready for review: the issue moves to In Review.
• Request changes: the issue moves back to In Progress if you enabled that rule.
• Merge into a feature branch: the issue does not move to Done.
• Merge into main with a squash merge: the issue moves to Done with a resolution set.
• Close without merging: the issue returns to In Progress with an explanatory comment.
• Revert the merged pull request: the issue moves to Reopened.
• Add and remove an area: label: the Jira component updates both times.
• Set a milestone on the pull request: the matching fix version is added to the issue.
• Open a pull request with two keys in the title: both issues transition on merge.

Troubleshooting

Common problems with GitHub-driven Jira transitions

Symptom	Likely cause	Fix
Issue never moves	No key found, or key in lowercase	Enforce the key check; normalize case before matching
Rule runs but transition fails	Transition not available from the current status, or required field missing	Check the workflow; set resolution and required fields in the action
Issue moves backwards unexpectedly	Rule transitions from any status	Add a status condition to every rule
Duplicate components or versions	Free-text copying instead of mapping	Use an explicit mapping table and match existing values only
Rule fires twice	Two rules or two integrations listening to the same event	Consolidate rules; check for overlapping apps or webhooks
Permission error in the audit log	Rule actor lacks transition permission in the project	Grant the automation or integration user the required project permissions

Jira Automation's audit log shows each rule execution and the reason it failed. For webhook-based services, log the GitHub delivery ID with every Jira call so you can trace a status change back to the exact event. GitHub's webhook settings also let you redeliver a failed delivery, which is useful when testing fixes.

Choosing a tool

For a single GitHub organization and Jira Cloud, the GitHub for Jira app plus Jira Automation covers the transition mapping in this guide with no code. When you need two-way sync between GitHub Issues and Jira issues, several GitHub organizations or Jira Data Center, or central governance over many rules, ZigiOps is a standalone no-code option. ZigiOps connects to both systems through their APIs, syncs issues, comments and attachments in both directions, applies trigger conditions and conditional mapping in its UI, and does not store transferred data. Other platforms such as Exalate, Getint or Unito, or a small custom webhook service, are alternatives. Compare them on how they handle event filtering, field mapping tables, status conditions and error visibility, because those are the parts that make or break the automation described here.

Frequently asked questions

Can GitHub automatically change a Jira issue status?

Yes. With the GitHub for Jira app connected, Jira Automation can trigger on development events such as "Pull request merged" and run a "Transition issue" action. Integration platforms and custom webhook services can do the same using GitHub webhooks and the Jira REST API.

How do I connect Jira to GitHub so pull requests show on issues?

Install and configure the GitHub for Jira app for your Jira Cloud site, connect your GitHub organization, and include the Jira issue key in branch names, pull request titles or commit messages. Linked development data then appears in the issue's development panel.

What is the best transition to trigger on a merged pull request?

Transition to Done only when the pull request merges into your main or release branch, and set a resolution in the same action. If you release on a schedule, use an intermediate status such as Ready for Release instead.

Should GitHub labels sync to Jira labels or components?

Map prefixed GitHub labels to specific Jira fields: area labels to components, workflow labels to Jira labels, and blockers to the Flagged field. Use an explicit mapping table rather than copying label text.

Can ZigiOps sync GitHub issues and Jira issues in both directions?

Yes. ZigiOps creates and updates GitHub issues and Jira issues in both directions, including comments, labels and milestones mapped to Jira fields. Status, component and fix version rules are set with trigger conditions and conditional mapping in its no-code UI.

How do I stop a revert from leaving an issue marked Done?

Add a rule that detects merged pull requests whose title starts with "Revert", extracts the original issue key and transitions the issue from Done to Reopened with a comment.

Key takeaways

• A reliable Jira GitHub integration starts with key discipline in branch names and pull request titles.
• Write an event-to-transition mapping table before building rules, and add a status condition to every rule.
• Filter merges by target branch so only main or release merges move issues to Done, and always set the resolution.
• Sync labels and milestones through explicit mapping tables with clear ownership, and process removals as well as additions.
• Plan for squash merges, multi-issue pull requests, multi-pull-request issues, reverts and bots before go-live.
• Test every scenario in a sandbox and use audit logs and webhook delivery IDs to troubleshoot.
• For two-way GitHub Issues and Jira sync across organizations, ZigiOps configures labels, milestones and status rules without code.