Enable Git Integration
- Dmytro Stasyuk
Supported providers: Bitbucket
Synchronization approach: 2-way
Support for issue branches: yes
On this page:
Enable Git Integration on the Jira side
Git Integration is disabled by default and you can still use all of the App’s features without it. This can be useful for example during early phases of the project when you may not have a Git repository available yet but you need to start capturing user requirements nevertheless. Once you have a repository that you can link your Jira project to, then you can go ahead and configure Git Integration like explained below so that any changes from then on are synchronized with Git.
On the App’s project configuration page select the 'Git' tab and click on the toggle button to enable it
2. Enter the required connection parameters, referencing the values of your Bitbucket repository. For information on how to create a Bitbucket access token see this page.
Once back on the issue page, make a small change to your feature file and save. Then open the history side panel like shown below to observe that your change entry now contains a git commit link icon next to the Jira change id.
Clicking on it will take you to the Bitbucket page for the commit in which the change was uploaded.
Add a webhook on the Bitbucket side
In order for the Feature file changes made outside of Jira e.g. via IDE or directly via Bitbucket UI to be synchronized to Jira a web hook needs to be added in Bitbucket for the linked repository.
Copy the Bitbucket webhook URL from the App’s configuration page by clicking on the copy button highlighted below
2. Navigate to the Repository Settings page of your Bitbucket repository
3. Select Webhooks in the side panel and then click on the ‘Add webhook’ button
Give your Webhook a name and paste the URL you copied on the Jira App’s settings page. Ensure that your webhook is selected to be Active and from the Triggers section select only 'Push' event type. Click save to create your webhook.
After you’ve added your Bitbucket webhook, changes that are made to the Feature files via IDE, Bitbucket UI or other means, will be uploaded to Jira.
Troubleshooting Git connectivity
Troubleshooting download from Bitbucket
If changes to feature files that are made outside of Jira are not uploading to Jira it may be down to webhook misconfiguration. To verify that your webhook is working as expected you can inspect its request logs to ensure that it gets sent to Jira and that a valid response is received back.
From the Webhooks section of your Repository settings page click on the 'View requests' action link
Click on 'Enable History' if it is not already enabled
Make a change to a feature file outside of Jira (e.g. via Bitbucket UI) and then inspect request details by clicking on the ‘View details' link. Note that Jira will send back a successful response with HTTP code 200, even in cases when there are issues downloading from Bitbucket, this is done purposely so that Bitbucket does not trigger the Webhook again and again as it would do in case of error response type.
You can check whether Jira was able to download the feature files by inspecting the message in the response body, like highlighted in example below
In the example above Jira did not download any changes as the project ‘BFJD' is not configured to use issue branches in the App’s Git Integration settings page and the change was made on an issue type branch - 'feature/BFJD-80-demo-issue'
Troubleshooting upload to Bitbucket
If the feature file changes made via Jira are not being uploaded to Bitbucket, you can check the reason from under the History tab on the issue page like shown below
In this case our project was configured to use issues branches in the App’s Git Integration settings page however no branch for this issue could be found at the time of the change