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

GitLab for Jira Cloud 应用开发

开发者有几种方式来为 GitLab for Jira Cloud 应用设置开发环境：

  1. 一个完整的 带 Jira 的环境。当您需要测试与 Jira 的交互时使用此选项。
  2. 一个完整的 带 Jira Connect proxy 的环境。当您需要测试多个 GitLab 实例通过 Jira Connect proxy 连接到 Jira，或者测试对 Jira Connect proxy 本身的更改时使用此选项。
  3. 一个本地 不带 Jira 的环境。如果您不需要 Jira，例如在测试 GitLab 前端时，可以使用这个更快的设置。

设置带 Jira 的环境

安装应用需要以下条件：

  • 一个 Jira Cloud 实例。Atlassian 提供了 用于开发和测试的免费实例。

  • 一个可通过互联网访问的 GitLab 实例。为了使应用正常工作，Jira Cloud 应该能够通过互联网连接到 GitLab 实例。为此，我们建议使用 Gitpod 或类似的云开发环境。有关使用 Gitpod 与 GDK 的更多信息，请参见：

    GitLab 团队成员 必须不要 使用 Serveo 或 ngrok 等隧道工具。这些是安全风险，不能在 GitLab 开发人员笔记本电脑上运行。

    Jira 要求所有到应用主机的连接都必须使用 SSL。如果您设置自己的环境，请记得启用 SSL 和适当的证书。

设置 GitPod

如果您使用 Gitpod 您必须 将端口 3000 设为公开。

在 Jira 中安装应用

要在 Jira 中安装应用：

  1. 启用 Jira 开发模式以安装来自 Atlassian Marketplace 的应用：

    1. 在 Jira 中，转到 Jira 设置 > 应用 > 管理应用。
    2. 滚动到 管理应用 页面底部并选择 设置。
    3. 选择 启用开发模式 并选择 应用。

  2. 安装应用：

    1. 在 Jira 中，转到 Jira 设置 > 应用 > 管理应用。

    2. 选择 上传应用。

    3. 在 从此 URL 字段中，提供应用描述符的链接。主机和端口必须指向您的 GitLab 实例。

      例如：

      https://xxxx.gitpod.io/-/jira_connect/app_descriptor.json

    4. 选择 上传。

    如果安装成功，您应该在 管理应用 下看到 GitLab for Jira Cloud 应用。 您还可以选择 入门 来打开从您的 GitLab 实例渲染的配置页面。

    请注意，对应用描述符的任何更改都需要您先卸载然后重新安装应用。

  3. 如果 已安装并准备就绪！ 对话框打开，要求您 开始，请先不要开始，而是选择 关闭。

  4. 您现在必须 设置 OAuth 认证流程。

设置 GitLab OAuth 认证流程

GitLab for Jira 用户使用 GitLab OAuth 认证 GitLab。

在执行这些步骤之前，请确保您已经 在 Jira 中安装了应用，否则 Jira 中的应用安装会失败。

以下步骤描述了设置环境来测试 GitLab OAuth 流程：

  1. 启动一个 Gitpod 会话。
  2. 在您的 GitLab 实例上，转到 Admin > Applications。
  3. 创建一个具有以下设置的新应用：
    • 名称：GitLab for Jira
    • 重定向 URI：YOUR_GITPOD_INSTANCE/-/jira_connect/oauth_callbacks
    • 受信任：否
    • 机密：否
    • 范围：api
  4. 复制 Application ID 值。
  5. 转到 Admin > Settings > General。
  6. 展开 GitLab for Jira App。
  7. 将 Application ID 值粘贴到 Jira Connect Application ID 中。
  8. 在 Jira Connect Proxy URL 中，输入 YOUR_GITPOD_INSTANCE（例如，https://xxxx.gitpod.io）。
  9. 启用公钥存储：保持未选中状态。
  10. 选择 保存更改。

在 Jira 中设置应用

在执行这些步骤之前，请确保您已经 先设置了 OAuth，否则这些步骤会失败。

  1. 在 Jira 中，转到 Jira 设置 > 应用 > 管理应用。
  2. 滚动到 用户安装的应用，找到您的 GitLab for Jira Cloud 应用并展开它。
  3. 选择 入门。

您应该能够使用您的 GitLab 实例进行身份验证并开始链接群组。

故障排除

应用安装失败

如果应用安装失败，您可能需要从数据库中删除 jira_connect_installations。

  1. 打开 数据库控制台。
  2. 运行 TRUNCATE TABLE jira_connect_installations CASCADE;。

无权访问文件

如果您使用 Gitpod 并收到关于 Jira 无法访问描述符文件的错误，您需要 将 GitPod 端口设为公开。

设置 Jira Connect Proxy

