Updated August 2026 with current Smart Commit syntax, the documented limitations, and the development smart value situation on Cloud versus Data Center.
A Smart Commit is a Git commit message carrying commands that Jira acts on when the commit is pushed: #comment to comment on a work item, #time to log work against it, and the name of a workflow transition such as #done to move it.
The catch is that none of them report failure. If the work item key is missing, misspelled, or points to a work item the committer cannot edit, Jira does nothing and the commit succeeds anyway. No error reaches the developer, no error reaches the Git client, and nobody finds out until someone notices the worklog is empty.
This guide covers the syntax, working examples, the documented limits, and what to do about the silent failures.
Smart Commit syntax
Every Smart Commit follows the same shape: optional free text, the work item key, more optional free text, then one or more commands.
<ignored text> <WORK_ITEM_KEY> <ignored text> #<command> <command arguments>
The work item key is mandatory somewhere in the message. Without it there is nothing to act on and the entire message is treated as ordinary text. Any text between the key and the command is ignored. Putting the key first, as every example below does, is a convention that keeps git log readable, not a requirement of the parser.
A single command cannot span more than one line, though you can put several commands on the same line.
| Command | What it does | Arguments |
|---|---|---|
#comment | Adds a comment to the work item | The comment text, to the end of the line |
#time | Logs a worklog entry | A duration such as 1w 2d 4h 30m, optionally followed by a worklog comment. The values can be decimal numbers |
#<transition_name> | Moves the work item through a workflow transition | None. The transition name is the command itself, for example #done |
That is the complete list. Smart Commits have three commands and no mechanism for adding a fourth.
The last row is the one people get wrong. There is no #transition keyword. You write the transition you want as the command, so a transition named Close is invoked with #close.
Transition names are matched by two rules. Smart Commits only consider the part of the name before the first space, so a transition called finish work is invoked with #finish. Where that would be ambiguous, because a workflow offers both Start Progress and Start Review, replace the spaces with hyphens and write #start-review.
Smart Commit examples
Logging time and commenting in one message:
SW-424 Rework the OAuth callback handler #time 3h 30m Debugged the state parameter mismatch #comment Callback now validates state before token exchange
Transitioning a work item on the commit that finishes the work:
SW-518 Add retry logic to the payment webhook consumer #done
A transition whose name contains spaces, hyphenated because another transition starts with the same word:
SW-602 Wire up the new pricing table #start-review
All three commands at once, in a multi-line message:
SW-731 fix(auth): reject expired refresh tokens Refresh tokens past their expiry were being accepted because the comparison used the issued-at claim instead of the expiry claim. #comment Fixed the claim comparison and added a regression test #time 2h #done
Acting on several work items in one commit:
SW-812 SW-813 Extract the shared validation helper #comment Refactor covers both reported cases
Note the pattern in every example: the human-readable description comes before the commands. That keeps git log readable for the people who have to read it later.
What Smart Commits cannot do
| Capability | Smart Commits | Notes |
|---|---|---|
| Comment, log time, transition | Yes | The three built-in commands |
| Custom commands | No | The command set is fixed |
| Set a field value | No | Not exposed as a command |
| Assign the work item | No | Not exposed as a command |
| Require a work item key | No | A commit without a key is accepted as normal |
| Validate that the key exists | No | An unresolvable key is ignored silently |
| Reject a commit | No | Smart Commits react, they never block |
| Transition through a workflow with required fields | No | Atlassian's documented behaviour is that the command silently fails |
| Report a failure to the developer | No | Failures are silent from the Git client's perspective |
Why Smart Commits fail silently
Smart Commit processing happens in Jira, after the push has already been accepted. Git has no idea Jira exists, so there is no channel through which a failure can be reported back to the developer's terminal.
The failures come from four places, and all four are common.
The key does not resolve. PROJ-9999 parses as a valid key format but no such work item exists. Jira finds nothing and stops. The developer sees a successful commit.
The committer is not recognised. Smart Commit actions are performed as the Jira user whose email address matches the Git author email, and Atlassian requires that match to be against a single Jira user. If the developer's git config user.email does not match their Jira account, or matches more than one, none of the commands run.
The committer lacks permission. Even with a matched account, #comment needs permission to comment on work items in that project, #time needs permission to log work, and a transition command needs permission to transition. Missing any one of them means that command is skipped.
The transition is not available or the screen demands more. #done only works if a transition whose name starts with done exists from the work item's current status. Atlassian is explicit about what happens next: if any field on the transition screen has been made required, the transition command will silently fail. There is also an inverted case. If your Jira admin has made comment a required field, adding #comment to a transition command breaks it, so the command has to be written without the thing you would assume it needs.
In all four cases the commit is already in the repository's history. The automation you were relying on did not run, and the only way to discover that is to go and look.
Development smart values in Jira automation
If you need more than the three commands, the usual next step is Automation for Jira, and here the answer depends entirely on your deployment.
On Jira Cloud, Automation for Jira has development triggers and development smart values. A rule can fire on a new commit, branch, or pull request and act on the commit metadata: send a Slack message, set a field, assign the work item, call an external service.
On Jira Data Center, none of that exists. There are no development triggers and no development smart values. Automation for Jira on self-hosted deployments cannot start a rule when a commit is pushed, and there is no supported workaround inside the product. The practical path on Data Center is an incoming webhook trigger, with a post-receive hook or CI step that POSTs to it.
One thing is identical across both deployments. A rule that fires on a commit still depends on the commit carrying a resolvable work item key, so on Cloud you inherit the same silent failure in a more capable wrapper.
How to make the work item key reliable
Every failure mode above traces back to the same root cause: nothing checks the commit before it is created. Smart Commits, automation rules, and the Jira development panel all consume the work item key, and none of them can require it.
Doing it yourself means building it. A pre-receive hook that calls the Jira REST API to confirm the key resolves, matches the committer to a Jira account, reads the work item's status, checks the relevant permission, and returns an error a developer can act on is a real piece of software. It then belongs to you: across Jira upgrades, API deprecations, credential rotation, and every repository someone creates next quarter. On Bitbucket Cloud you cannot even deploy it, because the platform has no server-side hook to run it in.
Better Commit Policy for Jira is that enforcement layer, already built and maintained. Policies define what a commit message must contain, and commits that break the rules are blocked until they are fixed. For Smart Commits specifically, the relevant rules are:
- The message must contain a work item key that resolves to a work item that actually exists, which eliminates the
PROJ-9999failure entirely. - The work item must be in an allowed status, so transition commands target a valid transition when the commit is made rather than being discovered invalid afterwards.
- The committer must be a recognised Jira user, optionally restricted to specific groups, which is the same identity check Smart Commit processing relies on, run early enough to be actionable.
- The message must match an agreed format, so
git logand any downstream parsing stay predictable.
The checks run at two points, and neither one needs a server-side hook, which is why this works on Bitbucket Cloud where a hand-built hook cannot. A pre-commit hook runs on the developer's machine at git commit time, before the commit object is created:
✗ 1 violation found Commit message must start with a valid Jira work item key (e.g. PROJ-123) Fix the violation and commit again.
The Commit policy satisfied merge check validates the pull request title, description, and every commit in it, which covers developers who have not enabled the pre-commit hook. Set as required, a Bitbucket Premium feature, it blocks the merge until the violations are fixed. Set as recommended, available on all plans, it lists the violations without blocking the merge.
Checking the key before the commit exists is unique to the Better Commit Policy apps. Bitbucket Cloud has no native equivalent, because it does not support custom server-side hooks, and no other Marketplace app runs the check on the developer's machine. This is a platform constraint, not a configuration option. Every other option, Smart Commits included, finds out after the commit is already in history. On Bitbucket Data Center, the Connector for Bitbucket adds server-side push rejection as well.
Does Better Commit Policy replace Smart Commits?
No. Smart Commits still perform the comment, worklog, and transition. Better Commit Policy guarantees that the work item key those actions depend on is present, correctly formatted, and resolvable, so the actions actually run.
It also runs wherever Smart Commits do. Better Commit Policy for Jira is available for both Jira Cloud and Jira Data Center, so the same rules apply on either deployment, and on Data Center the policies extend to Subversion and Mercurial as well as Git.
Can I enforce Conventional Commits alongside a work item key?
Yes, and this is the common configuration in Jira-based teams. The message carries the key and the Conventional Commit type together, for example SW-424 feat(auth): add OAuth2 login. See Conventional Commits in Bitbucket Cloud for the policy configuration, and these commit message templates for copy-ready formats.
Why this matters for regulated teams
Under SOX, ISO 13485, IEC 62304, ISO 26262, and similar standards, the requirement is a demonstrable link from every code change back to an authorized work item. A Smart Commit that silently did nothing leaves a gap that looks identical to a change nobody bothered to document.
Enforcing the key before the commit exists means the traceability record is complete by construction, rather than reconstructed under audit pressure.
Get started
Keep using Smart Commits. Put a policy in front of them so the work item key they depend on is always there.
