Integrating builds with your issues workflow

You can configure a workflow in JIRA applications, so that the workflow is actioned when a build completes successfully. For example, you can configure a workflow to automatically progress an issue from 'Building' to 'Resolved' status. You could also configure the same workflow to progress an issue from 'Building' to 'Build Broken' status if a build related to that issue fails. A build is related to an issue if the build involves a commit that had the issue key added to commit message.

On this page:

Builds Workflow exists in JIRA applications  and it incorporates the common statuses and transitions (see the Understanding the 'Builds Workflow' section below).

Understanding the 'Builds Workflow'

Diagram: The default Builds Workflow




Start Progress


Stop Progress


Resolve Issue


Close Issue


Reopen Issue


Wait for Build


Build Passed


Build Failed


The 'Wait for Build', 'Build Passed' and 'Build Failed' transitions are Bamboo-specific transitions:

  • 'Wait for Build' — This transition will be triggered when code is committed for this issue (and a build started) using the #wait or #wait-for-build commit command . Note, you must manually enter the commit command in your commit message to trigger the transition, as described in Using Smart Commits.
  • 'Build Passed' — This transition will be automatically triggered when a build for this issue passes.
  • 'Build Failed' — This transition will be automatically triggered when a build for this issue fails.

Using the 'Builds Workflow' in your projects

The following instructions describe how to create a workflow scheme that uses the 'Builds Workflow', and then associate the workflow scheme with a project. If you want to add the 'Builds Workflow' to an existing workflow scheme, ignore steps 4-6 below and assign the workflow to your existing workflow scheme instead.


1. Creating a workflow scheme that uses the Builds Workflow
  1. Log in as an admin for your site.
  2. In the administration console of a JIRA application, go to Workflows Workflow Schemes. The 'Workflow Schemes' page will display.
  3. Click Add workflow scheme
  4. Enter a Name and Description for your workflow scheme and click Add. Your workflow scheme will be created and you will see the page for editing the workflow.
  5. Click Assign a workflow
  6. In the Issue Type dropdown, select the issue types that you want the 'Builds Workflow' to apply to. In the Workflow drop-down list, select Builds Workflow. Click Add. 
2. Associating the workflow scheme with your project
  1. Go to the 'Project Summary' page. Keyboard shortcut g + g + start typing 'projects'.

  2. Click Workflows on the left of the 'Project Summary' page (you can also click the More link in the 'Workflows' section in the middle of the screen). The 'Workflows' page is displayed, indicating the current workflow scheme used by the project.

  3. Click Switch Scheme to display the 'Associate Workflow Scheme to Project' page.

  4. Select the relevant workflow scheme from the Scheme list and click Associate to begin the migration process. The 'Builds Workflow' will be associated with your project via your workflow scheme.
  5. Click Acknowledge to finish the process. 
  6. Select the project you wish to use the 'Builds Workflow' with. 

Issues (of the issue types specified in your workflow scheme) will now use the 'Builds Workflow'. If you add the issue key of an issue to the commit message when committing, the issue will be automatically transitioned along the workflow when the build starts/succeeds/fails.

Modifying the 'Builds Workflow'

You cannot modify the 'Builds Workflow' itself because it is non-editable. However, you can copy it and edit the copy if the original 'Builds Workflow' doesn't suit the needs of your project. You can then activate the new (copied) workflow by adding it to a workflow scheme and then associating that scheme with your projects.

Copying and editing the 'Builds Workflow'

  1. Log in as an admin for your site.
  2. In the JIRA administration console of a JIRA application, go to Schemes > Workflow Schemes. The 'Workflow Schemes' page will display.
  3. Click View all workflows
  4. Locate the 'Builds Workflow' and click Copy in the 'Operations' column.
  5. Enter a Name and Description for the new (copied) workflow scheme and click Copy. The new workflow will be created and displayed on the 'View Workflows' page.
  6. You can now edit and activate your new workflow as needed.See Configuring Workflow and Activating workflow in the JIRA Cloud Administration documentation for more information on how to do this.

Integrating build transitions into your custom workflow

If modifying a copy of the 'Builds Workflow' is not feasible for your projects, it is possible to manually modify your existing workflow to include the Bamboo transitions. It is recommended that you avoid doing so unless you have a good understanding of the workflows.

To integrate build transitions into your existing custom workflow, edit your workflow and configure appropriate issue statuses and issue transitions as described below.

Configuring your issue statuses

We recommend that you set up issue statuses for your workflow to indicate when a build related to an issue is building or the build is broken (e.g. 'Building', 'Build Broken'). There is no technical restriction preventing you from incorporating Bamboo-specific build transitions into a workflow without these intermediate states, however, in practice it will cause problems.

For example, a developer may work on an issue, and commit several times over the course of a few days for that issue. 
Even if earlier commits cause the build to pass, the developer may not have finished working on the issue and will need to commit more code without successful builds resolving the issue. Hence, an intermediate state (e.g. 'Building') is required which a developer will only transition the issue into (i.e. using the #build commit command), if they want the issue to be resolved from that particular build.

Configuring your issue transitions

Automatic issue transitioning via builds is controlled by both commit commands and Bamboo-specific transition properties in JIRA applications, as described below:

  • Commit Command — Commit commands are mapped to transition names. Hence, if you add the 'Waiting for Build' transition to your workflow, your users will be able to automatically trigger the transition by using the #wait or #wait-for-build commit command in their commit messages.
  • Bamboo-specific transition properties— The Bamboo-specific transition properties on the transitions that you want to be triggered when a Bamboo build passes or fails. The following properties are supported:






    A transition with this property will be triggered when a build for this issue passes, and the transition is available to the issue in its current state.



    A transition with this property will be triggered when a build for this issue fails, and the transition is available to the issue in its current state.


    any valid resolution, e.g. 'Fixed'

    The issue resolution will be set as specified by this property, if the transition with this property is triggered by a build.

    (info) Please note, you cannot set up common transition properties in JIRA applications. You will need to manually re-enter the transition property on each transition that you want it added to.

Last modified on Oct 7, 2015

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.