GitLab for Jira Cloud 应用

通过 GitLab for Jira Cloud 应用，您可以连接 GitLab 和 Jira Cloud，实时同步开发信息。您可以在 Jira 开发面板 中查看这些信息。

您可以使用 GitLab for Jira Cloud 应用来链接顶级组或子组。无法直接链接项目或个人命名空间。

要在 GitLab.com 上设置 GitLab for Jira Cloud 应用，安装 GitLab for Jira Cloud 应用。

设置应用后，您可以使用 Atlassian 开发和维护的 项目工具链 来 将 GitLab 仓库链接到 Jira 项目。 项目工具链不会影响 GitLab 和 Jira Cloud 之间的开发信息同步方式。

对于 Jira Data Center 或 Jira Server，请使用 Atlassian 开发和维护的 Jira DVCS 连接器。

同步到 Jira 的 GitLab 数据

链接组后，当您 提及 Jira 问题 ID 时，以下 GitLab 数据将同步到该组中所有项目的 Jira：

• 现有项目数据（链接组之前）：
  • 最近 400 个合并请求
  • 最近 400 个分支以及每个分支的最后一次提交（GitLab 15.11 及更高版本）
• 新项目数据（链接组之后）：
  • 合并请求
    • 合并请求作者
  • 分支
  • 提交
    • 提交作者
  • 流水线
  • 部署
  • 功能标志

安装 GitLab for Jira Cloud 应用

先决条件：

• 您的网络必须允许 GitLab 和 Jira 之间的入站和出站连接。
• 您必须满足某些 Jira 用户要求。

安装 GitLab for Jira Cloud 应用：

1. 在 Jira 中，在顶部栏选择 应用 > 探索更多应用，然后搜索 GitLab for Jira Cloud。
2. 选择 GitLab for Jira Cloud，然后选择 立即获取。

或者，直接从 Atlassian Marketplace 获取应用。

现在您可以 配置 GitLab for Jira Cloud 应用。

有关概述，请参阅 从 Atlassian Marketplace 为 GitLab.com 安装 GitLab for Jira Cloud 应用。

配置 GitLab for Jira Cloud 应用

先决条件：

• 您必须至少拥有 GitLab 组的维护者角色。
• 您必须满足某些 Jira 用户要求。

您可以通过将 GitLab for Jira Cloud 应用链接到一个或多个 GitLab 组来同步数据从 GitLab 到 Jira。 配置 GitLab for Jira Cloud 应用：

1. 在 Jira 中，在顶部栏选择 应用 > 管理您的应用。

2. 展开 GitLab for Jira。根据您的安装方式，应用名称为：

   • 如果您 从 Atlassian Marketplace 安装应用，则为 GitLab for Jira (gitlab.com)。
   • 如果您 手动安装应用，则为 GitLab for Jira (<gitlab.example.com>)。

3. 选择 开始使用。

4. 可选。要将 GitLab Self-Managed 与 Jira 连接，选择 更改 GitLab 版本。

   1. 选择所有复选框，然后选择 下一步。
   2. 输入您的 GitLab 实例 URL，然后选择 保存。

5. 选择 登录 GitLab。

   企业用户 如果其组 禁用了密码身份验证， 必须先使用其组的单点登录 URL 登录 GitLab。

6. 选择 授权。现在会显示一个组列表。

7. 选择 链接组。

8. 要链接到组，选择 链接。

链接到 GitLab 组后：

• 数据会同步到该组中所有项目的 Jira。初始数据同步以每批 20 个项目的速度进行。 对于包含许多项目的组，某些项目的数据同步会延迟。
• GitLab for Jira Cloud 应用集成会自动为该组及其所有子组或项目启用。 该集成允许您 配置 Jira Service Management。

配置 Jira Service Management

先决条件：

• 必须已 安装 GitLab for Jira Cloud 应用。
• 必须在 GitLab for Jira Cloud 应用配置中 链接一个 GitLab 组。

