How to use Jira Software for Deployment Management?

At Apwide, we continuously improve our software development processes and we love exploring new ways of working, especially when we leverage DevOps principles and automate repetitive tasks. Managing deployments in Jira Software Cloud is quite new and relies on new features not available in Jira Software Data Center.

There is not much information available online when it comes to Deployment Management in Jira, that's why we are publishing this article where we share our findings and recipes. We hope it will give you some inspiration for your current and future software projects!

Deployment Management

ITIL4 defines 3 key practices necessary to successfully deliver software:

Zooming on the Deployment Management practice, there are several deployment techniques available: Phased Delivery, Continuous Delivery, Big Bang Deployments, etc. If you want to understand and learn how to choose between them, I recommend the article David wrote,  8 Deployment Strategies Explained and compared. 

In this article, we will focus on improving Continuous Delivery by tracking CI/CD Deployments in Jira. Some can also call it "Agile Release Management".

Jira Deployment Views and API

For improving your CI/CD processes, Jira Software Cloud provides several features for sharing deployment information:

Deployments View

The Jira Deployments View gives you a global view of the tickets that have been recently deployed to your various environments on a very handy timeline. This view is useful to find the tickets that have been recently deployed to your various environments.

Issue Deployment View

Jira Software also provides an easy way to access the deployment status of an issue from its "Development" information tab (more information).

Issue Deployment View

The last deployments of an issue can now also be accessed directly from the "Releases" page:

Jira Cloud Deployment API

All these views rely on the Jira Software Cloud Deployment API that you need to integrate with your deployment pipelines and scripts.

Push deployment information to Jira

You may be already thinking:
"Well, cool views! but how can I get such accurate deployment information in Jira?"

Deployment tools are specific to your applications: they may be executed by any kind of combination of custom, esoteric and third-party tools. There is no magic/universal way to push deployment information to Jira.

Hopefully, Jira provides a Deployment API and a bunch of integrations with major tools used to trigger deployment jobs. For more information, refer to the official documentation.

1. Integration with Jenkins

In our case, we use Jenkins to build and deploy our applications. When certain branches are updated, a Jenkins job is automatically triggered to perform an automatic deployment to our CI/CD test environments. In order to do that properly, we have just followed those instructions.

Here is an extract of our jenkinsfile pipeline that shows the step used to push deployment information into Jira:

// the deployment will be automatically triggered:
// 1) when merging into the 'develop' branch
// 2) if the job is manually launched with the "DEPLOY" param set to true
if (params.DEPLOY || (env.BRANCH_NAME.contains("develop"))) {

   stage('deploy to CI environment') {
      try {
         // Deployment context information
         def environmentId = 222 // unique id of your environment
         def environmentName = "dev.ci.golive-data-center" // name of your environment
         def environmentType = "testing" // check deployment API doc if you want to change it
         def jiraSite = "your-jira-software-site.atlassian.net" // url of your Jira Software Cloud

         jiraSendDeploymentInfo(
            environmentId: environmentId, 
            environmentName: environmentName, 
            environmentType: environmentType, 
            site: jiraSite, 
            state: 'in_progress'
         )

         // ...
         // do the deployment here
         // ...

         jiraSendDeploymentInfo(
            environmentId: environmentId, 
            environmentName: environmentName, 
            environmentType: environmentType, 
            site: jiraSite, 
            state: 'successful'
         )

      } catch (error) {
         echo "Not able to deploy to CI environment"
         jiraSendDeploymentInfo(
            environmentId: environmentId, 
            environmentName: environmentName, 
            environmentType: environmentType, 
            site: jiraSite, 
            state: 'failed'
         )
      }
   }
}

Each time Jenkins performs a deployment, the deployment status as well as the list of deployed tickets are automatically updated in Jira 👍

2. How Jira tickets are linked to deployments?

Have you already asked your developers to manually update the Jira tickets they worked on, once they are deployed? For many reasons you can guess, this is an error-prone process and it does not work well…

For developers, it is much easier to update this information the moment they are done, before switching to the next task. At this point in time, developers usually summarize what was done in a clean commit message before pushing and sharing it with the rest of the team.

That's why we are asking each developer to include the reference of the linked Jira tickets in the commit message. This will automatically create links between Jira tickets and the commits pushed to the central repository. Read this for more information

