Jira Smart Commits with GitHub: syntax, requirements, and why they do not run
On this page
A Smart Commit is a commit message that does more than mention a Jira issue: it can add a comment, log time, or move the issue through its workflow. When it works, it saves a trip to Jira. When it does not, nothing tells the developer why: the commit shows up on the issue, and the command is silently ignored. This page sums up what Atlassian documents about Smart Commits, read on 2 November 2026, and the checks to run when one does not work.
The three commands
From Atlassian’s page Process work items with smart commits:
| Command | Example | What it does |
|---|---|---|
#comment |
CHK-42 #comment Fixed the rounding error |
Adds a comment to the issue |
#time |
CHK-42 #time 1d 2h 30m Investigation |
Logs work (w, d, h, m, decimals allowed); the text after the time becomes the work log comment |
#<transition> |
CHK-42 #start-progress |
Moves the issue through a transition of its workflow |
Commands can be combined on one line and applied to several issues at once:
CHK-42 CHK-43 #time 2h #comment Ready for review #start-review
The rules that trip people up
- One line per command. “A Smart Commit command must not span more than one line”, and each
line of the message must follow the syntax on its own. A
#timeon a second line, with no issue key on that line, is not logged. - Issue keys in upper case. Atlassian describes a key as “two or more uppercase letters,
followed by a hyphen and the work item number”.
chk-42 #commentdoes nothing. - Transition names. Jira “only considers the part of a transition name before the first space”.
If two transitions start with the same word (Start progress and Start review),
#startis ambiguous: write#start-progressor#start-review. - Required fields. “If any other fields have been set as required the transition command will silently fail.” A transition that opens a screen asking for a field cannot run from a commit.
- Resolution.
#resolvecannot set the Resolution field. - Time tracking must be enabled on the site for
#timeto work.
The rule behind most failures: the email address
This is the one that matters most, and the least visible. Jira runs a command as a Jira user, and finds that user by the commit’s email address: it “must match the email address of a single Jira Software user” who has the permission the command needs (comment, log work, or transition in that project). “Exactly one”: if no Jira account, or two, use that address, the command does not run.
On GitHub, that address is the one in your local Git configuration when you commit, not the one on your GitHub profile. Check it with:
git config user.email
Three common mismatches:
- you commit with a personal address and log in to Jira with your work address;
- you commit with GitHub’s private
…@users.noreply.github.comaddress, which is rarely the address of a Jira account; - your Jira site hides or manages email addresses differently from what you expect: ask a Jira admin which address your account carries.
When a Smart Commit fails, Atlassian says Jira emails the Jira user, or the user of the connected tool if it cannot find one, and “in rare cases … the Smart Commit fails silently”. The commit itself still appears on the issue either way.
Checklist when a Smart Commit does nothing
- Does the commit appear on the issue at all (Development panel)? If not, the problem is the link, not the command: see GitHub commits not showing in Jira.
- Is the issue key in upper case, on the same line as the command?
- Does
git config user.emailmatch exactly one Jira account, with the right permission? - For a transition: is the name unambiguous, and does the transition require no field?
- For
#time: is time tracking enabled? - Are Smart Commits enabled for that repository? For repositories linked through Jira’s DVCS accounts screen, Atlassian puts the switch there (Settings › Apps › DVCS accounts), enabled by default for new repositories.
A word on security
Git lets anyone write any name and email address in a commit. Atlassian’s page on enabling Smart Commits says so: “Elevated access rights in Jira apps can result from the way that Git … allow[s] commits” to be attributed to other users, and it suggests disabling Smart Commits if that is a risk for you. Concretely, someone with push access to a repository could write a commit in a colleague’s name and transition an issue as that colleague.
How Linkwright handles Smart Commits
Linkwright sends commits to Jira’s own Development panel, and since version 2.17.0
(2 November 2026) it lets Jira run their Smart Commits. We tested it on our own Jira site on
2 November 2026: #comment commands pushed to an attached repository were added as comments on the
issue. Until that version, Linkwright did not send the author’s email address, so Jira ran nothing;
our FAQ said otherwise, and was wrong until we measured it.
To limit the risk described above, Linkwright passes a commit’s email address to Jira only when:
- the commit is your own and you pushed it: GitHub must have verified the commit’s email address on the same GitHub account that pushed it. A commit written in a colleague’s name, or pushed by someone else (after a rebase, for example), is still linked to its issues, but its commands do not run. Up to 20 commits with commands are passed on per push;
- every issue key in the message belongs to a project the repository is attached to. A command
aimed at an issue of another project is not run, so a repository cannot act on projects it is not
attached to. To stay on the safe side, any word shaped like a key counts: a message with a command
that also mentions
UTF-8does not run its command; - the commit arrives live, by webhook. Commits read later (the first read after attaching a repository, the periodic re-read, a Refresh) never run commands, so history is not replayed.
The email address and the full message go to your Jira site with the push and are not stored by Linkwright (privacy policy, § 2.1). Linkwright has no switch of its own to turn Smart Commits off yet; if you need one, tell us on the support portal.
More guides
- How to connect GitHub to Jira Cloud
- GitHub Issues vs Jira
- GitHub commits not showing in Jira
- GitHub for Jira backfill: restart it and check it
- GitHub for Atlassian is moving to Forge: what to check
- Limit which GitHub repositories each Jira project can link
- JQL for GitHub data in Jira
- Linkwright permissions and sync statuses, explained
- GitHub for Jira alternatives
- 24 hours side by side with GitHub for Atlassian
- GitHub organization not showing in Jira
- GitHub deployments not showing in Jira