BlogUse Cases

The Easiest Way to Integrate GitHub and Jira [Step-by-Step Guide]

GitHub and Jira are two names anyone in the software industry can instantly recognize without needing extra information. 

Developers and project managers lean on these tools to build software, using GitHub for version control and source code management, and Jira for tracking and solving issues. 

Naturally, the need for GitHub - Jira integrations is prevalent, as linking both tools together can solve problems related to communications, delivery times, and redundancy. 

While there are a few solutions to connect GitHub and Jira, none seems to have the leading hand in terms of simplicity and power. 

Today, we are here to change that.

In this use case, we will show you how to create GitHub and Jira integrations that lessen the burden on project managers and developers. 

Before we get started, let’s go over a few notes to keep in mind.

Connecting Jira to GitHub: Initial considerations

Jira currently features three different editions:

  • Jira Software 
  • Jira Core
  • Jira Service management

In this article, we’ll focus on the Jira Software version (aka Jira Server), for which Integromat provides full API access

Secondly, a word about the integration itself. 

In this guide, we will show you how to create not one, but two types of GitHub - Jira integrations:

  • One-way integration: sends data from one application to another. Either Jira to GitHub, or GitHub to Jira
  • Two-way integrations: sends data from one app to another and vice versa automatically 

For example, when an issue is created on GitHub, a task/issue is created on Jira. Then, when that same issue is closed on GitHub, the corresponding task on Jira is also closed. This is how two-way integrations work. 

Sticking with the example mentioned earlier, we’ll take you through a step-by-step process of how to set up the GitHub - Jira Software integration. 

Savoring the time savings already? Let’s keep moving forward then.

Note: You will need an Integromat account to create the integration. If you don’t have one yet, please register for free.

Note 2: You will see the word “scenario” thrown around a lot. This is a synonym to “automated workflow”, and our setup will require two of them. For more information about basic Integromat terms, please refer to this page

Connecting GitHub with Jira software: A step-by-step guide

Now that you have an Integromat account, it’s time to make the most out of it. Let’s jump right into it.

1. Creating the scenario

Starting from your dashboard, you will create a new scenario from scratch:

 create-new-integromat-alt


After you do this, please pick the first app you will use in your scenario: GitHub. Then, click the “Continue” button on the upper right side of the screen.

 searching-for-integromat-app-alt

 

This will land you on the scenario builder (aka visual canvas) which is what you will use to integrate GitHub with Jira.

In the visual canvas, you will see that the GitHub app has been pre-loaded as your first option. Click on it, and select the “Watch issues” module from your options. 

This module will kick off the automation.

jira-watch-issues-instant-integromat-module-alt

2. Configuring the GitHub module

Once you select the module, you will need to connect your GitHub account to Integromat and grant a few permissions. 

Click the “Add” button and click “Continue”.

jira-watch-issues-instant-integromat-module-1-alt

 

In the pop-up screen, enter your GitHub credentials and sign in.

 github-integromat-connection-alt

After you do this, you will see the “I want to watch” field, which gives you the option to watch just one or all repositories in GitHub. 

For this automation, just choose one repository. Another field will appear to select the specific repository Integromat will watch for you. 


github-watch-repositories-alt


 

Now, it’s time to choose when to start processing data. For this use case, select the “From now on” option to watch for new issues.

 github-jira-integration-scheduling-alt

 

Great, you have successfully configured the Github module! 

3. Configuring the Jira Software app

Next step is to add the Jira app to the scenario and configure it. 

When you hover over the Github app, you’ll see a little plus sign, which allows you to add another module. 

Click on the sign, an app search box will appear in front of you. 

Here, you need to search for Jira and select the Jira Software app. 

As we know, the goal is to create an issue on Jira Software from issues previously created in Github. 

With this in mind, select the “Create an issue” module.

jira-create-an-issue-module-integromat-alt


Just like with Github, you will have to connect your Jira account to Integromat to proceed.

When you click the “Add” button, you will notice that it requires the following information:

  • Service URL
  • Username
  • API token

For the Service URL, go to your Jira account, copy the URL ending in .net and paste it in the Service URL field. 

Then, enter your Username in the field below.

jira-integromat-connection-alt


What about the API token you ask? Don't worry, we got you. Just follow the steps below.

Creating an API token in your Jira account 

  • Click this link and log in to your account
  • Click the Create API token button

api-token-atlassian-account-alt

In the popup window, enter a name for your token.

create-api-token-jira-alt


Next, copy the token, head over to Integromat, and paste it in the API token field.

copy-api-token-jira-alt

Now, it’s time to finish the configuration of the Jira module on Integromat. 

First, you need to create a custom field on Jira and call it the GitHub Issue number. 

As the name suggests, this field will contain the GitHub issue number, which is important for the synchronization to work correctly.

Next, select the project that you want to create the issue in. You will see many fields appearing on the module. Here’s what you need to do with these:

  • In the Issue type menu, select the Task option
  • Next, map (drag and drop) the Title element from the Github module to the Summary field

