Configure workflow triggers

While this page on triggers applies to all Jira products, triggers are designed to work closely with development tools, and are most powerful when used with Jira. 

Triggers are a powerful tool for keeping your Jira issues synchronized with the information in your development tools (Fisheye/Crucible, Bitbucket Cloud and GitHub). Instead of relying upon developers to manually update the status of issues after committing code, completing reviews, creating branches, etc, you can configure triggers in your workflow to automatically transition issues when these events occur in your development tools. For example, you could configure a trigger to automatically transition an issue from 'To Do' to 'In Progress' when a branch is created.

This page will help you get started using triggers. We will show you how to set up triggers in a workflow and demonstrate how an automatic transition works. We will also provide some guidelines on how to best configure a trigger and help you troubleshoot your triggers.

Before you begin

Currently, you can't configure workflow triggers for team-managed projects. The instructions on this page apply to company-managed projects only.

Before you can start using triggers, you need to connect your development tools to Jira. At a minimum, you will need at least one of the following:

• Bitbucket Cloud

• GitHub (using the app)

• Bitbucket Data Center (all current versions)

• Fisheye/Crucible (all current versions)

• GitHub Enterprise 11.10.290 (or later)

For instructions on how to connect these tools to Jira, see Integrating with development tools. This page also includes details on improved functionality enabled by connecting Atlassian development tools.

Guide: Setting up triggers

In this example, you will be configuring a Jira workflow with triggers. By the end of this section, you will have an understanding of how to configure triggers and what a typical development workflow with triggers looks like.

Introduction

The screenshot and table below show a workflow and triggers similar to what you will be configuring. They reflect the typical interactions between Jira and development tools in a software development lifecycle. Jira, Bitbucket Data Center and Fisheye/Crucible (3.5.2) are used for this example, but you can configure something similar using any of the supported development tools.

Step 1. Create/Edit a workflow

The easiest way to create a software development workflow is to create a new project, choosing a relevant project type. This will set up your new project with the software development workflow, which is identical to the one shown above.

If you already have a similar workflow, navigate to it and edit it:

1. Select  > Issues.

2. Under WORKFLOWS, select Workflows.

3. Next to the workflow you want to edit, click Edit.

Step 2. Add a trigger to a transition

We'll start by adding a 'Commit created' trigger to the 'Start progress' transition. Ensure that you are editing (not viewing) the workflow.

1. In diagram mode, select the Start progress transition in the workflow (the line from 'To Do' to 'In Progress'). A panel displays showing the details of the transition.

2. Click Triggers in the panel. The 'Transition: Start Progress' screen displays showing the 'Triggers' tab.

3. Click Add trigger, then select Commit created in the dialog that appears. A diagnostics window displays. You'll notice that the trigger will be added for all development tools that Jira is connected to.

4. Click Add trigger to add the trigger. It will appear in a list at the bottom of the 'Triggers' tab. You can check whether it is working by clicking View Details.

That's it! Don't forget to publish your draft workflow.

Step 3. Test the trigger

Now that you have added the 'Commit created' trigger to the 'Start progress' transition, let's test it by making a commit.

1. Create an issue in your Jira project. This project needs to use the workflow that you just edited. The status of your new issue should be 'To Do'. Take note of the issue key, as you'll need it for the next step.

2. Commit some code to your Bitbucket Cloud repository. You can commit anything, however you will need to include the issue key in your commit message. 
   In this example, the issue key is TIS-1, which is referenced in the commit message shown in the screenshot. 

3. Check your issue in Jira again. The status changed from 'To Do' to 'In Progress'. If you click the History tab or Activity tab, you can see the automatic transition that changed the issue's status.

Step 4. Add the rest of the triggers

Now that you've added and tested a trigger, follow the same process to add the rest of the triggers in the list above.

Congrats! You've set up a workflow with triggers.

If you are having problems configuring your trigger or getting it working, check the Troubleshooting section below.

If you want to learn more about how triggers work, see the Understanding triggers section below.

Understanding 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 directly or with an app. The table below lists the events that are enabled for each development tool.

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. For more information about global transitions, see 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).

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. When we can’t match a user to the trigger, we move the issue with an anonymous user. This doesn’t mean there are anonymous users with access to your Jira site.

  • 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:

Bitbucket Data Center

Fisheye/Crucible

Bitbucket Cloud

GitHub / GitHub Enterprise

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:

Bitbucket Cloud and GitHub Enterprise

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

• Webhook-triggered synchronization: the DVCS connector uses webhooks in Bitbucket and GitHub Enterprise 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 Cloud/GitHub event.

• Scheduled synchronization: if Jira cannot be contacted when a Bitbucket Cloud/GitHub Enterprise 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.

Bitbucket Data Center and Fisheye/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 limits — Event limits are imposed on all of the development tools so that Jira is not overloaded with too many events. Any events sent after the event limit is exceeded are lost. Event limits for each development tool are listed below:

Bitbucket Cloud and GitHub Enterprise

• Webhook-triggered synchronization: 10 branches; 100 commits

• Scheduled synchronization: 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.

Bitbucket Data Center

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.

Fisheye/Crucible

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).

Troubleshooting

If you are having problems setting up a trigger or getting a trigger to work, follow the steps below to troubleshoot your problem.

1. Use the trigger diagnostics

Your first step in troubleshooting a trigger is to check the diagnostics for it in Jira. The diagnostics can tell you if there is a problem with the connection to your development tools or whether an issue did not automatically transition as expected.

1. Navigate to the Jira administration console > Issues > Workflows > Find your workflow and click View (Operations column)

2. In Text mode (not Diagram mode), click the desired transition.

3. On the transition screen (Triggers tab will be showing), click View details for the desired trigger to show the diagnostics information. 

   • The 'Trigger sources' section lists problems related to the integration between Jira and your development tools. For example, whether you have the correct type of authentication configured.

   • The 'Transition failures' section lists issues that have failed to automatically transition despite the trigger firing. For example, an anonymous user was mapped to the transition but the transition has a post function that requires a non-anonymous user.

2. Check for common problems

If you cannot resolve your problem with the information from the trigger diagnostics, check the list of common problems below for possible causes and solutions.

I cannot add a trigger to a transition:

Possible causes...

The issue does not transition:

Possible causes...

The issue transitions but not as expected:

Possible causes...

The information recorded for the transition is not correct:

Possible causes...

3. Get help

If you still cannot resolve your problem, there are a number of other help resources available, including our applications forums, Atlassian community, and our support team.

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).