Help us learn about your current experience with the documentation. Take the survey.

Jira 到 GitLab VSA 集成

  • Tier: Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

GitLab Value Stream Analytics (VSA) 为您的开发工作流程提供强大的洞察力，跟踪以下关键指标：

  • Lead time（前置时间）：从问题创建到完成的时间
  • Issues created（创建的问题数）：特定时间段内新增问题的数量
  • Issues closed（关闭的问题数）：特定时间段内已解决问题的数量

对于使用 Jira 进行问题跟踪，同时使用 GitLab 进行开发的团队，此集成能够实时自动地将 Jira 问题复制到 GitLab。这确保了准确的 VSA 指标，而无需团队更改现有的 Jira 工作流程。

该集成还会填充 GitLab 的 Value Streams Dashboard（仅限 Ultimate），它提供了关键 DevSecOps 指标的概览，您可以在 GitLab 项目或组的 Analyze > Analytics dashboards 下找到它。

注意：存在一个类似的集成用于事件复制以生成特定的 DORA 指标（变更失败率和恢复服务时间）。如果您对事件复制感兴趣，请参考 Jira Incident Replicator。

架构

我们将使用 Jira 自动化创建 2 个自动化工作流：

  1. 在 Jira 中创建问题时，在 GitLab 中创建问题
  2. 在 Jira 中解决问题时，关闭 GitLab 中的问题

问题创建

当在 Jira 中创建新问题时，自动化工作流程会向 GitLab Issues API 发送 POST 请求，以在指定的 GitLab 项目中创建相应的问题。

问题解决

当 Jira 问题转换为已解决状态（Closed、Done、Resolved）时，自动化工作流程会发送 PUT 请求来关闭相应的 GitLab 问题。

设置

先决条件

本指南假设您已具备：

  • 一个用于生成 VSA 分析的 GitLab 项目
  • 一个用于复制问题的 Jira 项目
  • GitLab Ultimate 或 Premium 许可证（用于 Value Stream Analytics 功能）

Jira 根据 Jira 许可证对自动化运行的频率设置了限制：

Tier Limit
Free 每月 100 次运行
Standard 每月 1700 次运行
Premium 每月每用户 1000 次运行
Enterprise 无限次运行

每次问题创建计为 1 次运行，每次问题解决计为 1 次运行。

GitLab 项目访问令牌

首先，我们需要创建一个 GitLab 项目访问令牌，具有通过 API 创建和更新问题的必要权限。

  1. 导航到您希望复制 Jira 问题的 GitLab 项目。从侧边栏，转到 Settings > Access Tokens。
  2. 点击 Add new token。
  3. 设置以下配置：
    • Token name: Jira VSA Integration（或任何描述性名称）
    • Expiration date: 根据您的安全策略设置
    • Role: Owner（这是设置自定义问题 ID 所需的）
    • Scopes: 勾选 api（完全 API 访问）

重要：需要 Owner 级别的访问令牌，因为集成需要在创建 GitLab 问题时强制设置自定义问题 ID。这确保当 Jira 问题被关闭时，自动化可以使用相同的 ID 映射来识别并关闭相应的 GitLab 问题。如果没有 Owner 角色，GitLab API 将不允许设置自定义问题 ID，这将破坏 Jira 问题关闭和 GitLab 问题关闭之间的同步。

  1. 点击 Create project access token 并安全保存生成的令牌 - 您将需要它来设置 Jira 自动化。

Jira 问题创建工作流

