GitHub for Jira

关于

将您的GitHub代码与Jira中的项目管理连接起来。需要单独的Jira订阅。通过连接这两个最重要的工具，您将花更少的时间管理项目，更多的时间用于实际工作。这个集成是一个开源项目，由Atlassian构建和维护。

支持

对于一般支持询问和错误报告，请联系Atlassian支持团队。对于功能请求，请创建一个新的issue。

目录

• 安装应用
  • 要求
  • 从Jira Cloud站点安装
  • 从Atlassian Marketplace安装
  • 从GitHub Marketplace安装
• 配置应用
  • 将GitHub组织连接到Jira
  • 连接新的GitHub仓库
• 管理应用
  • 授权
    • Jira权限范围
    • GitHub权限范围
      • 仓库权限
      • 组织权限
      • 我们的应用订阅的事件
  • 管理Jira订阅
• 发送数据并使用集成
  • 在Jira中查看GitHub开发信息
  • 在GitHub中查看Jira问题
  • 在Jira中查看GitHub构建和部署
  • 集成如何工作
  • 回填如何工作
• 从DVCS连接器迁移
• 企业功能
  • IP允许列表
  • 已知问题
    • 连接启用SSO的GitHub组织
• 需要帮助？
• 贡献
• 许可证

安装应用

要求

此应用正式支持GitHub.com（包括所有版本的Enterprise）和Jira Cloud。未来可能会考虑支持GitHub Enterprise Server和/或Jira服务器。

从Jira Cloud站点安装

这是在Jira站点和GitHub组织中安装应用的推荐方法。

1. 登录您的Jira Cloud账户。
2. 在Jira顶部导航栏中，选择应用 > 查找新应用。您也可以点击右上角的齿轮图标并选择应用。
3. 搜索GitHub for Jira并选择获取应用
4. 应用安装完成后，右上角会弹出一个标志。点击开始使用以连接您的GitHub账户。如果您错过了这个标志，请从应用菜单中点击配置集成。

接下来，您需要配置应用。

从Atlassian Marketplace安装

1. 前往Atlassian Marketplace。
2. 登录您的Atlassian账户并点击立即获取。
3. 选择要安装此应用的站点，点击安装应用。
4. 您将被带到Jira站点上的应用列表页面，点击获取应用。
5. 应用安装完成后，右上角会弹出一个标志。点击开始使用以连接您的GitHub账户。如果您错过了这个标志，请从应用菜单中点击配置集成。

接下来，您需要配置应用。

从GitHub Marketplace安装

1. 前往https://github.com/marketplace/jira-software-github。
2. 为您的GitHub组织完成（免费）订购。
3. 在安装设置界面上选择您想要与Jira集成使用的仓库，然后点击安装。
4. 您将被引导到一个设置页面，选择您的Jira站点。
5. 安装完成后，您将被重定向到Atlassian Marketplace来安装GitHub for Jira应用。
6. 从那里，按照上面的说明从Atlassian Marketplace安装。

配置应用

将GitHub组织连接到Jira

作为安装流程的一部分，您应该被引导到Jira应用中的GitHub配置界面来配置您的GitHub组织。

:warning: 如果您没有被引导，请导航到Jira实例的应用页面，并在"GitHub"标题下点击配置集成。如果您没有看到这个，请点击管理您的应用，然后在GitHub for Jira下点击开始使用（仅对Jira管理员可见）。这将带您进入应用的配置界面。

选择连接GitHub组织，然后选择GitHub Cloud或GitHub Enterprise Server。

• 如果您选择GitHub Cloud，您将被重定向到一个页面，在那里您可以连接到GitHub中的组织。

• 如果您选择GitHub Enterprise Server，您需要提供服务器的URL并创建一个GitHub应用。

在连接GitHub组织页面上，选择您想要连接的组织和仓库。

:warning: 如果您没有看到您的组织，请点击在新组织上安装Jira，并按照步骤在GitHub上安装应用并允许它查看您的仓库的权限。您也可以随时在同一界面上管理现有连接或添加其他组织。

有关如何连接到Cloud或Server的详细说明，请阅读我们的支持文档。

