GitLab Jira integration

原文：https://docs.gitlab.com/ee/user/project/integrations/jira.html

GitLab Jira integration

GitLab 问题是讨论想法，计划和跟踪工作的强大工具. 但是，许多组织已经将 Jira 用于这些目的，并且内置了广泛的数据和业务流程.

尽管您始终可以将内容和流程从 Jira 迁移到 GitLab Issue，但是您也可以选择继续使用 Jira，并通过我们的集成将其与 GitLab 一起使用.

有关与 Jira 集成的视频演示，请观看有关GitLab 工作流程的 Jira 问题和 Jenkins 管道 .

将 GitLab 项目与 Jira 实例集成后，即可自动检测 GitLab 项目与 Jira 中的任何项目之间的活动并进行交叉引用. 这包括在 GitLab 中完成工作后关闭或转换 Jira 问题的功能.

在 GitLab 中执行以下操作时，集成的响应方式如下：

  • 在提交消息或 MR（合并请求）中提及 Jira 问题 ID .
    • GitLab 超链接至 Jira 问题.
    • Jira 问题将问题链接添加到 GitLab 中的提交/ MR.
    • Jira 问题会添加评论，以反映在 GitLab 中发表的评论，评论作者以及在 GitLab 中指向 commit / MR 的链接，除非禁用了对 Jira 的评论.
  • 提及提交或 MR”关闭”，”解决”或”修复” Jira 问题 ID . 在项目的默认分支（通常是主分支）上进行提交或将更改合并到默认分支时：
    • GitLab 的合并请求页面显示一条注释，指出”已关闭” Jira 问题，并带有指向该问题的链接. （注意：在合并之前，MR 将显示它”关闭”了 Jira 问题.）
    • Jira 问题显示活动，并且 Jira 问题已关闭或已转换.

您还可以直接从 GitLab 使用Jira 的 Smart Commit，如文章如何以及为什么将 GitLab 与 Jira 集成中所述 .

Configuration

每个 GitLab 项目都可以配置为连接到整个 Jira 实例. 这意味着一个 GitLab 项目一旦配置，便可以与该实例中的所有 Jira 项目进行交互. 因此，您不必将 GitLab 项目与任何单个 Jira 项目显式关联.

如果您有一个 Jira 实例，则可以使用默认模板预先填充设置页面. 请参阅服务模板文档.

为了在 GitLab 中启用 Jira 服务，您需要首先在 Jira 中配置项目，然后在 GitLab 中输入正确的值.

Configuring Jira

Jira Server

Jira Server支持基本身份验证. 连接时，需要用户名和密码 . 请注意，无法通过 CAS 连接到 Jira Server. 首先在 Jira Server 中设置用户，然后继续配置 GitLab .

Jira Cloud

Jira Cloud支持通过 API 令牌进行身份验证. 连接到Jira Cloud 时 ，需要电子邮件和 API 令牌 . 首先在 Jira Cloud 中设置用户，然后继续配置 GitLab .

Configuring GitLab

Notes:

  • 当前支持的 Jira 版本是v6.x, v7.x, v8.x . 需要 GitLab 7.8 或更高版本.
  • GitLab 8.14 引入了一种与 Jira 集成的新方法，该方法大大简化了您必须输入的配置选项. 如果您使用的是旧版本，请遵循此文档 .
  • 为了支持 Oracle 的 Access Manager，GitLab 将发送其他 cookie 以启用基本身份验证. 添加到每个请求的 cookie 是OBBasicAuth ，其值为fromDialog .

要在项目中启用 Jira 集成，请导航到Integrations 页面 ，单击Jira服务，然后按照下表中的说明在页面上填写所需的详细信息.

Field Description
Web URL 链接到此 GitLab 项目的 Jira 实例 Web 界面的基本 URL. 例如， https://jira.example.com .
Jira API URL The base URL to the Jira instance API. Web URL value will be used if not set. E.g., https://jira-api.example.com. Leave this field blank (or use the same value of Web URL) if using 吉拉云.
Username/Email 在配置 Jira step时创建. 将username用于Jira Server或将email用于Jira Cloud .
Password/API token 在配置 Jira 步骤中创建. 为Jira Server使用password或为Jira Cloud使用API token .
Transition ID 这是将问题移至所需状态的过渡的 ID. 它可以插入过渡 IDS 分离通过,或; 这意味着将按照给定的顺序将问题逐个移至每个州. 如果您未正确设置 ID，则无法通过提交或合并请求来关闭 Jira 问题.

Obtaining a transition ID

在最新的 Jira 用户界面中，您不再可以在工作流管理 UI 中看到过渡 ID. 您可以通过以下两种方式之一获取所需的 ID：

  1. 通过使用 API​​，并使用诸如处于适当”打开”状态的问题的请求（例如https://yourcompany.atlassian.net/rest/api/2/issue/ISSUE-123/transitions
  2. 通过将鼠标悬停在所需转换的链接上并在 URL 中查找” action”参数

