atlassian/github-for-jira

Connect your code with your project management in Jira

GitHub For Jira

About

Connect your GitHub code with your project management in Jira. A separate Jira subscription is required. With two of your most important tools connected, you'll spend less time managing projects and more time working on them. This integration is an open-source project, built and maintained by Atlassian.

Support

For general support inquiries and bug reports, please contact the Atlassian Support team. For feature requests, please create a new issue.

Table of Contents

• Install app
  • Requirements
  • Install from Jira Cloud site
  • Install from Atlassian Marketplace
  • Install from GitHub Marketplace
• Configure app
  • Connect your GitHub organization to Jira
  • Connect new GitHub repositories
• Manage app
  • Authorize
    • Jira permission scopes
    • GitHub permission scopes
      • Repository Permissions
      • Organization permissions
      • Events Our App Subscribes To
  • Manage Jira subscriptions
• Send data and use the integration
  • See GitHub development information in Jira
  • See Jira issues in GitHub
  • See GitHub builds and deployments in Jira
  • How the integration works
  • How the backfill works
• Migrate from the DVCS Connector
• Enterprise Features
  • IP Allow List
  • Known issues
    • Connecting GitHub organizations with SSO
• Need help?
• Contribute
• License

Install app

Requirements

This app officially supports GitHub.com (all editions including Enterprise) and Jira Cloud. Support for GitHub Enterprise Server and/or Jira server may be considered in the future.

Install from Jira Cloud site

This is the recommended approach to install the app into your Jira site and GitHub org.

1. Sign in to your Jira Cloud account.
2. From the top navigation bar in Jira, select Apps > Find new Apps. You can also click the Gear icon in the top-right corner and select Apps.
3. Search for GitHub for Jira and select Get app
4. When the app is installed, a flag will pop up in the top-right corner. Click Get Started to connect your GitHub account. If you missed this flag, click Configure integration from the Apps menu.

Next, you will need to configure the app.

Install from Atlassian Marketplace

1. Go to Atlassian Marketplace.
2. Sign in to your Atlassian account and click Get it now.
3. Select your site to install this app, click Install app.
4. You will be taken to the app listing on your Jira site, click Get app.
5. When the app is installed, a flag will pop up in the top-right corner. Click Get Started to connect your GitHub account. If you missed this flag, click Configure integration from the Apps menu.

Next, you will need to configure the app.

Install from GitHub Marketplace

1. Go to https://github.com/marketplace/jira-software-github.
2. Complete the (free) order for your GitHub Organization.
3. Choose which repositories you want to use with the Jira Integration on the installation settings screen, and click Install.
4. You will be directed to a setup page to select your Jira site.
5. Once installation completes you will be redirected to Atlassian Marketplace to install the GitHub for Jira app.
6. From there, follow the instructions above to install from Atlassian Marketplace.

Configure app

Connect your GitHub organization to Jira

As part of the installation flow, you should be directed to a GitHub configuration screen to configure your GitHub organizations in the Jira app.

⚠️ If you are not directed, navigate to the Apps page of your Jira instance and click Configure integration under the ”GitHub” heading. If you do not see this, click on Manage your apps and Get started under GitHub for Jira (only visible for Jira admins). This will bring you to the app's configuration screen.

Select Connect GitHub organization, then select either GitHub Cloud or GitHub Enterprise Server.

• If you select GitHub Cloud, you’ll be redirected to a page where you can connect to organizations in GitHub.

• If you select GitHub Enterprise Server, you’ll need to provide the URL for your server and create a GitHub app.

On the Connect a GitHub organization page, select the organization and repositories you'd like to connect.

⚠️ If you don’t see your organization click Install Jira on a new organization and follow the steps to install the app on GitHub and allow it permission to view your repositories. You can also manage existing connections or add additional organizations at any time on this same screen.

For detailed instructions on how to connect to Cloud or Server, read our support documentation.

Connect new GitHub repositories

