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

GitLab for Jira Cloud 应用管理

Tier: Free, Premium, Ultimate
Offering: GitLab Self-Managed

本页面包含 GitLab for Jira Cloud 应用的管理员文档。有关用户文档，请参阅 GitLab for Jira Cloud 应用。

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

要在您的 GitLab Self-Managed 实例上设置 GitLab for Jira Cloud 应用，请执行以下操作之一：

从 Atlassian Marketplace 安装 GitLab for Jira Cloud 应用（GitLab 15.7 及更高版本）。
手动安装 GitLab for Jira Cloud 应用。

概览信息请参阅：

如果您从 Atlassian Marketplace 安装 GitLab for Jira Cloud 应用，您可以使用由 Atlassian 开发和维护的项目工具链来将 GitLab 仓库链接到 Jira 项目。项目工具链不会影响 GitLab 和 Jira Cloud 之间的开发信息同步方式。

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

设置 OAuth 认证

无论您想从 Atlassian Marketplace还是手动安装 GitLab for Jira Cloud 应用，都必须创建一个 OAuth 应用程序。

要在您的 GitLab Self-Managed 实例上创建 OAuth 应用程序：

在左侧边栏底部，选择 管理员。
选择 应用程序。
选择 新建应用程序。
在 重定向 URI 中：
- 如果您要从 Atlassian Marketplace 列表安装应用，请输入 https://gitlab.com/-/jira_connect/oauth_callbacks。
- 如果您要手动安装应用，请输入 <instance_url>/-/jira_connect/oauth_callbacks 并将 <instance_url> 替换为您的实例 URL。
清除可信和机密复选框。

您必须清除这些复选框以避免错误。
在范围中，仅选择 api 复选框。
选择 保存应用程序。
复制 应用程序 ID 值。
在左侧边栏中，选择 设置 > 通用。
展开 GitLab for Jira 应用。
将 应用程序 ID 值粘贴到 Jira Connect 应用程序 ID 中。
选择 保存更改。

Jira 用户要求

在您的 Atlassian 组织中，您必须确保用于设置 GitLab for Jira Cloud 应用的 Jira 用户是以下任一组的成员：

组织管理员（org-admins）组。较新的 Atlassian 组织使用集中式用户管理，其中包含 org-admins 组。现有的 Atlassian 组织正在迁移到集中式用户管理。如果可用，您应该使用 org-admins 组来指示哪些 Jira 用户可以管理 GitLab for Jira Cloud 应用。或者您也可以使用 site-admins 组。
站点管理员（site-admins）组。site-admins 组在原始用户管理下使用。

如有必要：

创建您偏好的组。
编辑该组，将您的 Jira 用户添加为成员。
如果您在 Jira 中自定义了全局权限，您可能还需要向 Jira 用户授予浏览用户和组权限。

从 Atlassian Marketplace 安装 GitLab for Jira Cloud 应用

您可以将 Atlassian Marketplace 中的官方 GitLab for Jira Cloud 应用与您的 GitLab Self-Managed 实例一起使用。

使用此方法：

GitLab.com 处理从 Jira Cloud 发送的安装和卸载生命周期事件并将它们转发到您的 GitLab 实例。来自您的 GitLab Self-Managed 实例的所有数据仍然直接发送到 Jira Cloud。
GitLab.com 通过将分支创建链接重定向到您的实例来处理分支创建链接。
在 17.2 之前的任何 GitLab 版本中，无法在 GitLab Self-Managed 实例上从 Jira Cloud 创建分支。更多信息，请参阅 issue 391432。

或者，如果出现以下情况，您可能想要手动安装 GitLab for Jira Cloud 应用：

您的实例不满足先决条件。
您不想使用官方的 Atlassian Marketplace 列表。
您不希望 GitLab.com 处理应用生命周期事件或知道您的实例已安装该应用。
您不希望 GitLab.com 将分支创建链接重定向到您的实例。

先决条件

