GitHub for Atlassian integration FAQ

General questions about setting up GitHub for Atlassian

Why can't I see the author, reviewer names, or icons in Jira?

To see author, reviewer names, and icons in the development panel of your Jira work item, the email address associated with your GitHub account must match the email address in your Jira account. If these two email addresses are different, then the account names and icons will not show up in Jira. This behavior is similar to smart commits, which also require matching emails.

How can I migrate from DVCS Connector to GitHub for Atlassian?

If you’ve been using Jira’s built-in DVCS connector, you should migrate to the GitHub for Atlassian integration, as long as you meet the following requirements:

• This app officially supports http://GitHub.com (all editions including Enterprise Server) and Jira Cloud.

• Jira server is not supported.

If you haven’t already been prompted, you can manually kick off the migration:

1. Log in to your Jira Cloud account.

2. [設定] () > [Jira アプリ] の順に選択します。

3. Under Integrations in the sidebar, select DVCS accounts.

4. Follow the prompts to upgrade your GitHub connection.

Permissions requirements for GitHub for Atlassian

The permission scope for code and metadata suggests data is read to synchronize development information. Is code stored on Jira?

Commits, branches, and merges that occur in a connected GitHub repository will be seen on the dev panel in associated Jira work items. Whenever a commit message includes a work item key, it generates an event that is sent to Jira so the work item specified in the commit message can be updated. Our app needs code access to read commit messages and branch names to correctly link your data to your Jira work items, but no code is stored during this process. Our app simply sends data through to Jira.

Why does the app need metadata access to my repositories?

Read-only access to metadata is a mandatory requirement by GitHub for all GitHub apps. (Here’s more about the permissions required for GitHub apps.) This access makes it possible for GitHub apps to access various read-only endpoints for a number of resources. Our app will be able to see the repository’s code, however, Atlassian takes the security of our software very seriously. We constantly monitor our code for vulnerabilities and have processes in place to make sure it's safe to use. Additionally, GitHub documentation for metadata permissions states: “These endpoints do not leak sensitive private repository information.” If there are repositories you still don’t want our app to have access to, you can:

• select the repositories you want to grant access to when installing the app, or

• select the edit icon on the GitHub configuration page (or the “Connect an org” page) to update your GitHub settings.

Why are read and write permissions required for pull requests, contents and work items?

This is needed so our app can create links to Jira work items from pull request or work item comments. When you create a comment and include the work item key surrounded by square brackets, our app will ping Jira to see if that work item key exists in a Jira space. If it finds a matching work item, it will create a link for easy navigation. As for contents, we need the write access so we can create a branch on your request.

What happens if another change is made to the app in the future that requires new permissions? Can I choose to accept the new permission but ignore previously requested permissions that I don’t want/feel comfortable with?

Unfortunately not. GitHub apps are limited in this sense as permissions are not granular.

Smart Commits

スマート コミットが機能しないのはなぜですか?

Smart Commits make it easier for you and your team to comment on work items, transition work items, and add time tracking. To enable this for your teams you will need to make sure:

• The email address in your GitHub account matches the email address in your Jira account. For example, mypersonal@email.com in GitHub and mywork@email.com in Jira will prevent smart commits from working. However, mypersonal@email.com and mypersonal@email.com will work.

• You have unchecked 'Keep my email addresses private' in GitHub. If this is checked, GitHub will not send your email address as part of the payload when a webhook is fired. Jira treats this as a mismatch between emails and fails to meet the above criteria. To update this setting in GitHub, go to Settings, select Emails, and then uncheck the box next to Keep my email addresses private.

• You use the correct naming when transitioning. If you want to transition a work item from one column to another, please make sure you use the same naming for the column you want to transition the work item to. For example, if you want to flag a work item as complete and this column is called ‘Done' you’ll need to include #done in your commit message. (Words like #closed, #complete, etc, will not work unless those statuses are in fact in your workflow.)

• You aren't trying to 'jump' columns in your workflow. If transitions aren't working, make sure you are abiding by the workflow set up by your team's admin. For example, if you have 3 columns named 'todo', 'in progress' and 'done' but your admin has applied a rule that specifies work items can't be moved straight from 'todo' to 'done', any smart commit that tries to transition a work item from todo to done will fail. In this scenario, you need to first move your work item to #in-progress.

