Jira & Bitrise: Comments on New Builds

I joined a team this year which has been experimenting with using Bitrise for Continuous Integration of Android and iOS builds. I come from a Jenkins background, so it was a great opportunity to learn something new and overall I have been impressed by Bitrise’s simple to understand workflow with almost drag and drop components.

The problems I found was that the team members not working in engineering would often ask the developer for a link to the Bitrise build so they could download and test. The Bitrise job would output multiple files, so there were often questions over which build to use. We were also using the github plugin in Jira, but it was cumbersome to navigate through Jira, github, Bitrise to locate the latest build.

In an attempt to improve this process, I decided to write an addition to our Bitrise workflow which would post a comment on the Jira ticket once the build had completed.

Find Jira Tickets Script

The first problem I needed to solve was to figure out the relationship between Bitrise builds and Jira tickets. My workplace typically require that the Jira ticket is included in the commit message and/or the branch name. Fortunately, Bitrise provide these as an environment variables which I can then search for the ticket number.

I visited the workflow editor, selected my primary workflow, and added a new step at the end. I was unable to find an existing step that would identify Jira tickets, so I selected the Script step which would let me run my custom bash query.

I named it ‘Find Jira Issue’ so it could be easily identified in the workflow

(Update)

I submitted this step to Bitrise to include in their catalog of steps, so you can now just select the Find Jira Issue step instead of selecting Script. The step will allow you to set the input and will output a list of unique tickets as $JIRA_ISSUE_LIST.

https://www.bitrise.io/integrations/steps/find-jira-issue

Searching the commit message for a ticket

#!/usr/bin/env bash
set -o pipefail
echo "Extracting JIRA Issue number from commit message '${BITRISE_GIT_MESSAGE}"
JIRA_ISSUE="$(echo "${BITRISE_GIT_MESSAGE}" | egrep -o '[a-zA-Z]+-[0-9]+' | sort -uf | tr '\n' '|' | sed 's/.$//')"

Breaking down the query

The first step is to select the input. This can be different depending on your process. Some teams use the branch name to identify the ticket, others will add it to the commit message. Bitrise provides environment variables to identify each of these inputs so these can be used in your workflow step. Here is an example of using both the commit message and branch name as the input:

echo "${BITRISE_GIT_MESSAGE} ${BITRISE_GIT_BRANCH}"

Next we search for anything that matches a Jira ticket pattern, this is typically as follows:
1. Upper or lower case text which will identify a Jira Project
2. Separated by a hyphen
3. Ends in a number, which will indicate the ticket id

egrep -o '[a-zA-Z]+-[0-9]+'

You could add character limits to both the Jira project and ticket number to enforce a specific pattern and reduce false matches, or if you use a single Jira project you can be specific about the name.

egrep -o 'PROJECT-[0–9]+'

To ensure we find unique tickets, you can sort this list with flags specifying that the sorting is case insensitive and the output should remove any duplicates.

sort -uf

The search request will output each successful result on new lines and to make this Bitrise compatible we need to convert it to a pipe separated list. This request will replace any new line with a pipe.

tr '\n' '|'

The trim command will replace all new lines, which includes the final one at the end of the list. The last action to be taken is the replace method to remove the final entry.

sed 's/.$//'

Abort when no issue is found

This step was created to provide information for the next step in the workflow. If no ticket can be found we should mark the step as failed. This is important because we can set the next step to not run when the previous step is not successful.

# If no issue, abort
if [ -z "${JIRA_ISSUE}" ]; then
    echo "Input doesn't contain Jira issue"
    exit -1
fi

When a step fails, it will mark the entire build as a failure. We can get around this by marking this step as skippable, this can be done by editing the bitrise.yml file directly:

- find-jira-issue@0:
    is_skippable: true
    inputs: 
        - find_issue_content: "$BITRISE_GIT_MESSAGE"

Save environment variable using envman

Now that we have successfully located the Jira ticket number, we need to tell Bitrise to pass this value to the next step of the workflow. This is done using a command called envman to add the result as an environment variable.

if command -v envman 2>/dev/null; then
    echo "Adding $JIRA_ISSUE to env. vars"
    envman add --key JIRA_ISSUE --value "${JIRA_ISSUE}"
fi

Post Jira Comment Integration

I used the Bitrise provided Post Jira Comment workflow step. A link can be found below. I went with this approach because it removed the complication of authorization and formatting the HTTP Post request.

Make sure you toggle the box that indicates that this step should not run if the previous step failed.

Secrets

Jira account username, password/api token, and base url. These are sensitive variables, and should be saved in the Bitrise secrets section so they are not outputted in the public Bitrise log. I would recommend creating a new Jira user for this account with the appropriate display picture.

Jira issue keys

This is the environment variable we set in the previous workflow step. I called this $JIRA_ISSUE above.

Build Message

Identify what is important to the consumers of the comment. Ensure that it is clear, concise, and has easy to identify links to builds. Jira tables don’t handle multiple lines, so I also wrapped the commit message in no-format tag to ensure that it displays correctly.

(/) *$BITRISE_APP_TITLE* build *$BITRISE_BUILD_NUMBER* is now available
||Commit|{noformat}$BITRISE_GIT_MESSAGE{noformat}|
||Branch|$BITRISE_GIT_BRANCH|
||Hash|$GIT_CLONE_COMMIT_HASH|
[Download|$BITRISE_PUBLIC_INSTALL_PAGE_URL] | [Details|$BITRISE_BUILD_URL]

The Finished Result

Overall this increased the productivity of our team and ensured that my colleagues could be effective with their time. By watching Jira tickets, colleagues would be notified by email when builds would be complete and it also provided a link to the public download page so it was easier for non-technical employees to download builds without navigating the Bitrise details page.

Hopefully the find-jira-issues workflow step pull request is accepted, because I imagine this will be useful for other teams for all kinds of notifications and reporting.

bitrise-steplib/steps-post-jira-comment-with-build-details

find-jira-issue 0.0.1 by jimmithy · Pull Request #2570 · bitrise-io/bitrise-steplib