If you originally gave the GitHub for Jira app access to "All repositories", and you've created a new repository on GitHub after configuration, your new repository will automatically work with the integration. However, if you installed the app on a subset of repositories, you will need to manually edit your repository selection by:

1. Sign in to your Jira Cloud account
2. From the top navigation bar in Jira, select Apps > Manage your apps - GitHub for Jira > Get started.
3. Select Configure next to the relevant GitHub organization and add the new repository you want the app to integrate with.

Manage app

Authorize

By granting the app access, you are providing the following authorizations to your GitHub and Jira accounts:

Jira permission scopes

Read, Write, and Admin for Development Information (branches, commits, and pull requests) as well as read for Security Information (Dependabot, Code Scanning, and Secret Scanning).

GitHub permission scopes

Repository Permissions

Permission scope	Why the app needs it
Read-only access to actions	Read-only access to actions exposes the workflow_run webhook event. This event includes information such as artifacts_url, check_suite_id, conclusion, head_branch, and head_sha.
Read-only access to code scanning alerts / security events	If you want to see links to GitHub code scanning alerts in Jira or see your code scanning alerts as part of Security in Jira, the app will need read permissions to Security events. The GitHub App will listen to code_scanning_alert webhooks and send details of the Security reports to Jira. These will appear under the "Other links" tab of the Development Panel on Jira issues as well as in the Security in Jira vulnerability table.
Read-only access to dependabot alerts	If you want to see your dependabot alerts in Security in Jira, the app will need read permissions for dependabot alerts. The GitHub App will listen to dependabot_alert webhooks and send details of the Security reports to Jira. These will appear in the Security in Jira vulnerability table.
Read-only access to secret scanning alerts	If you want to see your secret scanning alerts in Security in Jira, the app will need read permissions for secret scanning alerts. The GitHub App will listen to secret_scanning_alert webhooks and send details of the Security reports to Jira. These will appear in the Security in Jira vulnerability table.
Read-only access to deployments	If you want to see build and deployment information in Jira, the app will need read permissions for deployments. This will allow the integration to listen to the webhook deployment_status event which occurs when a deployment is created. Read-only deployment permissions are used for the following webhooks: - deployment status
Read-only access to metadata	Metadata All GitHub apps have read-only metadata permission set by default. This is a mandatory requirement by GitHub and is needed to provide access to a collection of read-only endpoints with metadata for various resources. These endpoints do not provide sensitive private repository information. Read-only metadata permissions are used for the following webhook: - repository
Read and write access to issues and pull requests	Issues and pull requests are used by the GitHub for Jira app to power Smart Commit actions and unfurl Jira URLs. "Unfurling" means that the app looks for Jira issue keys in square brackets like [ABC-123] in pull request or issue comments and then replaces those issue keys with a link to the respective Jira issue. Issues: Read and write issue permissions are used for the following webhooks: - issue comment - issues Pull requests: Read and write pull request permissions are used for the following webhooks: - pull request - pull request review. Notes: The square brackets are required, without which the pull request may appear in the Jira issue's Development section, but the issue key won't be expanded to a link. For GitHub Enterprise integration (where the user owns the GitHub app) "Write" permission is optional. When not provided, the "unfurl" logic is gently skipped.
Read and write access to contents	Contents (aka code): Read-only permissions are needed to sync development information to Jira for the following webhooks: - commit comment - delete - push - workflow run We need write permissions for the create webhook so you have the ability to create a branch from an issue's dev panel. Note: for GitHub Enterprise integration (where the user owns the GitHub app) "Write" permission is optional. When not provided, the "Create Branch" feature will not function.

Organization permissions

Permission scope	Why the app needs it
Read-only access to members	To determine if you have admin access to a GitHub organization.

Events Our App Subscribes To

