Jira issues integration

Jira issues integration 可以将一个或多个 GitLab 项目连接到 Jira 实例。 你可以自行托管 Jira 实例，或者使用 Jira Cloud。 支持的 Jira 版本包括 6.x、7.x、8.x、9.x 和 10.x。

配置集成

先决条件：

• 你的 GitLab 安装不能使用 relative URL。
• 对于 Jira Cloud：
  • 你必须拥有 Jira Cloud API token 和创建该 token 时使用的电子邮件地址。
  • 如果你已启用 IP allowlists，请将 GitLab.com IP range 添加到允许列表中，以便在 GitLab 中 view Jira issues。
• 对于 Jira Data Center 或 Jira Server，你必须具备以下之一：
  • Jira 用户名和密码。
  • Jira personal access token（GitLab 16.0 及更高版本）。

你可以通过在 GitLab 中配置项目设置来启用 Jira issues integration。 你也可以为特定的 group 或整个 instance 在 GitLab Self-Managed 上配置集成。

通过此集成，你的 GitLab 项目可以与你实例上的所有 Jira 项目进行交互。 要在 GitLab 中配置项目设置：

1. 在左侧边栏，选择 Search or go to 并找到你的项目。
2. 选择 Settings > Integrations。
3. 选择 Jira issues。
4. 在 Enable integration 下，选择 Active 复选框。
5. 提供连接详情：
   • Web URL：你要链接到此 GitLab 项目的 Jira 实例 Web 界面的基础 URL（例如，https://jira.example.com）。
   • Jira API URL：Jira 实例 API 的基础 URL（例如，https://jira-api.example.com）。 如果未设置此 URL，则默认使用 Web URL 的值。 对于 Jira Cloud，请将 Jira API URL 留空。
   • Authentication method：
     • Basic：
       • Email or username：
         • 对于 Jira Cloud，输入电子邮件。
         • 对于 Jira Data Center 或 Jira Server，输入用户名。
       • API token or password：
         • 对于 Jira Cloud，输入 API token。
         • 对于 Jira Data Center 或 Jira Server，输入密码。
     • Jira personal access token（仅适用于 Jira Data Center 和 Jira Server）： 输入 personal access token。
6. 提供触发设置：
   • 选择 Commit、Merge request 或两者作为触发器。 当你在 GitLab 中提及 Jira issue ID 时，GitLab 会链接到该 issue。
   • 要在 Jira issue 中添加评论并链接回 GitLab， 选择 Enable comments 复选框。
   • 要在 GitLab 中 transition Jira issues automatically， 选择 Enable Jira transitions 复选框。
7. 在 Jira issue matching 部分：
   • 对于 Jira issue regex，输入正则表达式模式。
   • 对于 Jira issue prefix，输入前缀。
8. 可选。要在 GitLab中 view Jira issues， 在 Jira issues 部分：

   1. 选择 View Jira issues 复选框。

      当你启用此设置时，所有有权访问你的 GitLab 项目的用户 都可以查看你指定的 Jira 项目中的所有 issue。

   2. 输入一个或多个 Jira 项目键。 留空以包含所有可用的键。

9. 可选。要 create Jira issues for vulnerabilities， 在 Jira issues for vulnerabilities 部分：

   1. 选择 Create Jira issues for vulnerabilities 复选框。

      你只能为单个项目和组启用此设置。

   2. 输入一个 Jira 项目键。

   3. 选择 Fetch issue types for this project key（ ）， 然后选择要创建的 Jira issue 类型。

   4. 可选。选择 Customize Jira issues 复选框，以便在为漏洞创建 Jira issue 时能够查看、修改或添加详细信息。

10. 可选。选择 Test settings。
11. 选择 Save changes。

View Jira issues

先决条件：

• 确保 Jira issues integration 已 configured 并且选择了 View Jira issues 复选框。

你可以为特定的组或项目启用 Jira issues，但你只能在 GitLab 项目中查看这些 issue。 要在 GitLab 项目中查看来自一个或多个 Jira 项目的 issue：

1. 在左侧边栏，选择 Search or go to 并找到你的项目。
2. 选择 Plan > Jira issues。

默认情况下，issue 按 Created date 排序。 最近创建的 issue 显示在顶部。 你可以 filter issues 并选择一个 issue 以在 GitLab 中查看该 issue。

根据其 Jira status， issue 被分组到以下选项卡中：

• Open：具有除 Done 以外的任何 Jira status 的 issue。
• Closed：具有 Done Jira status 的 issue。
• All：具有任何 Jira status 的 issue。

Filter Jira issues

先决条件：

• 确保 Jira issues integration 已 configured 并且选择了 View Jira issues 复选框。

当你在 GitLab 中 view Jira issues 时， 你可以按标题和描述中的文本过滤 issue。 你还可以按以下条件过滤 issue：