连接新的GitHub仓库

如果您最初授予GitHub for Jira应用访问"所有仓库"的权限，并且在配置后在GitHub上创建了新仓库，您的新仓库将自动与集成配合使用。但是，如果您只在部分仓库上安装了该应用，您需要通过以下步骤手动编辑您的仓库选择：

1. 登录您的Jira Cloud账户
2. 从Jira顶部导航栏中，选择应用 > 管理您的应用 - GitHub for Jira > 开始使用。
3. 选择相关GitHub组织旁边的配置，并添加您希望应用与之集成的新仓库。

管理应用

授权

通过授予应用访问权限，您将为您的GitHub和Jira账户提供以下授权：

Jira权限范围

对开发信息（分支、提交和拉取请求）的读取、写入和管理权限，以及对安全信息（Dependabot、代码扫描和秘密扫描）的读取权限。

GitHub权限范围

仓库权限

权限范围	应用需要它的原因
只读访问操作	对操作的只读访问公开了workflow_runwebhook事件。此事件包括诸如artifacts_url、check_suite_id、conclusion、head_branch和head_sha等信息。
只读访问代码扫描警报/安全事件	如果您想在Jira中看到GitHub代码扫描警报的链接或将代码扫描警报作为Jira中安全的一部分查看，应用将需要对安全事件的读取权限。GitHub应用将监听code_scanning_alertwebhooks并将安全报告的详细信息发送到Jira。这些信息将出现在Jira问题开发面板的"其他链接"选项卡下，以及Jira安全漏洞表中。
只读访问dependabot警报	如果您想在Jira的安全部分中看到您的dependabot警报，应用将需要对dependabot警报的读取权限。GitHub应用将监听dependabot_alertwebhooks并将安全报告的详细信息发送到Jira。这些信息将出现在Jira安全漏洞表中。
只读访问秘密扫描警报	如果您想在Jira的安全部分中看到您的秘密扫描警报，应用将需要对秘密扫描警报的读取权限。GitHub应用将监听secret_scanning_alertwebhooks并将安全报告的详细信息发送到Jira。这些信息将出现在Jira安全漏洞表中。
只读访问部署	如果您想在Jira中看到构建和部署信息，应用将需要对部署的读取权限。这将允许集成监听deployment_statuswebhook事件，该事件在创建部署时发生。只读部署权限用于以下webhooks：<br> - 部署状态
只读访问元数据	元数据 所有GitHub应用默认都设置了只读元数据权限。这是GitHub的强制要求，需要提供对各种资源元数据的只读端点集合的访问权限。这些端点不提供敏感的私有仓库信息。只读元数据权限用于以下webhook：<br> - 仓库
读取和写入问题和拉取请求的权限	GitHub for Jira应用使用问题和拉取请求来支持智能提交操作和展开Jira URL。"展开"意味着应用在拉取请求或问题评论中查找方括号内的Jira问题键（如[ABC-123]），然后将这些问题键替换为相应Jira问题的链接。<br><br> **问题：**读取和写入问题权限用于以下webhooks：<br> - 问题评论 <br> - 问题 <br><br> **拉取请求：**读取和写入拉取请求权限用于以下webhooks：<br> - 拉取请求 <br> - 拉取请求审查 <br> <br> 注意： <ol><li>方括号是必需的，如果没有方括号，拉取请求可能会出现在Jira问题的开发部分，但问题键不会被展开为链接。</li><li>对于GitHub Enterprise集成（用户拥有GitHub应用的情况），"写入"权限是可选的。如果不提供，"展开"逻辑将被轻微跳过。</li></ol>
读取和写入内容的权限	内容（又称代码）：需要只读权限来同步开发信息到Jira，用于以下webhooks：<br> - 提交评论 <br> - 删除 <br> - 推送 <br> - 工作流运行 <br><br> 我们需要创建webhook的写入权限，以便您能够从问题的开发面板创建分支。<br><br> *注意：*对于GitHub Enterprise集成（用户拥有GitHub应用的情况），"写入"权限是可选的。如果不提供，"创建分支"功能将无法使用。

