Written by At Lambert Labs we work with a range of clients across different sectors. What can be awkward is that they often use completely different DevOps and project management tools. On the DevOps side, some clients use AWS while others prefer Google Cloud Platform or even PaaS providers such as Heroku. Some clients use CircleCI while others prefer to use Travis/Jenkins. From the project management perspective Jira and Confluence are very popular, but a selection of our smaller projects still make use of Trello.
As a software development agency it is important for us to be expert users of as many of these project management tools as possible because it enables us to work on a broader range of projects. We recently started working on a project with a client that uses GitHub for code hosting and Jira for issue tracking. Integrating Jira with GitHub makes it easier for our project managers and software engineers to keep track of the GitHub branches and pull requests that correspond to tickets in Jira. The benefits of integration are shown in the example Jira ticket below, where there are links to a GitHub branch and pull request in the development section (these appear automatically as part of the integration).
Integration
Prerequisites
- A Jira account with administration rights
- A personal GitHub account, or a GitHub organisation account with administration rights
Setting up GitHub
First, navigate to your GitHub account settings page (if you navigate to your personal settings, this will eventually give Jira access to your personal repositories. If you navigate to your organisation settings, this will eventually give Jira access to your organisation’s repositories). Go to ‘Developer Settings -> OAuth Apps -> New OAuth App’. You will be presented with the following page:
Fill in the following details and click on ‘Register Application’:
- Application Name: Jira
- Homepage URL: https://yoursubdomain.atlassian.net/
- Application Description: Jira integration
- Authorization Callback URL: https://yoursubdomain.atlassian.net/
After clicking on ‘Register Application’ you will be taken through to a confirmation page giving you a Client ID an Client Secret. Make a note of these – you will need them in a moment.
Setting up Jira
Now navigate to your organisation’s dashboard on Jira and go to ‘Settings -> Applications -> DVCS Accounts -> ‘Link GitHub Account’. You will be prompted with the following popup:
Choose either GitHub or Github Enterprise as your host (depending on what is appropriate) and put either your GitHub username or GitHub organisation name as the ‘Team or User Account’ (again, depending on what is appropriate). Client ID and Client Secret should be self explanatory! After you click ‘Add’ you will be prompted by an authorisation page (you should authorise the app, and may be required to enter your password as part of this process). You will then be redirected to the DVCS accounts page in Jira, where you should now see your linked GitHub account.
The last step is to understand how to make sure your GitHub branches and pull requests appear in the corresponding Jira tickets. To ensure the link takes place, you must name your Git(Hub) branches as ‘<JiraProjectKey>-<Jira-Issue-Number>-normal-git-branch-name’. You can find your Jira Project Key (on a per project basis) by going to a Jira project and navigating to settings. You will see a details page similar to the following:
So, for the above Jira project, an example branch name would be ‘LMS-5-my-new-feature’. As soon as you follow this naming convention for your branches you will see branches and pull requests appearing in your Jira tickets. Nice!