Configuring workflow triggers
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
Before you can start using triggers, you need to connect your development tools to JIRA Software. At a minimum, you will need a JIRA Server instance, plus at least one of the following:
- Bitbucket Server (all current versions)
- FishEye/Crucible (all current versions)
- GitHub Enterprise 11.10.290 (or later)
- Bitbucket
- GitHub
For instructions on how to connect these tools to JIRA, see Integrating with development tools. This page also includes details on other functionality you can enable by connecting the various development tools Atlassian offer.
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 Software, Bitbucket Server and FishEye/Crucible (3.5.2) are used for this example, but you can configure something similar using any of the supported development tools.
| Transition | Triggers |
|---|---|
Start progress | Branch created (Bitbucket Server) |
Start review | Pull request created (Bitbucket Server) |
Restart progress | Pull request declined (Bitbucket Server) |
Done | Pull request merged (Bitbucket Server) |
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: JIRA administration console > Issues > Workflows > 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. Select the Start progress transition in the workflow, i.e. the line from 'To Do' to 'In Progress'. A panel will display on the right, showing the details of the transition.
Related topic: Why you shouldn't configure triggers on global transitions
2. Click Triggers in the panel. The 'Transition: Start Progress' screen will display with the 'Triggers' tab showing.
3. Click Add trigger, then select Commit created in the dialog that appears. A diagnostics window will display — you'll notice that the trigger will be added for all development tools that JIRA is connected to.
Related topic: How to enable different events for triggers
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 be using 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 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.
Related topic: Referencing a JIRA issue in a commit, branch, pull request, or review
3. Check your issue in JIRA again. The status should have 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.
Related topics: How the user is mapped from the development tool to JIRA;
Event handling and event limits;
How triggers relate to other workflow operations/constraints
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.
Don't want to set all of this up? Good news! You can download a similar workflow (pre-configured with triggers) from the Atlassian Marketplace: download 'Development Workflow with Triggers'.
Congratulations! You have now 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. The table below lists the events that are enabled for each development tool.
| Dev tool | Bitbucket, GitHub, GitHub Enterprise | Crucible | FishEye |
|---|---|---|---|
| Events |
|
|
|
There is a known issue where the 'Branch created' event isn't supported for GitHub, which is being tracked under DCON-432 - Getting issue details... STATUS — please keep this in mind when configuring trigger events.
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'.
Tip: 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:
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:
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:
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.
- Navigate to the JIRA administration console > Issues > Workflows > Find your workflow and click View (Operations column)
- In Text mode (not Diagram mode), click the desired transition.
- 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:
The issue does not transition:
The issue transitions but not as expected:
The information recorded for the transition is not correct:
3. Get help
If you still cannot resolve your problem, there are a number of other help resources available, including our applications forums, Atlassian Answers, and our support team.