组织权限

权限范围	应用需要它的原因
只读访问成员	用于确定您是否对GitHub组织有管理权限。

我们的应用订阅的事件

事件	该事件发生时
代码扫描警报 / 安全事件	创建代码扫描警报、在分支中修复或关闭
提交评论	创建提交评论
创建	创建 Git 分支或标签
删除	删除 Git 分支或标签
Dependabot 警报	Dependabot 警报自动忽略、自动重新打开、创建、忽略、重新打开、修复或重新引入
部署状态	创建部署
议题评论	与议题或拉取请求评论相关的活动
议题	与议题相关的活动
拉取请求	与拉取请求相关的活动
拉取请求审查	与拉取请求审查相关的活动
推送	将一个或多个提交推送到仓库分支或标签
仓库	与仓库相关的活动
秘密扫描警报	创建、解决或重新打开秘密扫描警报
工作流运行	请求或完成 GitHub Actions 工作流运行时

有更多关于权限的问题？请查看我们的常见问题文档。如果找不到问题的答案，请随时提出问题并将您的问题发送给我们的团队。我们很乐意回答并相应地更新我们的常见问题文档。

管理 Jira 订阅

此外，安装的管理员可以查看和删除 GitHub 对其他 Jira 实例的订阅，而无需登录 Jira 实例本身。如果您的安装设置为向您不再有权访问的 Jira 实例发送开发信息，或者审核组织中其他管理员之前可能配置的实例，这将非常有用。

导航到 Jira 订阅

1. 点击连接 GitHub 组织。
2. 点击组织旁边的编辑图标。

:information_source: 这只给予您删除与 Jira 实例连接的权限。要在该 Jira 实例中查看开发信息，您需要在 Jira 中获得访问权限。

发送数据并使用集成

在 Jira 中查看 GitHub 开发信息

要开始在 Jira 中查看来自 GitHub 的开发信息，只需在提交消息、分支名称或 PR 标题中添加 Jira 议题键。

例如：文本 [DEV-2095] 将被发送到 Jira，并出现在键为 DEV-2095 的 Jira 议题的开发信息部分。与此提交相关的任何分支、提交、拉取请求、构建和部署现在都将显示在 Jira 中。您可以在这里找到更多关于如何在开发工作中引用议题的信息。

在 GitHub 中查看 Jira 议题

如果议题正文包含您实例上的有效 Jira 议题键，当用方括号 [] 括起来时，集成将自动将其展开（展开）为引用链接。例如：[DEV-2095] 将被转换为指向 https://<your-instance>.atlassian.net/browse/DEV-2095 的链接。

这样，Jira 议题可以在评论中链接，而不会打断整个评论的流程。

**注意：**必须使用方括号，否则拉取请求可能会出现在 Jira 议题的开发部分，但议题键不会被展开为链接。

在 Jira 中查看 GitHub 构建和部署

GitHub Actions 工作流和部署将自动发送到您连接的 Jira 实例，以便在 Jira 议题中可见。如果您是首次设置，请按照 GitHub Actions 文档 - GitHub Docs 进行操作。如果您已经有 GitHub Actions 并希望在 Jira 中看到来自 GitHub 的 CI/CD 数据，请在提交消息、分支名称或 PR 标题中包含 Jira 议题键。

另请参阅我们的构建和部署指南。

在 Jira 中查看 GitHub 安全警报

GitHub 中的 Dependabot、代码扫描和秘密扫描警报将发送到 Jira，使您的团队能够在 Jira 中跟踪漏洞，并创建 Jira 议题以帮助管理安全工作。

了解更多关于 Jira 中的安全功能。

集成如何工作

当工作流（例如 GitHub Action）、开发事件（例如拉取请求、提交、分支）或安全事件（例如 dependabot、代码扫描或秘密扫描警报）运行时，应用程序会从 GitHub 接收 webhook。对于开发信息，应用程序会从相应的分支/提交/PR 中提取议题键，并将这些信息发送到 Jira；对于安全警报，则不需要议题键。

回填如何工作