实例必须可公开访问。
实例必须在 GitLab 15.7 或更高版本上。
您必须设置 OAuth 认证。
您的 GitLab 实例必须使用 HTTPS，并且您的 GitLab 证书必须是公开信任的或包含完整的证书链。
您的网络配置必须允许：
- 从您的 GitLab Self-Managed 实例到 Jira Cloud 的出站连接（Atlassian IP 地址）
- 您的 GitLab Self-Managed 实例和 GitLab.com 之间的入站和出站连接（GitLab.com IP 地址）
- 对于防火墙后的实例：
  1. 在您的 GitLab Self-Managed 实例前面设置面向互联网的反向代理。
  2. 配置反向代理以允许来自 GitLab.com 的入站连接（GitLab.com IP 地址）
  3. 确保您的 GitLab Self-Managed 实例仍然可以建立前面描述的出站连接。
安装和配置应用的 Jira 用户必须满足特定的要求。

为 Atlassian Marketplace 安装设置您的实例

先决条件

要在 GitLab 15.7 及更高版本中为 Atlassian Marketplace 安装设置您的 GitLab Self-Managed 实例：

在左侧边栏底部，选择 管理员。
选择 设置 > 通用。
展开 GitLab for Jira 应用。
在 Jira Connect 代理 URL 中，输入 https://gitlab.com 以从 Atlassian Marketplace 安装应用。
选择 保存更改。

链接您的实例

先决条件

要将您的 GitLab Self-Managed 实例链接到 GitLab for Jira Cloud 应用：

检查 Jira Cloud 是否已链接

您可以使用 Rails 控制台来检查 Jira Cloud 是否已链接到：

特定组：

JiraConnectSubscription.where(namespace: Namespace.by_path('group/subgroup'))

特定项目：

Project.find_by_full_path('path/to/project').jira_subscription_exists?

任何组：

installation = JiraConnectInstallation.find_by_base_url("https://customer_name.atlassian.net")
installation.subscriptions

手动安装 GitLab for Jira Cloud 应用

在 GitLab 17.5 及更早版本中，手动安装 GitLab for Jira Cloud 应用时可能会遇到问题。更多信息，请参阅 issue 505372。此问题不影响从 Atlassian Marketplace 的安装。

如果您不想使用官方的 Atlassian Marketplace 列表，请手动安装 GitLab for Jira Cloud 应用。

您必须从单个位置安装每个 Jira Cloud 应用。Jira 从您提供的位置获取清单文件。清单文件向系统描述了该应用。

要支持您的 GitLab Self-Managed 实例与 Jira Cloud 的集成，请执行以下操作之一：

先决条件

实例必须可公开访问。
您必须设置 OAuth 认证。
您的网络配置必须允许：
- 您的 GitLab Self-Managed 实例和 Jira Cloud 之间的入站和出站连接（Atlassian IP 地址）。
- 对于防火墙后的实例：
  1. 在您的 GitLab Self-Managed 实例前面设置面向互联网的反向代理。
  2. 配置反向代理以允许来自 Jira Cloud 的入站连接（Atlassian IP 地址）。
  3. 确保您的 GitLab Self-Managed 实例仍然可以建立前面描述的出站连接。
安装和配置应用的 Jira 用户必须满足特定的要求。

为手动安装设置您的实例

先决条件

要在 GitLab 15.7 及更高版本中为手动安装设置您的 GitLab Self-Managed 实例：

在左侧边栏底部，选择 管理员。
选择 设置 > 通用。
展开 GitLab for Jira 应用。
将 Jira Connect 代理 URL 留空以手动安装应用。
选择 保存更改。

在开发模式下安装应用

先决条件

要配置您的 Jira 实例以便您可以从 Atlassian Marketplace 外部安装应用：

以管理员身份登录您的 Jira 实例。
在您的 Jira 实例上启用开发模式。
以管理员身份登录 GitLab。
从您的 Jira 实例安装 GitLab：
1. 在您的 Jira 实例上，转到 应用 > 管理应用 并选择 上传应用。
2. 在 应用描述符 URL 中，根据您的实例配置提供清单文件的完整 URL。
  
  默认情况下，您的清单文件位于 /-/jira_connect/app_descriptor.json。例如，如果您的实例域名是 app.pet-store.cloud，您的清单文件位于 https://app.pet-store.cloud/-/jira_connect/app_descriptor.json。
3. 选择上传。
4. 选择 开始使用 以配置集成。
在您的 Jira 实例上禁用开发模式。

在 应用 > 管理应用 中，GitLab for Jira Cloud 现在可见。您也可以选择 开始使用 来配置 GitLab for Jira Cloud 应用。