Event	When this event occurs
Code scanning alert / security events	Code Scanning alert created, fixed in branch, or closed
Commit comment	A commit comment is created
Create	A Git branch or tag is created
Delete	A Git branch or tag is deleted
Dependabot alert	Dependabot alert auto_dismissed, auto_reopened, created, dismissed, reopened, fixed, or reintroduced.
Deployment status	A deployment is created
Issue comment	Activity related to an issue or pull request comment
Issues	Activity related to an issue
Pull request	Activity related to pull requests
Pull request review	Activity related to pull request reviews
Push	One or more commits are pushed to a repository branch or tag
Repository	Activity related to a repository
Secret scanning alert	Secret scanning alert created, resolved, or reopened
Workflow run	When a GitHub Actions workflow run is requested or completed

Have more questions about permissions? Please see our FAQ documentation. If you can’t find the answer to a question, please feel free to open an issue and send your question to our team. We’ll be more than happy to answer and will update our FAQ doc accordingly.

Manage Jira subscriptions

Additionally, admins of an installation can view and delete GitHub subscriptions to other Jira instances, without having to log in to the Jira instance itself. This is useful if your installation is set up to send Development information to a Jira instance you no longer have access to, or to audit instances that other admins in your org may have previously configured.

To navigate to your Jira subscriptions

1. Click Connect GitHub organization.
2. Click the edit icon next to the organization.

ℹ️ This only gives you permission to delete the connection to Jira instances. To view development information in that Jira instance, you’ll need to be granted access in Jira.

Send data and use the integration

See GitHub development information in Jira

To start seeing your development information from GitHub in Jira, simply add a Jira issue key to your commit message, branch name, or PR title.

For example: the text [DEV-2095] will be sent through to Jira and appear in the Development Information section of the Jira issue with the key DEV-2095. Any branch, commit, pull request, build and deployment linked to this commit will now appear in Jira. You can find more information on how to reference issues in your development work here.

See Jira issues in GitHub

If an issue body contains a valid Jira issue key on your instance, the integration will automatically expand (unfurl) it into a reference link when surrounded in brackets []. For example: [DEV-2095] will be turned into a link to https://<your-instance>.atlassian.net/browse/DEV-2095.

This makes it so Jira issues can be linked inside a comment without it interrupting the flow of the comment as a whole.

Note: The square brackets are required, without which the pull request may appear in the Jira issue's Development section, but the issue key won't be expanded to a link.

See GitHub builds and deployments in Jira

GitHub Actions workflows and deployments will automatically be sent to your connected Jira instances so that they will be visible in Jira issues. If you’re setting this up for the first time, follow GitHub Actions Documentation - GitHub Docs. If you already have GitHub Actions and want to see CI/CD data from GitHub in Jira, include the Jira issue key in your commit message, branch name, or PR title.

Also see our guides for builds and deployments.

See GitHub security alerts in Jira

Dependabot, code scanning and secret scanning alerts in GitHub will be sent to Jira allowing your team to track vulnerabilities in Jira, and create Jira issues to help manage security work.

Learn more about the Security in Jira feature.

How the integration works

When a workflow (e.g. GitHub Action), development event (e.g. pull request, commit, branch) or security event (e.g. dependabot, code scanning or secret scanning alert) runs, the app receives a webhook from GitHub. For development information the app then extracts the issue key from the respective branch/commit/PR and send this information to Jira, for security alerts no issue keys are needed.

How the backfill works

The app is designed to backfill historical data into Jira. Once you have installed and configured the app successfully, it will automatically trigger the backfilling process, for 6 months, for the allowed repositories to update Jira with historical information such as pull requests, deployments, branches, builds, commits and security alerts. Once the initial backfilling process is complete, you will be able to view the backfilled date and status on the user interface. All branches will be backfilled, regardless of their creation date. However, pull requests, deployments, builds, commits and security alerts will only be backfilled for the last six months. If you wish to pull more historical data in Jira, you may continue the backfill process for older dates by selecting 'Continue backfill' from the action menu. If the historical data is substantial, we recommend backfilling your data in 6 month segments, and continuing the process until you've reached the desired backfilled date.