该应用程序设计用于将历史数据回填到 Jira。一旦您成功安装和配置了应用程序，它将自动触发回填过程，回填 6 个月的数据，将允许的仓库的历史信息（如拉取请求、部署、分支、构建、提交和安全警报）更新到 Jira。初始回填过程完成后，您将能够在用户界面上查看回填日期和状态。所有分支都将被回填，无论它们的创建日期如何。但是，拉取请求、部署、构建、提交和安全警报只会回填最近六个月的数据。如果您希望在 Jira 中拉取更多历史数据，可以从操作菜单中选择"继续回填"来继续回填更早日期的数据。如果历史数据量很大，我们建议您每次回填 6 个月的数据，并继续这个过程，直到达到所需的回填日期。 符合以下标准的历史数据将在Jira中可用：

1. 回填过程会尝试连接满足至少一项以下标准的所有分支：
   • 分支名包含问题键。
   • 与该分支关联的最新拉取请求标题包含问题键。
   • 分支的最后一条提交消息包含问题键。
2. 默认分支的所有提交都将被回填。提交消息必须包含Jira问题键。
3. 非默认分支只会回填最新的50个提交。
4. 无法访问的提交（如已删除分支的提交）将不会被回填。
5. 所有拉取请求，无论其状态如何，都将被回填。Jira问题键应包含在拉取请求的标题、描述或源分支名称中。
6. 包含问题键的所有构建和部署数据将被回填。你可以查看如何在构建和部署中包含问题键此处。
7. 出现在主分支或受保护分支上的所有dependabot、代码扫描和密钥扫描警报将被回填。

如果在回填过程中出现错误，应用程序将提示你重试失败仓库的回填，无需重新启动整个回填过程。但这并不包括权限错误。在重试回填过程之前，你需要解决所有权限错误。

从DVCS连接器迁移

满足要求的Jira内置DVCS连接器的现有用户应迁移到此集成。如果你尚未收到提示，可以通过以下步骤手动启动迁移：

1. 登录到你的Jira Cloud账户。
2. 从Jira左侧边栏选择Jira设置 > 应用程序 > DVCS账户。
3. 按照提示升级你的GitHub连接。

企业功能

IP允许列表

GitHub能够限制谁可以与你组织的GitHub API通信，我们现在完全支持这一功能。 要启用此功能或调试任何问题，请参阅我们的GitHub IP允许列表文档。

已知问题

连接启用SSO的GitHub组织

如果GitHub组织受SAML保护， 你可能会发现其"连接"按钮被禁用。这可能发生在以下场景中： 当用户令牌（GitHub for Jira应用程序的UI正在使用）没有权限访问受保护的组织时， 因为它是在用户在浏览器中没有活动的GitHub SAML会话时颁发并保存到应用程序会话中的。

要解决此问题，请执行以下操作：

• 通过访问https://github.com/organizations/<你的组织名称>/settings创建一个活动的SAML会话
  • 这应该会启动与你的SSO身份提供商的身份验证过程
• 在同一浏览器窗口中，转到GitHub for Jira应用程序，找到<你的组织名称>GitHub组织的禁用"连接"按钮
  • 它必须位于以下页面之一
    • GitHub云版：https://github.atlassian.com/github/configuration，或
    • GitHub服务器企业版：https://github.atlassian.com/github/<UUID>/configuration
• 在浏览器中的页面URL中插入resetGithubToken=true查询参数并重新加载
  • GitHub云版：https://github.atlassian.com/github/configuration?resetGithubToken=true，或
  • GitHub服务器企业版：https://github.atlassian.com/github/<UUID>/configuration?ghRedirect=to&resetGithubToken=true

完成这些步骤后，GitHub将重新颁发具有所有必要权限的令牌并保存在应用程序的会话中， "连接"按钮应该变为可用。

需要帮助？

查看我们支持指南中的故障排除步骤。

贡献

想要帮助改进GitHub和Jira之间的集成吗？查看贡献文档以参与其中。

许可证

该项目以MIT许可证的条款作为开源提供。

使用GitHub徽标时，请务必遵守GitHub徽标指南。