当 GitLab Self-Managed 实例 从 Atlassian Marketplace 安装 GitLab for Jira 应用 时，该实例必须使用 GitLab.com 作为 Jira Connect proxy。如果您需要开发或测试诸如 Jira 生命周期事件处理 和 分支创建 之类的功能，您可以模拟此设置。

要设置开发用的 Jira Connect Proxy：

  • 一个 Jira Cloud 实例。Atlassian 提供了 用于开发和测试的免费实例。
  • 两个可通过互联网访问的 GitLab 实例。

    • 一个用作 Jira Connect proxy（模拟 GitLab.com）

    • 一个用作将通过 Jira Connect proxy 连接到 Jira 的 GitLab 实例

    • 为了使应用正常工作，Jira Cloud 应该能够通过互联网连接到 Jira Connect proxy 实例。为此，我们建议使用 Gitpod 或类似的云开发环境。有关使用 Gitpod 与 GDK 的更多信息，请参见：

      GitLab 团队成员 必须不要 使用 Serveo 或 ngrok 等隧道工具。这些是安全风险，不能在 GitLab 开发人员笔记本电脑上运行。

      Jira 要求所有到应用主机的连接都必须使用 SSL。如果您设置自己的环境，请记得启用 SSL 和适当的证书。

设置 GitPod

如果您使用 Gitpod 您必须 将端口 3000 设为公开。

设置 Jira Connect proxy 实例

  1. 对于 Jira Connect proxy 实例，按照 GDK with Gitpod 说明启动一个新的 Gitpod 工作区。

  2. 通过遵循 设置 GitLab OAuth 认证流程 部分在 Jira Connect proxy 上设置 OAuth 认证。

  3. 将 Jira Connect proxy 配置为代理。

在 Jira 中安装 GitLab for Jira Cloud 应用

遵循 在 Jira 中安装应用 部分，但使用您的 Jira Connect proxy 实例的 URL 作为应用描述符：

https://JIRA_CONNECT_PROXY_INSTANCE/-/jira_connect/app_descriptor.json

如果 已安装并准备就绪！ 对话框打开，选择 关闭（不要选择 入门）。

设置第二个 GitLab 实例

  1. 使用 Gitpod 设置第二个 GitLab 实例，遵循与代理实例相同的 GDK with Gitpod 说明

  2. 按照与 设置 GitLab OAuth 认证流程 相同的步骤在此实例上设置 OAuth 认证，但有一个关键区别：

    • 设置 重定向 URI 时，使用您的 Jira Connect proxy 实例的 URL，而不是此辅助实例：

      https://JIRA_CONNECT_PROXY_INSTANCE/-/jira_connect/oauth_callbacks

  3. 配置此 GitLab 实例以使用代理：

    1. 转到 Admin > Settings > General
    2. 展开 GitLab for Jira App
    3. 将 Application ID 值粘贴到 Jira Connect Application ID
    4. 在 Jira Connect Proxy URL 中，输入 JIRA_CONNECT_PROXY_INSTANCE（例如，https://xxxx.gitpod.io）
    5. 选择 保存更改

在 Jira 中完成设置

  1. 在 Jira 中，转到 Jira 设置 > 应用 > 管理应用。
  2. 滚动到 用户安装的应用，找到您的 GitLab for Jira Cloud 应用并展开它。
  3. 选择 入门。
  4. 要将应用链接到第二个 GitLab 实例，选择 更改 GitLab 版本。
  5. 选择所有复选框，然后选择下一步。
  6. 在 GitLab 实例 URL 中，输入 GITLAB_INSTANCE（例如，https://xxxx.gitpod.io），然后选择保存。
  7. 选择 登录 GitLab。
  8. 选择 授权。现在会显示一个群组列表。
  9. 选择 链接群组。
  10. 要链接到群组，选择 链接。

不带 Jira 的设置

如果您不需要使用 Jira 进行测试，您可以使用 Jira connect 测试工具 和您的本地 GDK。

  1. 克隆 Jira-connect-test-tool git clone [email protected]:gitlab-org/manage/integrations/jira-connect-test-tool.git。

  2. 启动应用 bundle exec rackup。（该应用需要您的 GDK GitLab 在 http://127.0.0.1:3000 上可用。）。

  3. 打开 config/gitlab.yml 并取消注释 jira_connect 配置。

  4. 如果在除 localhost 之外的域上运行 GDK，您必须将该域添加到 additional_iframe_ancestors。例如：

    additional_iframe_ancestors: ['localhost:*', '127.0.0.1:*', 'gdk.test:*']

  5. 重启 GDK。

  6. 转到 http://127.0.0.1:3000/-/user_settings/personal_access_tokens。

  7. 创建一个具有 api 范围的新令牌并复制该令牌。

  8. 转到 http://localhost:9292。

  9. 粘贴令牌并选择 安装 GitLab.com Jira Cloud 应用。