请注意，即使您要更改的状态相同，过渡 ID 在工作流之间也可能有所不同（例如，错误与故事）.

保存配置后，您的 GitLab 项目将能够与 Jira 实例中的所有 Jira 项目进行交互，并且您将在 GitLab 项目页面上看到 Jira 链接，该链接将您带到适当的 Jira 项目.

Jira service page

Disabling comments on Jira issues

当您引用 Jira 问题时，它将始终链接回 GitLab 中的源提交/ MR，但是，您可以控制 GitLab 是否还将交叉发布对 Jira 问题的评论. 默认情况下启用该功能.

要禁用对 Jira 问题的自动评论：

  1. 打开” 集成”页面，然后选择Jira .
  2. 在” 事件操作”部分中，取消选中” 注释” .

Jira issues

现在，您应该已经配置了 Jira并在 GitLab 中启用了Jira 服务 . 如果一切设置正确，您应该能够通过在 GitLab 提交和合并请求中提及 ID 来引用和关闭 Jira 问题.

Referencing Jira Issues

当 GitLab 项目配置并启用了 Jira 问题跟踪器时，在 GitLab 中提及 Jira 问题将自动在 Jira 问题中添加评论，并带有返回到 GitLab 的链接. 这意味着在合并请求和提交中引用问题的注释中，例如PROJECT-7 ，将在 Jira issue 中添加以下格式的注释：

  1. USER mentioned this issue in RESOURCE_NAME of [PROJECT_NAME|LINK_TO_COMMENT]:
  2. ENTITY_TITLE
  • USER提到问题的用户. 这是指向 GitLab 中的用户配置文件的链接.
  • LINK_TO_THE_COMMENT链接到提及的来源，带有提及吉拉问题的实体的名称.
  • RESOURCE_NAME引用该问题的RESOURCE_NAME种类. 可以是提交或合并请求.
  • PROJECT_NAME GitLab 项目名称.
  • ENTITY_TITLE合并请求标题或提交消息的第一行.

example of mentioning or closing the Jira issue

例如，以下提交将引用以PROJECT-1作为 ID 的 Jira 问题：

  1. git commit -m "PROJECT-1 Fix spelling and grammar"

Closing Jira Issues

通过在提交和合并请求中使用触发词，可以直接从 GitLab 关闭 Jira 问题. 当推送包含触发词并在提交消息中包含 Jira 问题 ID 的提交时，GitLab 将在提到的 Jira 问题中添加注释，并立即将其关闭（前提是正确设置了转换 ID）.

当前有三个触发词，您可以使用其中一个来实现相同的目标：

  • Resolves PROJECT-1
  • Closes PROJECT-1
  • Fixes PROJECT-1

其中PROJECT-1是 Jira 问题的 ID.

Notes:

  • 只有提交并合并到项目的默认分支（通常是master ）才能关闭 Jira 中的问题. 您可以在项目设置下更改项目默认分支.
  • 如果有解决方案，那么 Jira 问题将不会过渡.

Jira issue closing example

让我们考虑以下示例：

  1. 对于 Jira 中名为PROJECT ，我们实现了一项新功能，并在 GitLab 中创建了合并请求.
  2. This feature was requested in Jira issue PROJECT-7 and the merge request in GitLab contains the improvement
  3. 在合并请求描述中，我们使用问题关闭触发器Closes PROJECT-7 .
  4. 合并请求合并后，Jira 问题将自动关闭，并带有注释和指向解决该问题的提交的关联链接.

在以下屏幕截图中，您可以看到指向 Jira 问题的链接的外观.

A Git commit that causes the Jira issue to be closed

合并此合并请求后，将通过指向解决该问题的提交的链接自动关闭 Jira 问题.

The GitLab integration closes Jira issue

Troubleshooting

如果这些功能不能按预期方式工作，则可能是由于集成设置的配置存在问题.

GitLab is unable to comment on a Jira issue

如果您希望 GitLab 也可以这样做，请确保您为集成设置的 Jira 用户具有正确的访问权限，可以发表有关 Jira 问题的评论并转换问题. 如果禁用了 GitLab 问题跟踪器，则 Jira 问题参考和更新注释将不起作用.

GitLab is unable to close a Jira issue

确保在” Jira”设置中设置的” Transition ID与您的项目解决问题所需的Transition ID匹配.

确保尚未将 Jira 问题标记为已解决； 也就是说，未设置” Jira 问题解决”字段. （不应在 Jira 列表中删除它.）

CAPTCHA

在连续几次失败的登录尝试后，可能会触发 CAPTCHA，这可能会在测试 Jira 集成时导致401 unauthorized错误. 如果已触发验证码，则您将无法使用 Jira 的 REST API 对 Jira 站点进行身份验证. 您将需要登录到您的 Jira 实例并完成 CAPTCHA.