您可以将 GitLab 连接到您的 IT 服务项目以跟踪您的部署。

配置在 GitLab 中进行，在 GitLab for Jira Cloud 应用集成中。在 链接 GitLab 组 后，该集成会为 GitLab 中的组、其子组和项目启用。

启用和禁用 GitLab for Jira Cloud 应用集成完全通过组链接自动进行，而不是通过 GitLab 集成表单或 API。

在 Jira Service Management 中：

1. 在您的服务项目中，转到 项目设置 > 变更管理。
2. 选择 连接流水线 > GitLab，然后在设置流程末尾复制 服务 ID。

在 GitLab 中：

1. 在左侧边栏，选择 搜索或转到 并找到您的项目。
2. 选择 设置 > 集成。
3. 选择 GitLab for Jira Cloud 应用。如果集成被禁用，请先 链接 GitLab 组， 这会为组、其子组和项目启用 GitLab for Jira Cloud 应用集成。
4. 在 服务 ID 字段中，输入您要映射到此项目的服务 ID。要使用多个服务 ID， 在每个服务 ID 之间添加逗号。

您可以映射最多 100 个服务。

有关 Jira 中部署跟踪的更多信息，请参阅 设置部署跟踪。

使用 GitLab 设置部署门控

您可以设置部署门控，将来自 GitLab 的变更请求发送到 Jira Service Management 进行审批。 通过部署门控，任何 GitLab 部署到您选择的环境都会自动发送到 Jira Service Management，并且只有在获得批准后才会部署。

创建服务账户令牌

要在 GitLab 中创建服务账户令牌，您必须首先创建个人访问令牌。 此令牌用于验证在 Jira Service Management 中管理 GitLab 部署所使用的服务账户令牌。

创建服务账户令牌：

1. 创建服务账户用户。
2. 使用您的个人访问令牌 将服务账户添加到组或项目。
3. 使用您的个人访问令牌 将服务账户添加到受保护环境。
4. 使用您的个人访问令牌 生成服务账户令牌。
5. 复制服务账户令牌值。

启用部署门控

启用部署门控：

• 在 GitLab 中：

  1. 在左侧边栏，选择 搜索或转到 并找到您的项目。
  2. 选择 设置 > 集成。
  3. 选择 GitLab for Jira Cloud 应用。
  4. 在 部署门控 下，选择 启用部署门控 复选框。
  5. 在 环境层级 文本框中，输入要启用部署门控的环境名称。 您可以输入多个以逗号分隔的环境名称（例如，production, staging, testing, development）。 仅使用小写字母。
  6. 选择 保存更改。

• 在 Jira Service Management 中：

  1. 设置部署门控。
  2. 在 服务账户令牌 文本框中，粘贴您从 GitLab 复制的服务账户令牌值。

将服务账户添加到受保护环境

要将服务账户添加到 GitLab 中的受保护环境：

1. 在左侧边栏，选择 搜索或转到 并找到您的项目。
2. 选择 设置 > CI/CD。
3. 展开 受保护环境 并选择 保护环境。
4. 从 选择环境 下拉列表中，选择要保护的环境（例如，staging）。
5. 从 允许部署 下拉列表中，选择谁可以部署到此环境（例如，开发者 + 维护者）。
6. 从 审批者 下拉列表中，选择您 创建的服务账户。
7. 选择 保护。

示例 API 请求

• 创建服务账户用户：

  curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "name=<name_of_your_choice>&username=<username_of_your_choice>"  "<https://gitlab.com/api/v4/groups/<group_id>/service_accounts"

• 使用您的个人访问令牌将服务账户添加到组或项目：

  curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
       --data "user_id=<service_account_id>&access_level=30" "https://gitlab.com/api/v4/groups/<group_id>/members"
  curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
       --data "user_id=<service_account_id>&access_level=30" "https://gitlab.com/api/v4/projects/<project_id>/members"

