skip to content

In Bitbucket Cloud linked to Jira, why might a commit message like ACME-142 #resolve leave the Jira work item unchanged?

level: middleimportance: must knowfreq 30%

answer

  1. who Jira thinks you are
  2. author email, not the pusher
  3. required fields fail quietly
  4. one line, uppercase key
  5. a Jira admin can switch it off

basics

~20 s

A Bitbucket Cloud smart commit runs as the Jira user whose email matches the commit's author email. A mismatched email, missing permission, required transition fields, a malformed key or disabled smart commits stops it; the commit still lands.

solid answer

~40 s

Smart commits follow `<ignored text> <WORK_ITEM_KEY> <ignored text> #<command> <arguments>`, with three commands: `#comment`, `#time` (such as `#time 1w 2d 4h 30m`) and a workflow transition such as `#resolve`. The most common failure is identity: the author email in the commit, set locally with `git config user.email`, must match exactly one Jira user who has permission for that action. Other causes: the transition has required fields, so it silently fails; the command breaks across lines or sits on a line without its key; the key is not the default uppercase format like `ACME-142`; the transition name is ambiguous, as `#start` is when both Start Progress and Start Review exist; or a Jira admin disabled smart commits for the repository. The commit itself still pushes and still appears on the work item.

code

bash · 3 lines
bash
git config user.email "[email protected]"
git commit -m "ACME-142 #time 2h 30m #comment retry logic fixed"
git commit -m "ACME-142 ACME-143 #resolve"

go deeper

for a junior

Recall the three commands, #comment, #time and a transition, and that the work item key must appear in the commit message.

for a middle

Explain why the author email decides who Jira acts as, and list the silent failures: required fields, line breaks, key format and ambiguous names.

for a senior

Diagnose a team-wide failure quickly, starting with email matching and repository enablement, and weigh the impersonation risk before relying on smart commits.

for a principal

Decide whether workflow moves belong in commits, in the pull request merge or in Jira itself, given auditability and who is allowed to move work.

## Linking versus smart commits Once a Bitbucket Cloud workspace is connected to Jira Cloud, two different things can happen when a developer types a **work item key** such as `ACME-142` (Atlassian's pages now say *work item* and *space* where older pages said *issue* and *project*): - **Linking** is passive. A key in a **branch name**, a **commit message** or a **pull request title** associates that branch, commit or pull request with the work item, so it shows in the work item's **Development** panel. Jira users need the *View Development Tools* permission to see it. - **Smart commits** are active. A key followed by a `#command` in a commit message makes Jira *do* something: comment, log time or move the work item through its workflow. A commit can link and still fail as a smart commit. That is the situation this question describes. ## The syntax The general form is `<ignored text> <WORK_ITEM_KEY> <ignored text> #<COMMAND> <optional arguments>`. Text between the key and the command is ignored. | Command | Example | Effect | |---|---|---| | `#comment` | `ACME-142 #comment fixed retry loop` | Adds a comment | | `#time` | `ACME-142 #time 1w 2d 4h 30m wired up the client` | Logs work, with the trailing text as the work log comment; needs time tracking enabled in Jira | | transition | `ACME-142 #resolve #comment done` | Runs the workflow transition whose name starts with that word | Several commands can share a line (`ACME-142 #time 2d 5h #comment done early #resolve`), and one command can hit several keys separated by spaces or commas (`ACME-142 ACME-143 #resolve`). ```bash # Jira matches this email, not the account that pushes git config user.email "[email protected]" git commit -m "ACME-142 #time 2h 30m #comment retry logic fixed" git commit -m "ACME-142 ACME-143 #resolve" ``` ## Why a smart commit does nothing Work through these in order; the first is the usual answer. 1. **Email mismatch.** Git records whatever author email the developer configured locally. Jira requires it to match **exactly one** Jira user; no match, or several users with that email, and the action fails. 2. **Permission.** The matched user must be allowed to comment, log work or transition work items in that space. 3. **Required fields on the transition.** If the transition requires a field, the command **silently fails**. If the Jira admin made the comment itself required, the command must *not* include `#comment`. 4. **Line breaks.** A command must not span lines, and each line must carry its own key; a `#time` on a second line without a key is dropped. 5. **Key format.** Only the default key format is recognised: two or more uppercase letters, a hyphen and a number. `acme-142` does not qualify. 6. **Ambiguous transition names.** Only the part of a transition name before the first space is read. With *Start Progress* and *Start Review*, `#start` is ambiguous; write `#start-progress`. 7. **Smart commits disabled.** They are on by default for new repositories in a linked Bitbucket account, but a Jira administrator can turn them off for new repositories or for one repository. In every case the **commit still succeeds** and still shows on the work item. When the action fails, Jira normally emails the matched Jira user, or the committer if no Jira user can be identified; in rare cases it fails silently. Two more limits: `#resolve` cannot set the Resolution field, and with forks a smart commit is processed only the first time Jira sees it. ## Transitioning from the pull request instead A pull request whose title carries a key lists its work items in a Jira panel. In the merge dialog, the person merging can pick transitions for those work items, and the status changes in Jira as the merge completes. Only statuses that need no field input can be reached this way, so this path shares the smart-commit blind spot for transitions that require fields. ## The security note Because Git lets anyone write any author email into a commit, someone could push a commit attributed to a colleague and have Jira act with that colleague's rights. Atlassian flags this as a possible elevation of access in Jira; teams for whom that matters disable smart commits and transition work items through Jira or the pull request instead.

  • Why would #start fail in Bitbucket Cloud smart commits when the workflow has Start Progress and Start Review?
    Smart commits read only the part of a transition name before the first space, so #start matches both transitions and is ambiguous. Use hyphens to spell the full name, #start-progress or #start-review, and the command resolves to one transition.
  • Why might a Jira administrator disable smart commits for Bitbucket Cloud repositories?
    Git lets a commit carry any author email, so a developer could push a commit attributed to a colleague and have Jira comment, log time or transition with that colleague's permissions. Where that impersonation risk matters, admins disable smart commits and move work items in Jira or from the pull request.
  • How else can a Bitbucket Cloud pull request move a Jira work item?
    When the pull request carries a work item key, the merge dialog lists the linked work items and lets the person merging choose a transition for each. The status changes in Jira as the merge completes, but only statuses that need no field input can be reached this way.

  • Smart commits act as the Bitbucket user who pushed, whatever the commit's email.
  • A failed smart commit rejects the push so the developer notices immediately.
  • A lowercase key such as acme-142 works just as well as ACME-142.
  • A command can wrap onto the next line as long as the key appears once.
  • A transition with required fields prompts the developer for the missing values.