要在创建 Jira 问题时自动创建 GitLab 问题，我们将使用 Jira automation。

  1. 导航到您的 Jira 项目。从侧边栏，转到 Project settings > Automation。

  2. 在右上角点击 Create rule。

  3. 对于触发器，搜索并选择 Issue created。点击 Save。

  4. 可选：添加条件来过滤应该复制哪些问题。例如，您可能想要添加一个 Issue fields condition 来只复制特定类型或带有特定标签的问题。

  5. 选择 THEN: Add an action。搜索并选择 Send web request。

  6. 配置 Web 请求：

    • Web request URL: https://gitlab.com/api/v4/projects/<GITLAB_PROJECT_ID>/issues（如果是自托管，将 gitlab.com 替换为您的 GitLab 实例 URL，将 <GITLAB_PROJECT_ID> 替换为您的 GitLab 项目的数字 ID，例如 42718690）
    • HTTP method: POST
    • Web request body: Custom data

  7. 添加以下标头：

    Name Value
    Authorization Bearer <YOUR_GITLAB_TOKEN>
    Content-Type application/json

    为安全起见，将 Authorization 标头设置为 “Hidden”。

  8. 在 Custom data 字段中，输入：

    {
  "title": "{{issue.summary}}",
  "iid": {{issue.key.replace("VSA-", "1000")}}
}

    将 "VSA-" 替换为您的 Jira 项目前缀（例如，如果您的 Jira 问题编号为 PROJ-123，请使用 "PROJ-"）。1000 是一个基础数字，用于确保与可能通过 UI 直接在 GitLab 中创建的问题不发生冲突 - 您可以根据需要调整此值。

  9. 点击 Save，为您的自动化命名（例如 Jira to GitLab Issue Creation），然后点击 Turn it on。

Jira 问题解决工作流

创建第二个自动化工作流，在 Jira 问题时关闭 GitLab 问题：

  1. 按照创建工作流的步骤 1-2 开始新规则。

  2. 将触发器设置为 Issue transitioned：

    • 将 “From status” 字段留空
    • 将 “To status” 设置为已解决状态：Closed、Done、Resolved（根据您的 Jira 工作流程调整）

  3. 跳过条件（如果需要，添加自定义条件）。

  4. 添加一个 Send web request 操作，包含：

    • Web request URL: https://gitlab.com/api/v4/projects/<GITLAB_PROJECT_ID>/issues/{{issue.key.replace("<JIRA_PROJECT_PREFIX>-", "1000").urlEncode}}（如果是自托管，将 gitlab.com 替换为您的 GitLab 实例 URL，将 <GITLAB_PROJECT_ID> 替换为您的 GitLab 项目的数字 ID，将 <JIRA_PROJECT_PREFIX> 替换为您的 Jira 项目前缀，如 VSA 或 PROJ）
    • HTTP method: PUT
    • Web request body: Custom data

  5. 使用与创建工作流相同的标头。

  6. 在 Custom data 字段中，输入：

    {
  "state_event": "close"
}

  7. 保存并启用自动化规则，使用描述性名称（例如 Jira to GitLab Issue Closer）。

Value Stream Analytics 配置

一旦您的自动化工作流激活，GitLab 将开始接收问题数据。以下是访问您分析数据的方法：

Value Streams Dashboard（自动 - 仅限 Ultimate）

Value Streams Dashboard 会自动填充来自您复制的问题的指标，并且 GitLab Ultimate 可用：

  1. 在您的 GitLab 项目或组中，导航到 Analyze > Analytics dashboards
  2. 点击 Value Streams Dashboard
  3. 您将看到包括 Issues created、Issues closed、Lead time 和 Cycle time 在内的指标

Value Stream Analytics（需要设置 - Premium 和 Ultimate）

对于更详细的分析和自定义价值流（GitLab Premium 和 Ultimate 可用）：

  1. 在您的 GitLab 项目或组中，导航到 Analyze > Value stream analytics
  2. 点击 New value stream 创建自定义价值流
  3. 根据您的开发过程配置阶段和工作流
  4. 像前置时间和新问题计数这样的指标将自动生成并显示在您创建的阶段旁边
  5. 有关详细设置说明，请参考 GitLab Value Stream Analytics 文档

多项目考虑因素

如果您想使用一组自动化规则复制来自多个 Jira 项目的问题，请考虑使用基于时间戳的方法生成唯一的问题 ID，而不是项目前缀方法：

在您的自定义数据中替换 iid 值：

"iid": {{issue.created.replace("-","").replace("T","").replace(":","").replace(".","").replace("+","")}}

这将创建时间戳（格式：2025-02-15T09:45:32.7+0000）转换为数值。请注意，这种方法可能会导致问题 ID 非常长，并且如果两个问题在同一时间创建，存在小的冲突风险。

资源