Jira GitHub Integration: the Comprehensive 2021 Guide

stefaan@idalko.comUncategorized

Jira GitHub Integration

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.

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.

Here’s what we’ll cover in this blog post:

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.

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 its 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, but it will also see things like Pull Requests, branches, and more.

With just a single step, you can provide a 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. This 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 a .jirarc configuration file to connect to your project, check your issues, and confirm that each commit includes a message that Jira understands.

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.

Use Exalate to Sync issues across Jira and GitHub

Exalate is a synchronization tool that allows for the integration of issue trackers. This includes Jira (Cloud and on-premise) and Github.

github jira integration

So, if for example, you’d like to raise issues on Github and get them fixed on Jira, you’ll be able to have the issue data synchronized. Obviously, this would also work the other way around.

Would you rather watch a tutorial than read a guide? Then check out this video:

That means, if you’re working with multiple teams, each team can continue to work in their own environment and still have their data synchronized.

Exalate has a distributed architecture so each side can configure what it shares and receives independently without involving the other side in the process. There are outgoing and incoming sync rules written in Groovy-based scripting language for doing precisely this. This also ensures that the tool is flexible, so you can customize the synchronization any way you’d want.

Exalate comes in 2 modes: the Basic and the Script mode. Configuration modes in an integration

The Basic Mode

The Basic mode uses in-built mappings between Jira and Github issues. You can use this mode for simple integration use cases. It also comes with a Free Plan that offers up to 1000 free syncs per month. The ease with which you can get started with this mode is what makes it so appealing.

You can set up instant syncs between your issues using this mode by entering the issue key you want to sync and clicking on “Exalate” as shown on the screen below.

Issue key to sync

You can easily set up a bidirectional sync between your Jira and GitHub.

Synchronization of issues

The Script Mode

To configure the connection between Jira and GitHub using advanced scripting, you need to use the Script mode. With this mode, you can add scripts to the outgoing and incoming sync rules to send or receive new information. Or you can stop sending and receiving certain information by deleting or commenting on the sync rules. You can take the help of script helpers to guide you with this process.

 

This way you can use Exalate to sync almost any kind of information with the other side.

You can even set automated synchronization triggers that allow you to synchronize issues when the condition you have set is satisfied. To sync existing issues in bulk you can use the “Bulk Connect” option.

Find out more about Exalate here.

Note: this is not about integrating GitHub as a code repository with Jira. This only works if you’re looking to integrate the issue tracking.

Use Zapier to Further Integrate Jira and GitHub

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

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

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 a 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 is 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: