Jira Github Integration: the comprehensive 2019 guide

stefaan@idalko.comUncategorized1 Comment

Jira Github integration the complete guide

One of the main strengths of Jira is its ability to integrate with other tools to facilitate the development process.

Development and QA can use their own workflows. And your Jira acts as a central repository for information, incorporating all that data into one central hub.

This works best when you set everything up properly, so that information flows in and out of your Jira as easily as possible.

Of course, the fact that both GitHub and Jira are putting resources into integrating is a good sign. GitHub recently announced a big revamp of their Jira integration, and it’s only going to get better from there.

Today, we’re looking at some simple steps you can take to better incorporate Jira into your GitHub workflow. We’ve summed up all the steps that can help you go from syncing your work by hand, to fully integrating your Jira and GitHub.

1. Why set up a Jira Github integration in the first place?

Whether you’re working solo or heading multiple teams of developers, GitHub is great for organizing your thoughts, structuring your code, and tackling the problems of development.

Note: If you’re a fan of Atlassian products like Jira, Bitbucket might actually be the better option for you. Here’s why Bitbucket is better than Github.

Many people are fine with just using GitHub issues to track problems with their code.

Often, however, people start out using GitHub issues and then transition to Jira as their project becomes more complicated and they need the advanced features Jira provides. Such as complex fields on issues or integrations with third-party tools.

How you use the integration depends on what you’re trying to get out of it.

If you’ve just started using Jira, perhaps you just need a way to sync issues in Jira with actions in GitHub. If you’re managing a huge team, you might have bigger plans for making sure multiple workflows jive with each other.

Either way, it’s important to go in with an idea of what you want to accomplish.

Note: Learn more about Jira here.

2. How to set up a Jira Github connection

In order to get the most out of your integration, you need to ensure your tools are integrated to begin with. Recently,

GitHub made this even easier by redesigning their integration workflow. Adding the integration is free, and allows you to share data between your Jira and your GitHub repo.

If you’re using Atlassian Cloud, the new integration is the way to go.

If you’re hosting Jira on your own server, you’ll have to go through a more manual process to connect.

The process is simple, we’ll generate an OAuth token on GitHub, and enter it on our Jira instance so they can interact.

Create a connection using an OAuth token

To connect your Jira and your GitHub, you need to use an OAuth token.

Follow the directions on Jira’s documentation site to allow your Jira to see what’s going on in your codebase.

To connect your site, first use the OAuth page on GitHub to register your Jira site. Put your site URL as both the homepage and auth callback URL.

how to integrate jira and github using oauth

Click “Register Application”, and you should see a new screen with your client id and client secret, which are used in OAuth. Leave that tab open and open a new one for your Jira site.

Then, on your Jira site, go to the administrator tab and select applications. On the sidebar, go to DVCS Accounts, and click the button to add a new one. Fill out the form with the details from the other tab and click “Add”. You’re all set!

connect jira and github

Not only will the integration allow Jira to see when new commits come in, it will also see things like Pull Requests, branches and more.

With just a single step, you can provide richer context for your tickets and have your git activity show up alongside your issues.

integration of github in jira

With this integration set up, you can even leave notes in your git commit messages to indicate which tickets they’re addressing. Which brings us to our next point.

commit messages for connecting jira and github

Use a pre-commit hook

Git can be very powerful, but only if you remember to use it properly.

If your commit messages just say vague notes like “more work in progress” or if you’re trying to change your behavior, you need to use a pre-commit hook.

A hook is a script that Git runs whenever you make a commit. It can prompt you for more information and edit your commit message for you. For example, a great hook script can prompt you for what Jira issues you’re working on and add that as part of your commit message.

For Jira, we like this open-source project that provides a helpful commit hook with a useful message. It uses .jirarc configuration file to connect to your project, check your issues, and confirm that each commit includes a message that Jira understands.

3. Aligning Jira and Github workflows

Design your Jira Workflows with GitHub in Mind

Jira Workflows help you encode your process into each Jira ticket. Getting your workflow right for your organization is an important part of using Jira effectively.