如果 GitLab 升级更改了应用描述符，您必须重新安装该应用。

创建 Atlassian Marketplace 列表

先决条件

如果您不想使用开发模式，可以创建自己的 Atlassian Marketplace 列表。这样，您可以从 Atlassian Marketplace 安装 GitLab for Jira Cloud 应用。

要创建 Atlassian Marketplace 列表：

注册为 Atlassian Marketplace 供应商。
使用应用描述符 URL 列出您的应用程序。
- 您的清单文件位于：https://your.domain/your-path/-/jira_connect/app_descriptor.json
- 您应该将您的应用程序列为 private，因为公共应用程序可以被任何用户查看和安装。
为您的应用程序生成测试许可证令牌。

与 GitLab.com Marketplace 列表一样，此方法使用自动更新。

有关创建 Atlassian Marketplace 列表的更多信息，请参阅 Atlassian 文档。

配置您的 GitLab 实例以充当代理

GitLab 实例可以通过 GitLab for Jira Cloud 应用为其他 GitLab 实例充当代理。如果您管理多个 GitLab 实例但只想手动安装一次应用，您可能想要使用代理。

要配置您的 GitLab 实例以充当代理：

在左侧边栏底部，选择 管理员。
选择 设置 > 通用。
展开 GitLab for Jira 应用。
选择 启用公钥存储。
选择 保存更改。
手动安装 GitLab for Jira Cloud 应用。

使用代理的其他 GitLab 实例必须配置以下设置以指向代理实例：

安全注意事项

以下安全注意事项特定于应用管理。有关与应用使用相关的注意事项，请参阅安全注意事项。

GitLab.com 处理应用生命周期事件

当您从 Atlassian Marketplace 安装 GitLab for Jira Cloud 应用时， GitLab.com 会从 Jira 接收生命周期事件。这些事件仅限于在您的 Jira 项目中安装或卸载应用时。

在安装事件中，GitLab.com 从 Jira 接收一个秘密令牌。 GitLab.com 使用 AES256-GCM 加密存储此令牌，以便稍后验证来自 Jira 的传入生命周期事件。

然后 GitLab.com 将令牌转发到您的 GitLab Self-Managed 实例，以便您的实例可以使用相同的令牌对其向 Jira 的请求进行身份验证。您的 GitLab Self-Managed 实例也会收到 GitLab for Jira Cloud 应用已安装或卸载的通知。

当数据从您的 GitLab Self-Managed 实例发送到 Jira 开发面板时，它是从您的 GitLab Self-Managed 实例直接发送到 Jira，而不是发送到 GitLab.com。 GitLab.com 不使用该令牌访问您的 Jira 项目中的数据。您的 GitLab Self-Managed 实例使用该令牌来访问数据。

有关 GitLab.com 接收的生命周期事件和负载的更多信息，请参阅 Atlassian 文档。

sequenceDiagram
accTitle: 从 Atlassian Marketplace 安装的 GitLab for Jira Cloud 应用的数据流
accDescr: 当 GitLab for Jira Cloud 应用从 Atlassian Marketplace 安装时，GitLab.com 如何处理生命周期事件

    participant Jira
    participant Your instance
    participant GitLab.com
    Jira->>+GitLab.com: 应用安装/卸载事件
    GitLab.com->>-Your instance: 应用安装/卸载事件
    Your instance->>Jira: 您的开发数据

GitLab.com 处理分支创建

当您从 Atlassian Marketplace 安装了 GitLab for Jira Cloud 应用时，从开发面板创建分支的链接最初会将用户发送到 GitLab.com。

Jira 向 GitLab.com 发送一个 JWT 令牌。GitLab.com 通过验证令牌来处理请求，然后将请求重定向到您的 GitLab 实例。

通过 OAuth 访问 GitLab

GitLab 不会与 Jira 共享访问令牌。但是，用户必须通过 OAuth 进行身份验证才能配置应用。

访问令牌通过 PKCE OAuth 流程检索，并仅存储在客户端。初始化 OAuth 流程的应用前端是一个 JavaScript 应用程序，通过 Jira 上的 iframe 从 GitLab 加载。

OAuth 应用程序必须具有 api 范围，该范围授予对 API 的完整读写访问权限。此访问权限包括所有组和项目、容器注册表和包注册表。但是，GitLab for Jira Cloud 应用仅使用此访问权限来：

