• Products
  • Documentation
  • Resources

Understand workflow triggers

The following topics explain how triggers work in more detail, so you can use them more effectively.

Trigger events

Events (e.g. Commit created) are made available for triggers by integrating Jira with particular development tools. The table below lists the events that are enabled for each development tool.

Dev tool

Bitbucket, GitHub, GitHub Server

Crucible

Fisheye

Events

  • Pull request created

  • Pull request merged

  • Pull request declined (Bitbucket only)

  • Pull request reopened (Bitbucket Data Center only)

  • Commit created

  • Branch created

  • Review started

  • Submitted for approval

  • Review rejected

  • Review abandoned

  • Review closed

  • Review summarized

  • Commit created

  • Branch created

Triggers and global transitions

We recommend that you do not configure triggers for global transitions, unless you are confident that you understand exactly how the trigger will affect the behavior of the issue.

A global transition allows any status in a workflow to transition to a particular status. This is represented in the workflow viewer/editor by a black All lozenge pointing to the status that the global transition targets. Learn more about advanced workflow configuration.

Configuring triggers for global transitions can often result in an issue unexpectedly transitioning to the target status for the global transition. For example, consider if you configured a 'Commit created' trigger for the global transition to the 'In Progress' status. Committing code can happen at many stages during an issue's lifecycle (e.g. writing the initial code, changing code after a review, etc). This could result in the issue incorrectly transitioning to 'In Progress' out of a number of statuses, like 'In Review' or 'Done'.

If you do use global transitions in your workflow, you will probably have multiple transitions into a status. This means that users will have multiple workflow options on an issue (e.g. both 'Start Progress' and 'In Progress'). To hide options, add the 'Hide transition from user' condition to the relevant transitions.

Referencing a Jira issue in a commit, branch, pull request, or review

The table below describes how to reference a Jira issue in a commit, branch, pull request, or review, so that these events will trigger transitions for the issue (provided that you have set up triggers on the transitions).

Event

Instructions

Create commit

Include the issue key in the commit message.

For example, a commit message like this "TIS-1 Initial commit" will automatically transition the TIS-1 issue from 'To Do' to 'In Progress'.

Create branch

Include the issue key in the branch name, when you create the branch.

For example, if you name your branch "TIS-2-feature", it will automatically transition the TIS-2 issue from 'To Do' to 'In Progress'.

Create/Reopen/Decline Merge pull request

Ensure that the pull request includes commits that reference the issue (in their commit messages).

For example, if you create a pull request that has "TIS-3" in the title, it will automatically transition the "TIS-3" issue from 'In Progress' to 'In Review'. If you reopen, decline or merge the pull request, it will also transition the "TIS-3" issue accordingly.

Start/Reject/Abandon/Close review

Include the issue key in the review title, when you create the review.

For example, if you name your review "TIS-4 New story" and start the review, it will automatically transition the TIS-4 issue from 'In Progress' to 'In Review'. If you reject, abandon or close the review, it will also transition the "TIS-4" issue accordingly.

User mapping from the development tools to Jira

The following process describes how a development tool user is mapped to a Jira user for workflow triggers. It applies to all events, however each development tool uses a different email address and username for the mapping (see the bullet point following the process description below).

  • Process: The user initiating the event in the development tool is mapped to a Jira user by matching the email address, then the username, i.e.

    • Single Jira user with a matching email address — Transition the issue as the Jira user.

    • No Jira users with a matching email address — Transition the issue as an anonymous user.

    • Multiple users with a matching email address in Jira — Try to find a matching username in that group of users. If there is a Jira user with a matching username, transition the issue as the Jira user. If there is no matching username, transition the issue as an anonymous user.

Email address and username used for user mapping

For Bitbucket Data Center:

Event(s)

Email address and username used for user mapping

All pull request events

The Bitbucket Data Center email address and username of the user who actioned the pull request.

Commit created

The email address associated with the commit and the Bitbucket Data Center username that the email address maps to. If the email address does not map to a username, the authors "name" from the commit will be used.

Branch created