Example of commit message including references of Jira tickets:

git commit -m "TEM-1234 TEM-5677 CS-345: Fix timeline visualization bug"

3. Use Git Hooks for qualitative commit messages

You can enforce commit messages to contain a reference to a Jira ticket when pushing code to Bitbucket Cloud using a Git Hook. Refer to this great tutorial about Git Hooks.

In our case, we also wanted to standardize the format of our commit messages using the Conventional Commits format. Here is our .git/hooks/pre-push checking both link to Jira issues and Conventional Commits format:

#!/bin/bash
# install this hook

# run at the root of the git project (-N to avoid recursive build):
# atlas-mvn install -N

#set -e

if [[ "$CI" != "" ]]; then
   echo "No pre-push hook for Jenkins, he is not human, he does not need rules."
   exit 0
fi

cat <<EOF
★★★ Checking for mandatory tickets ★★★

✎ only chores do not require a ticket in the commit description
✎ an exception can be made by using TEM-0 as ticket.

Let's start !

EOF

upstream=$(git rev-parse --abbrev-ref HEAD@{upstream})
if [[ $? == 0 ]]; then
   upstream=origin/develop
fi

hashes=$(git log ${upstream}..HEAD --pretty=oneline | cut -f1 -d' ')
errors=0

function check_for_ticket {
   local hash=$1
   subject=$(git log -n 1 --pretty=format:%s ${i})
   if [[ "$subject" =~ 'chore' ]]; then
      echo " ✔ chore has no need for a ticket."
   else
      regex="([A-Z]{1,3}-[0-9]+)"
      if [[ "$(git log -n 1 --pretty=format:%s%b "${hash}")" =~ $regex ]]; then
         ticket="${BASH_REMATCH[1]}"
         echo " ✔ $ticket was referenced"
      else
         echo " ✘ MISSING TICKET: no ticket found in commit message!"
         errors=$((errors + 1))
      fi
   fi
}

function check_for_subject_format {
   local hash=$1
   subject=$(git log -n 1 --pretty=format:%s "${i}")
   echo "${subject}"
   regex="^(feat|fix|chore|doc|style)(\([a-zA-Z0-9-]*\))?:\s.*$"
   if [[ "${subject}" =~ $regex ]]; then
      echo ' ✔ commit message looks good.'
   else
      echo ' ✘ FORMAT: commit message format should follow    https://www.conventionalcommits.org/en/v1.0.0/'
      errors=$((errors + 1))
   fi
}

for i in ${hashes}; do
   print_hash=$(echo "${i}" | cut -c-6)
   echo -n "⚡ Checking ${print_hash}: "
   check_for_subject_format ${i}
   check_for_ticket ${i}
done

if [[ ! $errors -eq 0 ]]; then
   if [[ $errors -eq 1 ]]; then
      echo "There is one error (✘) to fix before pushing this code, exiting."
   else
      echo "There are ${errors} errors (✘) to fix before pushing this code, exiting."
   fi
   exit 1
else
   echo -e "✔ Good to go !\n"
fi

Example of formatted Conventional Commit message including references to Jira tickets:

git commit --all -m "feat(event-scheme): UI enhancements
>
> - correct usage of tabs
> - remove fixed-height (might need further work)
>
> TEM-2800
> "

Best Practices for Jira Deployment Automation

Automating deployments in Jira can simplify your workflow and ensure accurate status tracking. Here’s how to set up automation effectively and avoid common mistakes.

Implementing these steps will improve the accuracy and efficiency of your Jira deployment automation. Regular maintenance and attention to detail will help keep your deployment process effective and reliable.

Why is it worth doing this?

Never-ending questions are now answered in Jira! With information updated in real-time, the Deployments Views answer many recurrent questions:

And there are many other variants of such questions that should now be easily answered, just by browsing Jira!

Next Steps to go further

Our team loves the information they get thanks to the integration of the Jira Software Cloud Deployment API, but several use cases cannot natively be addressed. Hopefully, we found some good alternative solutions that we will share in our next article: stay tuned! 😉

If you have any questions or would like to share your feedback about the usage of the Jira Deployment API, add a comment in our Atlassian Community Post.