jira-module-setup-summary-alt


  • Scroll down until you see the Description field and map the Body element
  • Enter the name and account ID of the reporter in the corresponding fields below

jira-module-setup-issue-description-alt


  • Scroll down one more time until you see the Github Issue number custom field that you created. Here, simply map the Number element to this field
  • If there’s a specific assignee for these issues, you can enter the name and account ID in the fields below. Hit OK after doing this

jira-module-setup-issue-number-alt


Hit the “Save” button and switch the scenario on by toggling the switch on the bottom left.

github-jira-integration-saving-integromat-scenario-alt


At this point, the “Schedule setting” menu should appear on your screen. 

Integromat gives you the option to schedule your scenarios to run whenever you want them to. In case it doesn’t, you can always access this menu by clicking on the clock icon.

Here, you can choose the intervals at which Integromat will monitor GitHub for new issues (and consequently, pick up new issues and create them on Jira). 

Once you’ve chosen the one that fits your needs, click “Activate” at the bottom left.

jira-github-integration-scenario-scheduling-alt


Congrats! You’ve just created the first scenario.

4. Scenario execution 

Before we move on to the second scenario, let’s first test this one. 

Head over to GitHub and create an issue. Once completed, go back to the scenario and hit the “Run once” button. This is what it should look like:

github-jira-integration-gif-alt


The scenario should pick up the new GitHub issue, and create a Jira issue with it. 

Let’s move on to the second scenario, and unlock the full potential of Jira - GitHub integrations.

Second scenario: Two-way synchronization between Jira and GitHub

A quick recap before we continue: In the first scenario, when an issue is created on GitHub, an issue is also created in Jira.

In the second scenario, when an issue is closed on Jira, the corresponding issue will be closed on Github as well. 

Here’s how to do it.

1. Connecting the Jira Software app (instant)

This time, the Jira Software module will appear first in the automation but with an important difference. 

Remember in the first scenario, when you scheduled it to run at certain intervals? Well, Jira Software has an instant trigger module. 

This means that whenever an issue is changed in Jira, the information is picked up instantly by the module, triggering the scenario without delay.  

Now, into the action. You will need to create a new Integromat scenario. After that is done, you will have to search and select the “Watch issues - instant” Jira module (you can do this straight from the scenario builder).

watch-issues-jira-module-instant-alt


Next, you need to add a webhook, which allows Integromat to receive the data instantly. To do this, please follow the steps:

  • Click “Add” and give it a name 
  • Select “Issue” as the Hook type
  • Tick the “Updated” option under “Events” and hit “Save”

Once added, Integromat will automatically attach the webhook to Jira for you.

jira-module-setup-hook-type-alt


With the webhook, Integromat needs to learn the data structure before you can map the data elements in the GitHub module that we will use afterward.

To do this, please follow these steps:

  • Hit the “Run once” button on your scenario
  • Go to Jira and change the status of the issue you created in scenario 1 to “anything” (besides “Done”). 
  • You’ll see a number in the little bubble above the module if successful

jira-watch-issues-module-alt

2. Connecting the GitHub app

Now, you will have to add the GitHub “Update an issue” module to your scenario.

jira-github-integration-github-module-configuration-alt 

Once you do this, scroll down and map 

Scroll down, map the Issue: Fields: customfield element (name may vary but you will see a number next to it) to the “Number” field and select the “Closed” status. See the image below for reference.

jira-module-watch-closed-issues-alt


You probably noticed that this scenario watches for any status change in an issue on Jira, and then closes the issue in GitHub. 

So as it stands, if the status changes to let’s say, ‘TO DO’, it will still close the issue in Github. 

But don’t worry, there’s a solution to avoid that.

You will use a filter. This is an exclusive Integromat feature that allows data to pass through only if it meets a certain criteria.

To add a filter, click on the route between the two modules to bring up the filter settings.

jira-github-integration-filter-alt

To set up the filter, simply:

  • Map the Issue: Fields: Status: Name element to the top field
  • Select the “Equals to (case insensitive)” text operator
  • Type the word “Done” in the bottom field

This filter ensures that only issues with statuses set to “Done” will be closed on GitHub.

map-issue-status-jira-watch-issues-module-alt

3. Scenario execution

Since it's an instant trigger scenario, you need to hit the “Run once” button first, and then change the status of the issue to “Done” in Jira to trigger the scenario. 

You won’t have to do this every time, as this is just to check that the scenario works correctly.

jira-github-integration-gif-alt

Conclusion

Setting up these scenarios is a huge time and money saver for projects that live both on Jira and GitHub.

In addition, these integrations help you reduce the odds of miscommunications among team members. 

How many times did the lack of communication between team members block a project? 

How many times did someone forget to update either Jira or GitHub?

These are common occurrences that you can put an end to here and now with Integromat. 

Just like time, don’t let this opportunity pass you by.

Happy automating!


Do you like this article?
Don't forget to share it!
Share

Get started now!

Sign up for a free Integromat account today!