The historical data that meets the following criteria will be available in Jira:

1. The backfilling process attempts to connect all branches that fulfill at least one of the following criteria:
   • The branch name contains the issue key.
   • The title of the latest pull request associated with the branch contains the issue key.
   • The last commit message of the branch contains the issue key.
2. All commits from the default branch will be backfilled. The commit message must contain the Jira issue key.
3. Only the latest 50 commits from non-default branches will be backfilled.
4. Unreachable commits (e.g. from deleted branches) will NOT be backfilled.
5. All pull requests, regardless of their statuses, will be backfilled. The Jira issue key should be included either in the title of the pull request, in the description of the pull request or in the name of the source branch of the pull request.
6. All the builds and deployments data will be backfilled that contain the issue keys. You can check how to include issue keys to the builds and deployments here.
7. All dependabot, code scanning and secret scanning alerts that appear on main or protected branches will be backfilled.

If an error occurs during the backfilling process, the app will prompt you to retry the backfilling for the failed repositories without having to restart the entire backfill process. However, this does not account for permission errors. You will need to resolve any permissions errors before retrying the backfill process.

Migrate from the DVCS Connector

Existing users of Jira's built-in DVCS connector that meet the requirements should migrate to this integration. If you've not yet been prompted to do so, you can manually kick off the migration by:

1. Sign in to your Jira Cloud account.
2. From the left sidebar in Jira, select Jira Settings > Applications > DVCS accounts.
3. Follow the prompt to upgrade your GitHub connection.

Enterprise Features

IP Allow List

GitHub has the ability to limit who can communicate with your organization's GitHub API which we now fully support. To enable this feature or to debug any issues, please refer to our GitHub IP Allow List documentation.

Known issues

Connecting GitHub organizations with SSO

