Linkwright

Jira Smart Commits with GitHub: syntax, requirements, and why they do not run

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

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:

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

  1. 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.
  2. Is the issue key in upper case, on the same line as the command?
  3. Does git config user.email match exactly one Jira account, with the right permission?
  4. For a transition: is the name unambiguous, and does the transition require no field?
  5. For #time: is time tracking enabled?
  6. 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 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.