To look at both vendors’ pages on the topic, you would think the integration between CircleCI and Atlassian Jira‘s cloud products was easy and well supported at this stage. But having tried to follow the public docs to set this up today, my experience says otherwise.

I’m proposing a pull request to help improve CircleCI’s side of the docs, but in the mean time, here’s the extra info I wish I’d had to get this working quickly.

Update: this is now merged and the official docs updated! 🙂 Though hopefully if you too use a runner image that requires the same token setup steps as mine, the below steps may still save you a little time.

1. If you are adapting the basic example on the intro page but are not using the same CircleCI-issued image as the runner for your jobs – e.g. you use some other Docker image – you may find you’re missing something called jq. Annoyingly this was fixed but the docs tell you to use an old version that won’t sort out the dependency for you automatically. So update to at least circleci/jira@1.0.5 – latest at time of writing – and have a look at the orb’s home to find the latest stable version as of right now.
2. You need a CircleCI API key set up. Again, I’m not sure if this has just been overlooked or is buried elsewhere in the docs – it may be that the CircleCI base images do it for you if you use those. In my case I needed to create a project (not personal) API token in Project Settings > Permissions > API Permissions. I also found that the status scope was insufficient – this had to be set to all.
   
3. Next, to make that token available to your job, go to Project Settings > Build Settings > Environment Variables and add one called CIRCLE_TOKEN with the value of the token you created in step (2).
4. Finally, if you want to track releases, you’ll want to go beyond the minimal config example and pass in some of the parameters for notify that are only documented on the orb page. If you are tracking deploys to start off, you might want your config to look something like:
   
   

   ...
   orbs:
     jira: circleci/jira@1.0.5
   
   workflows:
     some-workflow:
       jobs:
         - deploy-development:
           ...
           post-steps:
             - jira/notify:
                 job_type: deployment
                 environment_type: development
   

   If your Jira issue layout includes Releases you should then get a nice one of these popping up:
   
   
   Just start your commits with the Jira issue number to have it join up the dots.