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

• If you are new to JIRA and Bamboo, we recommend that you use the 'Builds Workflow' as modifying an existing workflow is not a trivial task.
• If you have an existing workflow that you would like to modify to include build statuses and transitions, we recommend that you take a copy of the 'Builds Workflow' and modify it.
• If you want to integrate Bamboo transitions into your existing workflow, you can edit your workflow to add the transitions. We recommend that you avoid doing unless you have a good understanding of JIRA workflows.

Understanding the 'Builds Workflow'

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.

Procedure

1. Creating a workflow scheme that uses the Builds Workflow

1. Log in as an admin for your site.
2. In the JIRA administration console, 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. Log in as a user with the 'JIRA Administrators' global permission.

2. Go to the 'Project Summary' page. 
   Keyboard shortcut: g + g + start typing 'projects'.

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

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

5. 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.
6. Click Acknowledge to finish the process. 
7. 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, 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 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 JIRA 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 JIRA 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, 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:

  Property	Value	Description
  build.passed.transition	anything	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.
  build.failed.transition	anything	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.
  build.passed.resolution	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.

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