• You have enabled time tracking and added to each work item type. If you aren't seeing time tracking in your work items after adding something like #time 1w 2d 4h 30m to your commit message, ask you team's admin to check the site's settings. Here’s how to configure time tracking.

Backfilling data

データのバックフィルに長い時間がかかります。いつ Jira にデータが表示されますか?

When you connect a GitHub organization to Jira via the GitHub for Atlassian app, a process called “backfilling” begins. This process looks for work item keys in your historical data in GitHub. If it finds work item keys, it links your development data to existing work items in Jira.

When an organization contains a small amount of data, the backfilling process is relatively fast and may only take a few minutes. But when an organization contains a large amount of data, the backfilling process will take longer. The good news is you can start using work item keys in new branches, commits, and pull requests as soon as you’ve connected a Github organization to Jira - and this new data will be visible in Jira immediately.

Do I have to wait for all data to complete backfilling before I can start using the GitHub for Atlassian integration?

Nope! The job of backfilling is to pull in all your historical data so that, if any work item keys were referenced before you installed the app, you will eventually see that data in Jira. This means you can start using the app with your team immediately as the app will start listening and responding to webhook events (real-time data) straight away.

GitHub Enterprise Server

GitHub Enterprise Server に接続できないのはなぜですか?

Common reasons for connection problems with GitHub Enterprise Server include:

• アトラシアン IP アドレスを許可する必要があります。GitHub IP 許可リストの設定を表示する か、 サポート チームにお問い合わせください。

• SAML SSO は GitHub Enterprise Server ではサポートされていません (ただし、GitHub Enterprise Cloud は SAML SSO をサポートしています)。

• アトラシアン向け GitHub はリバース プロキシをサポートしていません。

• 自己署名証明書 (SSL) に問題があります。

アトラシアン アプリ向け GitHub で非公開キーと GitHub クライアント シークレットを更新するにはどうすればよいですか?

1. GitHub の設定ページが Jira に表示されます。

2. Find the GitHub app you want to update, select More actions (⋯), and select Edit.

3. Edit the GitHub client secret and/or private key, and select Update to save your changes.

複数の GitHub サーバーとアプリを接続できますか?

Yes. You can connect multiple GitHub Server to a single Jira account. You can also add multiple GitHub apps per Server to connect any GitHub organization to Jira. Read about rate limits for GitHub Apps

Can I create one primary GitHub app for multiple Jira sites?

いいえ、それぞれの GitHub アプリは 1 つの Jira インスタンスにしか接続できません。これは、セキュリティを維持してデータ漏えいを防ぐためです。

アプリの自動作成に GitHub Enterprise Server バージョン 3.1 が必要な理由は何ですか?

• アプリの自動作成は、バージョン 3.1 で追加された callback_url のサポートに依存しています。

• The GitHub for Atlassian app subscribes to three events that rely on GitHub Actions, which are available in version 3.0 or higher.

• GitHub は定期的に新しいバージョンをリリースして、古いバージョンのサポートを終了しています。バージョン 3.1 以降にアップグレードすると、最新の機能、バグ修正、改善、セキュリティ アップデートを常に新しい状態に保つことができます。

Server をアップグレードするには、GitHub のサポート ドキュメント「GitHub Enterprise Server のアップグレード」の手順に従ってください。

ワークフローの実行、デプロイのステータス、またはコード スキャン イベントのデータが表示されない理由は何ですか?

You may need to enable GitHub Actions in GitHub Enterprise Server. To enable GitHub Actions, follow the instructions in GitHub’s support documentation: Get started with GitHub Actions for GitHub Enterprise Server 3.2

アトラシアン向け GitHub はどのようにしてデータを取得しますか?

アトラシアン アプリ向け GitHub では、開発データを取得して Jira に送信するために、GitHub Enterprise Server にアクセスする必要があります。これを機能させるには、ネットワーク構成で、アトラシアンの IP アドレス リストから GitHub Enterprise Server への呼び出しを許可し、GitHub Enterprise Server から呼び出して HTTPS 経由で github.atlassian.com ドメインのアトラシアン Server に到達できるようにする必要があります。

• GitHub IP 許可リストの設定を表示します。

• アトラシアン IP アドレスの詳細をご確認ください。

アトラシアン アプリ向け GitHub は GitLab をサポートしていますか?

No, use the GitLab for Jira Cloud app to integrate Jira with GitLab.