The Bitbucket Data Center email address and username of the authenticated user that pushed the branch to Bitbucket Data Center.

For Fisheye or Crucible:

Event(s)

Email address and username used for user mapping

Commit created

The email address associated with the commit and the Fisheye username that the email address maps to. If the email address does not map to a username, the authors "name" from the commit will be used.

Branch created

This event is not mapped to a Jira user. This means that the issue will be transitioned as an anonymous user. 

All review events

The Crucible email address and username of the authenticated user that actioned the review.

For Bitbucket Cloud:

Event(s)

Email address and username used for user mapping

All pull request events

The Bitbucket email address and username of the user who actioned the pull request. Note, the Bitbucket user needs to have made at least one commit (with that email address configured for their profile), otherwise the pull request cannot be mapped to a Jira user. This means that the issue will be transitioned as an anonymous user. 

Commit created

Email address associated with the commit and the Bitbucket username that the email address maps to. If the email address does not map to a username, the authors "name" from the commit will be used.

Branch created 

This event is not mapped to a Jira user. This means that the issue will be transitioned as an anonymous user. 

For GitHub:

Event(s)

Email address and username used for user mapping

Pull request created / Pull request merged

GitHub email address and username of the user who actioned the pull request. Note, the GitHub user needs to have made at least one commit (with that email address configured for their profile), otherwise the pull request cannot be mapped to a Jira user. This means that the issue will be transitioned as an anonymous user.  

Commit created

Email address associated with the commit and the GitHub username that the email address maps to. If the email address does not map to a username, the authors "name" from the commit will be used.

Branch created  

This event is not mapped to a Jira user. This means that the issue will be transitioned as an anonymous user.  

Event handling and event limits

In most cases, the processing of events from your development tools into automatic issue transitions should be seamless. However, sometimes there may be delays in issues transitioning or issues not transitioning at all, due to how events are handled or event limits.

  • Event handling — Events are handled differently depending on whether the development tool connects to Jira via the DVCS connector or an application link. This can affect whether events are delayed or lost when Jira is unavailable

For Bitbucket or GitHub

Events from Bitbucket and GitHub are processed via the DVCS connector in Jira. The DVCS connector processes events from Bitbucket and GitHub via two synchronization mechanisms: a webhook-triggered synchronization and a scheduled synchronization.

  • Webhook-triggered synchronization: The DVCS connector uses webhooks in Bitbucket and GitHub to post data to Jira when an event occurs. This is the standard mechanism for processing events, which means that issues should be automatically transitioned almost immediately after a Bitbucket/GitHub event. Event limit: 10 branches; 100 commits. 

  • Scheduled synchronization: Event limit: 600 branches (sync interval in minutes x 10); 6000 commits (sync interval in minutes x 100)
    The event limits for scheduled synchronizations can be less than 600 branches and 6000 commits, if the synchronization interval is reduced, but never greater. 
    If Jira cannot be contacted when a Bitbucket/GitHub event occurs, the event is stored by the DVCS connector and sent at the next scheduled synchronization (every 60 minutes, by default). This is a backup mechanism in case the webhook-triggered synchronization fails.

For Bitbucket Data CenterFisheye, or Crucible

Events from Bitbucket Data Center and Fisheye/Crucible are processed via the application link. However, Bitbucket Data Center and Fisheye/Crucible are responsible for ensuring that events are sent, and they send them once at the time that the event occurs. This means that if Jira is unavailable when the events are sent, the events will be lost.

Event limit: 10 branches; 100 commits per synchronization. A further constraint that applies on top of the 10 branches and 100 commits limits is a 100,000 issue changed event limit. For example, if 100 commits each reference more than 1000 issue keys, the issue changed limit would be exceeded. Limited to 6000 events per synchronization.

How triggers relate to other workflow operations/constraints

When a transition is triggered automatically, it ignores any conditions, validators or permissions configured on the transition.

However, post functions are still executed. You need to be careful that if your post function requires a user, that your transition will not be executed by an anonymous user (see user mapping section above).

Additional Help