• 使用您的个人访问令牌生成服务账户令牌：

  curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"
  "https://gitlab.com/api/v4/groups/<group_id>/service_accounts/<service_account_id>/personal_access_tokens" --data "scopes[]=api,read_user,read_repository" --data "name=service_accounts_token"

更新 GitLab for Jira Cloud 应用

应用的更新大多是自动的。有关更多信息，请参阅 Atlassian 文档。

如果应用需要额外权限，您必须在 Jira 中手动批准更新。

安全注意事项

GitLab for Jira Cloud 应用连接 GitLab 和 Jira。数据必须在两个应用程序之间共享，并且必须双向授予访问权限。

GitLab 访问 Jira

当您 配置 GitLab for Jira Cloud 应用 时，GitLab 从 Jira 收到一个 共享密钥令牌。 该令牌授予 GitLab 对 Jira 项目的 READ、WRITE 和 DELETE 应用范围。 这些范围是更新 Jira 项目开发面板中信息所必需的。 该令牌不授予 GitLab 访问除安装该应用的 Jira 项目之外的任何其他 Atlassian 产品的权限。

该令牌使用 AES256-GCM 加密并存储在 GitLab 上。 当 GitLab for Jira Cloud 应用从您的 Jira 项目中卸载时，GitLab 会删除该令牌。

Jira 访问 GitLab

Jira 不会获得对 GitLab 的任何访问权限。

从 GitLab 发送到 Jira 的数据

有关发送到 Jira 的所有数据，请参阅 同步到 Jira 的 GitLab 数据。

有关发送到 Jira 的特定数据属性的更多信息，请参阅数据同步中涉及的 序列化器类。

从 Jira 发送到 GitLab 的数据

当 GitLab for Jira Cloud 应用安装或卸载时，GitLab 会从 Jira 接收一个 生命周期事件。 该事件包含一个 令牌 用于验证后续生命周期事件，并在 发送数据到 Jira 时进行身份验证。 来自 Jira 的生命周期事件请求会进行 验证。

对于使用来自 Atlassian Marketplace 的 GitLab for Jira Cloud 应用的 GitLab Self-Managed 实例，GitLab.com 处理生命周期事件并将其转发到 GitLab Self-Managed 实例。有关更多信息，请参阅 GitLab.com 对应用生命周期事件的处理。

Jira 存储的数据

发送到 Jira 的数据 由 Jira 存储 并显示在 Jira 开发面板 中。

当 GitLab for Jira Cloud 应用卸载时，Jira 会永久删除这些数据。 此过程是异步的，可能需要长达几个小时。

Atlassian Marketplace 中的隐私和安全详情

有关更多信息，请参阅 Atlassian Marketplace 列表的隐私和安全详情。

故障排除

在使用 GitLab for Jira Cloud 应用时，您可能会遇到以下问题。

有关管理员文档，请参阅 GitLab for Jira Cloud 应用管理。

错误：无法链接组

连接 GitLab for Jira Cloud 应用时，您可能会收到此错误：

无法链接组。请重试。

如果由于权限不足而无法从 Jira 获取用户信息，则会返回 403 Forbidden。

要解决此问题，请确保您满足某些 Jira 用户要求。

链接到 GitLab 组后 Jira Code 不工作

链接 GitLab for Jira Cloud 应用到 GitLab 组 后， Jira Code 可能无法工作。 要解决此问题，您必须同时配置 Bitbucket 和 Jira。

在 Bitbucket 中：

1. 登录您的 Atlassian 账户。
2. 创建并输入您工作区的名称。

在 Jira 中：

1. 在 项目 中，选择您的项目。
2. 选择 开发 > 代码。
3. 选择 连接 Bitbucket > 链接 Bitbucket Cloud 工作区。
4. 选择您在 Bitbucket 中创建的工作区。
5. 选择 授予访问权限。

您的仓库现在应该会出现在 Jira Code 中。