• Label：在 URL 的 labels[] 参数中指定一个或多个 Jira issue 标签。 当指定多个标签时，只有包含所有指定标签的 issue 会显示 （例如，/-/integrations/jira/issues?labels[]=backend&labels[]=feature&labels[]=QA）。
• Status：在 URL 的 status 参数中指定 Jira issue status （例如，/-/integrations/jira/issues?status=In Progress）。
• Reporter：在 URL 的 author_username 参数中指定 Jira 显示名称 （例如，/-/integrations/jira/issues?author_username=John Smith）。
• Assignee：在 URL 的 assignee_username 参数中指定 Jira 显示名称 （例如，/-/integrations/jira/issues?assignee_username=John Smith）。
• Project：在 URL 的 project 参数中指定 Jira 项目键 （例如，/-/integrations/jira/issues?project=GTL）。

Jira verification

先决条件：

• 确保 Jira issues integration 已 configured 并且选择了 View Jira issues 复选框。

你可以设置验证规则，以确保在允许推送之前，提交消息中引用的 Jira issue 符合特定标准。此功能有助于保持 GitLab 和 Jira 之间的一致工作流程。

要配置 Jira verification：

1. 在左侧边栏，选择 Search or go to 并找到你的项目。
2. 选择 Settings > Integrations。
3. 选择 Jira issues。
4. 转到 Jira verification 部分。
5. 配置以下验证检查：
   • Check issue exists：验证提交消息中引用的 Jira issue 是否存在于 Jira 中。
   • Check assignee：验证提交者是否是提交消息中引用的 Jira issue 的 assignee。
   • Check issue status：验证提交消息中引用的 Jira issue 是否具有允许的状态之一。
   • Allowed statuses：允许的 Jira issue 状态的逗号分隔列表（例如，Ready, In Progress, Review）。仅当启用 Check issue status 时才显示此字段。
6. 选择 Save changes。

当用户尝试推送不符合验证标准的更改时，GitLab 会显示一条错误消息，说明推送被拒绝的原因。

示例错误消息

• 如果引用的 Jira issue 不存在（当启用 Check issue exists 时）：

  Jira issue PROJECT-123 does not exist.

• 如果引用的 Jira issue 未分配给提交者（当启用 Check assignee 时）：

  Jira issue PROJECT-123 is not assigned to you. It is assigned to Jane Doe.

• 如果引用的 Jira issue 的状态不在允许列表中（当启用 Check issue status 时）：

  Jira issue PROJECT-123 has status 'Done', which is not in the list of allowed statuses: Ready, In Progress, Review.

验证检查的用例

考虑以下示例：

1. 你的团队使用一种工作流程，其中 Jira issue 在积极开发时应处于特定状态。
2. 你配置 Jira verification 以：
   • 检查 issue 是否存在
   • 验证 issue 是否处于 “In Progress” 或 “Review” 状态
3. 开发者尝试推送带有提交消息 “Fix PROJECT-123 by adding validation” 的更改。
4. GitLab 检查：
   • Jira issue PROJECT-123 是否存在
   • issue 的状态是否为 “In Progress” 或 “Review”
5. 如果所有检查都通过，则允许推送。如果任何检查失败，则推送被拒绝并显示错误消息。

这确保你的团队通过在相应的 Jira issue 不处于正确状态时阻止代码更改来遵循正确的工作流程。

Create a Jira issue for a vulnerability

先决条件：

• 确保 Jira issues integration 已 configured 并且选择了 Create Jira issues for vulnerabilities 复选框。
• 你必须拥有在目标项目中创建 issue 的 Jira 用户账户权限。

你可以从 GitLab 创建 Jira issue 来跟踪解决或缓解漏洞所采取的任何操作。 要为漏洞创建 Jira issue：

1. 在左侧边栏，选择 Search or go to 并找到你的项目。

2. 选择 Secure > Vulnerability report。

3. 选择漏洞的描述。

4. 选择 Create Jira issue。

   如果选中了 Customize Jira issues 设置，你将被重定向到 Jira 实例上的 issue 创建表单，其中预填充了漏洞数据。你可以在创建 Jira issue 之前查看、修改或添加详细信息。

issue 在目标 Jira 项目中创建，包含来自漏洞报告的信息。

要创建 GitLab issue，请参阅 Create a GitLab issue for a vulnerability。

Create a Jira Cloud API token

要为 Jira Cloud 配置 Jira issues integration，你必须拥有 Jira Cloud API token。 要创建 Jira Cloud API token：

1. 从具有 Jira 项目写入权限的账户登录 Atlassian。

   该链接将打开 API tokens 页面。或者，从你的 Atlassian 个人资料中选择 Account Settings > Security > Create and manage API tokens。

2. 选择 Create API token。

3. 在对话框中，为你的 token 输入标签，然后选择 Create。

要复制 API token，选择 Copy。

Migrate from one Jira site to another

要在 GitLab 中从一个 Jira 站点迁移到另一个 Jira 站点并保持你的 Jira issues integration：

1. 遵循 configure the integration 中的步骤。
2. 输入新的 Jira 站点 URL（例如，https://myjirasite.atlassian.net）。

要更新 GitLab 中现有的 Jira issue 引用以使用新的 Jira 站点 URL，你必须 invalidate the Markdown cache。