If you’re integrating with GitHub, you can make sure that your workflow is designed to match up to how GitHub pushes you to work.

GitHub has a great guide on how best to work on their platform.

Every issue gets a branch. And every branch gets a peer review before getting merged and deployed. Why not make those the steps on your Jira workflow? Whenever an action happens on GitHub, you can transition to the next state in Jira.

This can get a little tricky, so just make sure you’ve thought things all the way through.

If you have a development and a master branch along with your feature branches, when do you mark things as complete? When do they land in master, or on the main development branch? Likewise, if you have nested branches, when are they completed?

I’ve found the best way to answer these questions is to look at what your actual development practices are.

Every organization is different, but the great thing about Jira is that it lets you identify what works for you, formalize it into a workflow, and make sure you’re all on the same page.

Design Your GitHub Workflow with Jira in Mind

As with Jira, GitHub provides some great tools for power users trying to get the most out of their platform.

For each pull request, you can assign reviewers and assignees. Why not develop a policy to align your reviewers in GitHub with your reporters or watchers on Jira? Making sure interested parties know where to look for code changes they need is a great way to push to get things done.

Another important point is to make sure you’re using branches and stories properly.

My favorite workflow is to make one new branch per story (with the ticket id in the branch name), and have sub-items within that story be sub-branches that merge into the main branch. That lets me coordinate all the work on one ticket into one final pull request on GitHub.

4. Use Zapier to further integrate Jira and Github

Just by using the built-in Jira tools, you can accomplish a lot with GitHub.

(note: Intercom cta EXA)

However, there are some things you can’t do from within Jira. Like delete branches after their issue closes or sync issue comments between GitHub issues and Jira.

Enter Zapier.

Zapier lets you use webhooks to add additional connections between your tools.

Zapier has hooks for common Jira actions. So you can trigger events whenever people comment on issues or mark them as closed.

Zapier also defines actions that it can perform in Jira or in GitHub. Looking to do something complicated? Like make a Jira ticket for someone to review a pull request whenever someone creates one in GitHub? Zapier lets you do that.

Integrate github and jira with zapier

5. Common pitfalls to avoid after setting up the integration

When they’re working well, integrations are a great way to make sure you have the information you need right at your fingertips. When they’re working poorly, however, it can get really annoying

Mismatching the purpose of the tools

Tools work best when you’re using them as designed. GitHub integrates with code and is designed for code-centric workflows. Likewise, Jira is built around tracking issues. Use Jira as source of truth for issues, GitHub for code. That will help avoid problems like the following point.

Not knowing where to put information

If you’ve got a comment on an issue, should it be on the Jira ticket, on the GitHub pull request, or attached as a comment on a Git commit?

Jira and GitHub let you add information and metadata in a lot of places, but just because you can put a comment somewhere, doesn’t mean you should.

To ensure information doesn’t disappear into a black hole, make sure you have a policy in place about where it should go.

I’ve worked with teams that used Jira as our single source of truth. And with teams that had policies where code comments went to GitHub and issue comments went to Jira.

As long as everybody knows where to put information and where to look for it, you should be OK.

Messaging overload

After you’ve integrated your Jira and your GitHub, there’s one really common pitfall.

Picture this.

You finish working on an issue and merge the pull request after review.

Then suddenly, your phone lights up with 4 new emails.

Jira says your ticket closed, GitHub says your pull request finished, another email says your branch was deleted, and your merge commit left a comment on your Jira issue.

Having your tools talk to each other is great. Having them all talk to you is less good.

Once everything is set up properly, take a minute to make sure your actions only trigger the right number of emails, slack messages, or Jira comments.

Trust me, the peace of mind is worth it.

Conclusion

The great thing about Jira and GitHub is that they’re both excellent tools that make the development process simpler and easier to manage. That’s doubly true when they’re integrated together. The combination lets you make your GitHub repository more detailed and your Jira more in sync with the state of your code.

Whether you’re a project manager or a developer, or in-between, there’s a lot to be gained from having your tools work together to make your process easier.

Recommended Reads: