Configuring 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 Software.
Triggers are a powerful tool for keeping your Jira issues synchronized with the information in your development tools (Fisheye/Crucible, Bitbucket 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
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
- Bitbucket Server (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 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.
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.
Branch created (Bitbucket Server)
Pull request created (Bitbucket Server)
Pull request declined (Bitbucket Server)
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:
- Select the Jira icon ( > Jira settings > Issues. , , , or )
- Under WORKFLOWS, select Workflows.
- 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.
- 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.
- Click Triggers in the panel. The 'Transition: Start Progress' screen displays showing the 'Triggers' tab.
- 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.
- 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.
- 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.
- 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.
- 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.
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'.
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.