If a GitHub organization is protected with SAML, you might find its "Connect" button disabled. This may happen in a scenario when the user token (which GitHub for Jira app's UI is using) does not have permissions to access the protected org, because it was issued and saved to the app's session when the user didn't have an active SAML session in GitHub in the browser.

To workaround the problem, perform the following:

• create an active SAML session by going to https://github.com/organizations/<YOUR-ORG-NAME>/settings
  • that should initiate an auth process with your SSO identity provider
• in the same browser window, go to GitHub for Jira app and find the disabled "Connect" button for <YOUR-ORG-NAME> GitHub org
  • it must be located either on one of these pages
    • https://github.atlassian.com/github/configuration for GitHub cloud, or
    • https://github.atlassian.com/github/<UUID>/configuration for GitHub server enterprise
• insert resetGithubToken=true query parameter to the URL of the page in the browser and reload it
  • https://github.atlassian.com/github/configuration?resetGithubToken=true for GitHub cloud, or
  • https://github.atlassian.com/github/<UUID>/configuration?ghRedirect=to&resetGithubToken=true for GitHub server enterprise

After doing that, the token will be re-issued by GitHub with all necessary permissions and saved in the app's session, and "Connect" button should become enabled.

Need help?

Take a look through the troubleshooting steps in our support guide.

Contribute

Want to help improve the integration between GitHub and Jira? Check out the contributing docs to get involved.

License

The project is available as open source under the terms of the MIT License.

When using the GitHub logos, be sure to follow the GitHub logo guidelines.

github-for-jira's Issues

Look in PR body for issue keys

Currently only looks in PR title, but I think it makes sense to scan the body as well.

cc https://halp.githubapp.com/inboxes/technical/labels/ecosystem-integrations-jira/discussions/35a63390d08211e89a1a7d72d9abdb35

Feature request: support tagging?

Hey,

Just wondering if there is any intention to support tagging with that integration?

Would help organize tickets into releases (i.e. tag).

Thanks.

Jira issue links not unfurled in PR body

If you type [JI-123] in an issue body or comment, it will get linked to the Jira issue. If you type it in the Pull Request body, it does not.

The button "retry" doesn't work when accessing Jira with Safari

Anonymous access to the post-install-page

It seems that the post install page is open to anyone.

https://andymckay.atlassian.net/plugins/servlet/ac/com.github.integration.staging/github-post-install-page

Is available to anonymous users and @tcbyrd was able to add his org into that. We should see if this is something on our end defining the add-on or an issue in Jira that might need addressing

Link to this repo

We currently don't have any links to this repo, apart from the terms and conditions. Would it make sense to add a link to the bottom of some of the configuration pages we show in Jira?

Implement branch sync support

The DVCS connector currently supports syncing branches as well as commit and PRs. This has not been implemented in the integration yet, so we'll need to add support for new branches from webhook payloads as well as initial data sync.

Document the permissions we require from Jira

The readme currently says that we require permissions:

Jira for "Read, Write, and Admin for Development Information (branches, commits, and pull requests)

We could probably expand upon that a bit more since the permission request when you install the add-on it has a dialog outlining that the installation requires:

Administer JIRA
Administer JIRA spaces
Administer JIRA projects
Delete JIRA data
Write data to JIRA
Read JIRA data

Real-time synchronisation does not work for my jira/github integration

My Jira instance: https://kabakumov.atlassian.net
I've integrated it with my account and, particularly, with https://github.com/KAbakumovAtl/NewTestRepo repository.

1. I have created TEST-13 and TEST-14 issues
2. I've created new branch https://github.com/KAbakumovAtl/NewTestRepo/tree/TEST-13-merge-test-branch
3. I've pushed 2 commits consequentially to my branch with the following messages:

• TEST-13 #inprogress #comment start (https://github.com/KAbakumovAtl/NewTestRepo/commit/e2e6f8bcc20db616217c734bd94f2d1f0fe1b5e2)
• TEST-14 #done test (https://github.com/KAbakumovAtl/NewTestRepo/commit/a71c887178b6b9dbf9ccefe1f6860d9e8b76c795)

ER: I see these branch and commit on "TEST-13" issue and single commit on the "TEST-14" issue
AR: Information not synchronised. (Also, no requests to DevInfo API noticed on Jira side)

4. I've created a pull request to merge branch to master
5. I've merged the branch to the master using squash commit.

AR: Still no information on the issues

6. I went to GitHub add-on configuration page and triggered synchronisation manually
   ER: 2 commits on TEST-13 (merge commit and commit e2e6f8bcc2), branch and pull request. 1 commit (a71c887178b6) on TEST-14 issue.
   AR: I saw branch, merge commit and pull request on TEST-13 issue, I saw branch on my TEST-14 issue. No commits from the branch on either TEST-14 or TEST-13 issues.

Jira bot edits mangle autolinked GitHub references

To reproduce: create a Pull Request that references both a Jira issue, as well as an autolinked reference to another PR. For example, if I create a PR with the following body:

This PR addresses [JIRA-001]. See also my_org/my_project#123

Then I end up with a PR body in which the Jira issue is correctly linked, but the reference to PR 123 in "my_project" is dropped (i.e., shows up as plain text, not a link).

If I would have created the PR body without the Jira issue link, the autolinked reference would have been just fine.

"Get Started" in Jira addons leads to an error page

I've done the following:

• Installed the Jira integration on GitHub marketplace
• Installed the GitHub add-on in Jira

However, when it takes me to the post-install setup (https://XXX.atlassian.net/plugins/servlet/ac/com.github.integration.production/github-post-install-page), I see an iframe with a 500 in it and an "App is not responding" message:

The iframe links to a page like https://jira-integration-production.herokuapp.com/jira/configuration?user_id=...

Is this something strange about my particular installation, or is the integration down right now?

Implementation (required)

• Use the new JIRA API endpoints
• Adhere to rate limits to keep GitHub Enterprise stable and responsive
• GitHub - JIRA configuration pages.

Remove or fix the "configure" button

The configure button on Jira:

Currently takes you to an error page:

It should take you to the configuration page:

If we can't fix this, can we remove the link?

What is the migration path for existing users?

From the scope doc:

It is unknown what the migration path is for existing users.

Add a visual indicator that the Retry button was clicked

Clicking the Retry button inside the integration configuration in Jira should give an indicator that the button was clicked and that something is happening.

Here is a screenshot of where the button is located:

Currently clicking the button gives zero feedback.

Error when issue/pr body is blank

Bug reported by Sentry: https://sentry.io/github-integrations/jira/issues/722299397/

TypeError: Cannot read property 'match' of null

# from /app/lib/jira/client/index.js in Object.parse at line 33:21
  return text.match(jiraIssueRegex)

# from /app/lib/github/issue.js in module.exports at line 4:36
  const issues = jiraClient.issues.parse(issue.body)

When an isusue/pr body is blank, there's nothing to parse, so we need to ignore this.

Open source the JIRA connector

Presuming that at some point we'll be announcing the JIRA connector and open sourcing the work.

Add to the Marketplace

Let lots of people use it and get it through the Marketplace. We'll need to get some assets from github/creative#2066.

Implementation (optional parts)

• Linkifies JIRA identifiers [SENG-1234] in GitHub UI - Commit Messages, Reviews, Issues and Pull Requests
• Linkifies JIRA identifiers [SENG-1234] in GitHub notifications - email digest
• Associates JIRA project to 1 or more GitHub repositories
• Associates one GitHub repository with 1 or more JIRA projects

Developement Panel is not available

Description:

When linking my organisation to Jira Cloud with the new GitHub plugin, everything seems to works and I see my organisation. I used to do it the old way and it was working.

Actual Result:

The development panel is not present. I use to have all my commit, branches, pull request and now nothing is there, even after 3 days! That is very frustrating!

I have been searching and don't seems to find a way to sort that. Tried many different thing, removing the account, putting it back... It's just not here :(

Expected result:

After migrating, installing the new plugin and deleting the old DVCS link I would see the development section in my ticket as I use too. See screenshot.

Feature Requests

Hi,

We're using this plugin at our workplace as a replacement for the previous Jira DVCS connector. Got in touch with @andymckay for how to automatically trigger workflows from Github other than using 'smart commits'.

Primarily we are looking for deeper integration between Jira Workflows and Github actions.

More specifically, It'd be interesting if we could see some of the below features:-

1. Closing a Jira Issue by closing a PR on Github which has that Issue# (can be a setting)
2. Moving a Jira issue to "in progress" if a branch or commit has an issue# (and it was previously in todo)
3. Moving a Jira issue to "testing"/"in review" if a PR is opened for that issue# (and it was previously todo/in progress)
4. Automatically highlight Jira Issue IDs in Github and make them clickable links. If it's not possible (for example in a PR title), it could even just be an additional field/button somewhere that says "open in Jira"
5. Create/Delete branch from JIRA

Design review

Summary

We need a review of the existing pages for copy and design. Jira has their own design guidelines that we need to adhere to for pages on their side.

Screenshots

Unconfigured Jira App Page

GitHub Login Page

GitHub App Authorization

Organization Select Screen

Configured Jira App Page

Error when processing closed pull request

Found in Sentry: https://sentry.io/github-integrations/jira/issues/721597167/events/32750254925/

TypeError: Cannot read property 'html_url' of null
  createPullRequestUrl: `${pull_request.head.repo.html_url}/pull/new/${pull_request.head.ref}`,
                                                  ^
---
{
  event: pull_request.closed,
  id: dbae29a0-cc59-11e8-98a5-c8fed1b2beaa,
  installation: 366480,
  repository: xola/xola
}
--

There's only one event, but need to test if the pull_request.closed event sends head.repo in the payload. It might just need to be pull_request.repo.

Regex for branch and issue parsing

The DVCS connector used to parse the following: branchname.JIRA-KEY or branchname_JIRA-KEY. The new integration requires this to be -, eg: branchname-JIRA-KEY.

Perhaps this is a matter of updating the regex used in the integration.

Automate sync on installation

While in the testing stages, there is a manual Sync button that triggers the initial data sync. This should be automatic when the integration is first installed for new users. We can accomplish this by triggering the sync once the integration is installed, but we'll also want to listen for integration_installation_repositories.added events so we can trigger another sync when a user adds a new repository to their installation.

Move additions/deletions calculations per file and commit moved to another queue

Right now we have to do one request per commit pushed to get the number of lines added and deleted per file per commit, which makes the process take too much time.

Let's move the processing of that information to another queue to get most of the information processed as fast as possible and this, which has lower priority, will be processed in its own queue.

Get some internal testers

We'd like to aim for the end of this week. This will depend upon deployments #18.

cc @jmilas for letting people know about this

It is possible to connect an organisation for which GH user don't have an admin access

While connecting my GitHub account to Jira I can see the following options when choosing organisations to connect:

As discussed on the meeting I should not see the "integrations" organisation, because I don't have an admin access to it.

App sec review

This is a review of app sec before we release. More details to follow.

Consider sending merge commits with "preventTransitions=true" flag

When we do squash merge, we might have all commits messages from the branch copied to the merge commit.

In this case we might potentially have:

1. If there were any "smart commits" commands in the branch commits messages, then they might be executed again because they occurred in the smart commit
2. If there are some transitions triggers by submitting new commit configured in the issue workflow, then transitions might happen again.

To prevent it, please consider sending merge commit in a separate DevInfo API request with "preventTransitions=true" flag set.

Remove intermediary step for new GitHub installs.

When the app is installed to a new organization, it currently redirects back to the intermediary page and the user is forced to reselect their organization. Ideally, we'd take care of that for them so that it redirects back to Jira directly.

Improve the app listing page

The app listing page has no description and a transparent icon.

Let's improve this and make sure it all works nicely as part of #56.

Document development setup

Similar to https://github.com/integrations/slack/blob/master/CONTRIBUTING.md#getting-started

Set up a nice URL

A nice URL like https://jira.github.com that bounces over to the marketplace entry at https://github.com/marketplace/jira would be good.

Currently https://jira-integration-production.herokuapp.com/ redirects to https://github.com/apps/jira. Ideally that could redirect to https://github.com/marketplace/jira.

We should do this once the Marketplace listing is live: #20

Remove "write access" to code.

Currently the Jira app on GitHub requires "Write access". In a meeting, neither myself, @tcbyrd or @bkeepers could figure out why. Let's remove that permission from the Jira app.

Complete the list of capabilities in the Descriptor

It looks like our Atlassian Connect Descriptor is currently only subscribed to the Commit capability for the DevInfo API.

https://github.com/integrations/jira/blob/505c204b067d98b0c28c4c4ba183c0893aefdc34/lib/jira/connect.js#L36

We need to also add BRANCH and PULL_REQUEST per the docs here.

Implement remove old GitHub add-on API

https://github.com/integrations/jira/blob/cc5a3e1aac6104a33a0d89ef5c52d16a19a10b20/docs/jira-dev-info-0.10-swagger.yaml#L135-L156

It's called githubMigrationCompleted.

Commits on jira not up-to-date

I am not sure if this is a JIRA or a github integration issue, however if commits become unreachable due to rebasing, they still appear under the issue number in JIRA. The linked jira issue should only link reachable commits in repositories.

I could not find a bug or feature request to follow on this.

Feature request: Creation of bug in Jira based on Github security alert for vulnerable dependencies

In 2018, Github introduced security alerts for vulnerable dependencies in repos ref https://help.github.com/articles/about-security-alerts-for-vulnerable-dependencies/

This is an important security feature and many organisation would like to:

1. Act immediately by evaluating the impact the vulnerability has on their solutions
2. Keep a paper trail on decision process for the vulnerability.

To achive this, many use Jira today. It would make sense to extend the Github to Jira extension to allow the creation of new bug issues of high criticality when a vulnerability alert is triggered for a given Github repo.
Since April 2018 there exist a webhook in Github for the vulnerability alerts which can be used for this new feature ref https://developer.github.com/changes/2018-04-24-preview-dependency-graph-and-vulnerability-hooks/

Syncing data on initial setup

From the legacy-features doc:

We need to look at the initial sync as an important feature. This will most likely be used in the migration path from DVCS --> new integration.

The expectation would be on GitHub to re-sync everything from a historical perspective so their data is maintained in Jira Software

The scope doc doesn't currently include anything on the initial synchronization, and we know from experience that this has been a pain point for customers with the DVCS connector.

Jira Get Started page doesn't allow Administrators to access it.

When a user installs the app to Jira, it prompts them to "Get Started". Clicking on "Get Started" directs them to a forbidden page as no user has access to the page. This should be set to be available to anyone with access to add-on configuration.

Deploy JIRA Connector

This is just a general tracking issue to cover deploying the JIRA connector to the GitHub Infrastructure. More details to come.

Links within issues not appearing

On an issue I've inserted a comment that should match the regex, for example TES-2. It should be linked up by the Jira bot, however it doesn't seem to be.

Configuration (optional)

• Allows GitHub Enterprise instances to integrate with JIRA Enterprise

Configuration (required)

• Allows users to specify which repositories to synchronize with JIRA

Installing from the GitHub Marketplace

The flow to install from the Atlassian Marketplace is pretty straightforward. However the flow to do it from the GitHub Marketplace isn't as great. We get to the app install flow and then get to something like:

https://jira-integration-production.herokuapp.com/github/configuration?installation_id=322352&setup_action=install

This could be because the Marketplace is pointing to the production app, but we get this:

I'm curious what is meant to be showing on that page. The only one that is relevant is this one: https://sentry.io/github-integrations/jira/issues/674122106/?query=is:unresolved Required headers missing: x-hub-signature. In our meeting with @bkeepers and @tcbyrd it was mentioned that was unlikely to be the problem.

Link PR by Branch Name

We are using this integration as a replacement for the JIRA DVCS integration. One of the features we liked with it was that it would create links in JIRA to the PR if the branch name of the PR matched the JIRA key. This integration only links based on the PR title.

This integration already shows branches and commits, so including the branch name in the PR search would help catch PRs that might not have been named correctly, but clearly are related to the issue.

Other random ideas

A list of other ideas, none of which are required for V1.

• Creates a branch in GitHub from a JIRA ticket
• Displays Pull Request 'state' in JIRA - [open, closed], is mergeable, are all CI passing, state of reviews
• Modifies a Pull Request in GitHub from a JIRA ticket - Merge, Close
• Orchestrates branches or releases from JIRA
• Replaces GitHub issues with JIRA Issues
• Replaces GitHub Projects with Atlassian Project Boards
• Displays JIRA content in GitHub

Equivalence to existing DVCS Connector

The existing DVCS Connector is documented here.

• Allows users viewing a JIRA ticket to see URLs of associated GitHub data : Pull Requests, Commits, Branches.
• Enables JIRA smart commits from specific actions in GitHub - commit messages
  • Supports specific keywords from GitHub or Git data to associate data with JIRA
  • Closes JIRA issue - Synchronize with Pull Request closing
  • Allows adding a comment to a JIRA ticket from GitHub data
  • Allows specific actions transition JIRA ticket states

Use DevInfo 0.10 instead of 0.9

It looks like we're using an outdated version of the DevInfo API which Atlassian would like to deprecate. The docs for the new version can be found here https://drive.google.com/drive/folders/1ub7iuRsDWREGoTXMU14JSxxJ2nvvGVIX