显示要链接的组。
链接组。

通过 OAuth 的访问仅在用户配置 GitLab for Jira Cloud 应用期间需要。更多信息，请参阅访问令牌过期。

使用反向代理

如果可能，您应避免在 GitLab Self-Managed 实例前使用反向代理。相反，考虑使用公共 IP 地址并通过防火墙保护域。

如果您必须为无法直接从互联网访问的 GitLab Self-Managed 实例上的 GitLab for Jira Cloud 应用使用反向代理，请记住以下几点：

当您从 Atlassian Marketplace 安装 GitLab for Jira Cloud 应用时，使用可以同时访问内部 GitLab FQDN 和反向代理 FQDN 的客户端。
当您手动安装 GitLab for Jira Cloud 应用时，使用反向代理 FQDN 作为 重定向 URI 来设置 OAuth 认证。
反向代理必须满足您的安装方法的先决条件：
- 连接 GitLab for Jira Cloud 应用的先决条件。
- 手动安装 GitLab for Jira Cloud 应用的先决条件。
Jira 开发面板可能会链接到内部 GitLab FQDN 或 GitLab.com，而不是反向代理 FQDN。更多信息，请参阅 issue 434085。
为了在公共互联网上保护反向代理，仅允许来自 Atlassian IP 地址的入站流量。
如果您在代理中使用重写或子过滤器，请确保代理不重写或替换 gitlab-jira-connect-${host} 应用密钥。否则，您可能会得到链接组失败错误。
当您在 Jira 开发面板中选择创建分支时，您会被重定向到反向代理 FQDN，而不是内部 GitLab FQDN。

外部 NGINX

此服务器块是如何为与 Jira Cloud 一起使用的 GitLab 配置反向代理的示例：

server {
  listen *:80;
  server_name gitlab.mycompany.com;
  server_tokens off;
  location /.well-known/acme-challenge/ {
    root /var/www/;
  }
  location / {
    return 301 https://gitlab.mycompany.com:443$request_uri;
  }
}
server {
  listen *:443 ssl;
  server_tokens off;
  server_name gitlab.mycompany.com;
  ssl_certificate /etc/letsencrypt/live/gitlab.mycompany.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/gitlab.mycompany.com/privkey.pem;
  ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384';
  ssl_protocols  TLSv1.2 TLSv1.3;
  ssl_prefer_server_ciphers off;
  ssl_session_cache  shared:SSL:10m;
  ssl_session_tickets off;
  ssl_session_timeout  1d;
  access_log "/var/log/nginx/proxy_access.log";
  error_log "/var/log/nginx/proxy_error.log";
  location / {
    proxy_pass https://gitlab.internal;
    proxy_hide_header upgrade;
    proxy_set_header Host             gitlab.mycompany.com:443;
    proxy_set_header X-Real-IP        $remote_addr;
    proxy_set_header X-Forwarded-For  $proxy_add_x_forwarded_for;
  }
}

在此示例中：

将 gitlab.mycompany.com 替换为反向代理 FQDN，将 gitlab.internal 替换为内部 GitLab FQDN。
将 ssl_certificate 和 ssl_certificate_key 设置为有效证书（示例使用 Certbot）。
将 Host 代理头设置为反向代理 FQDN，以确保 GitLab 和 Jira Cloud 可以成功连接。

您必须仅使用反向代理 FQDN 来连接 Jira Cloud 到 GitLab。您必须继续从内部 GitLab FQDN 访问 GitLab。如果您从反向代理 FQDN 访问 GitLab，GitLab 可能无法按预期工作。更多信息，请参阅 issue 21319。

设置额外的 JWT 受众

当 GitLab 从 Jira 接收 JWT 令牌时， GitLab 通过检查 JWT 受众来验证令牌。默认情况下，受众从您的内部 GitLab FQDN 派生。

在某些反向代理配置中，您可能需要将反向代理 FQDN 设置为额外的 JWT 受众。要设置额外的 JWT 受众：

在左侧边栏底部，选择 管理员。
选择 设置 > 通用。
展开 GitLab for Jira 应用。
在 Jira Connect 额外受众 URL 中，输入额外的受众（例如，https://gitlab.mycompany.com）。
选择 保存更改。