在工具链中将 GitHub 配置为源代码仓库

Continuous Delivery 将于 2027 年 2 月 12 日在以下地区停止服务:au-syd、ca-tor、us-east。 Code Risk Analyzer 也将于该日期在所有地区停止提供服务。 如果某个区域未实际使用这些功能,该区域内的相关功能可能会提前停用,并停止接受新实例。 了解更多

在您的 IBM Cloud 工具链中配置 GitHub,以管理源代码、通过拉取请求进行协作,并在代码发生变更时触发管道运行。

GitHub Enterprise 是 Git 存储库基于 Web 的内部部署托管服务。

GitHub Issues 是一种跟踪工具,可将您的全部工作和计划保留在一个地方。 它与您的开发存储库相集成,以便您可将关注点放在重要的任务上。

您可以将 GitHub 配置为工具链中的工具集成,以便您可以管理 GitHub.com 上或您公司 GitHub Enterprise 实例中新存储库或现有存储库中的源代码。 通过 Wiki、问题跟踪和拉取请求,可参与社交编码。

如果您在创建工具链时配置此工具集成,请遵循以下步骤:

  1. 如果要将源代码存储在 GitHub 存储库中,请在“可配置的集成”部分中,单击 GitHub。 IBM Cloud GitHub 如果您正在 IBM Cloud Public 上配置此工具集成,则必须通过选择 OAuth、个人访问令牌或 GitHub 应用。

    • 如果选择 OAuth,请单击“授权”进入 GitHub 网站。 如果您没有活动的 GitHub 会话,那么系统会提示您登录。 单击授权应用程序,以允许 IBM Cloud 访问 GitHub 帐户。 如果您有活动的 GitHub 会话,但最近未输入过密码,那么系统可能会提示您输入 GitHub 密码以进行确认。

    • 如果选择“个人访问令牌”,那么必须输入要用于向 GitHub 授权的个人访问令牌,以克隆存储库并代表您执行其他操作。 如果您没有个人访问令牌,那么可以遵循 GitHub Web 站点上的文档来创建个人访问令牌。 确保您的个人访问令牌具有 repo,delete_repo,read:user 和 workflow 权限。

    • 如果您选择“GitHub”应用,IBM Cloud 将使用“GitHub”应用的安装信息,代表您向 GitHub 进行身份验证,而不是使用 OAuth 令牌。 GitHub 应用程序提供了更精细的权限控制,且不依赖于单个用户的凭据。 选择以下某种方法:

      • 托管型 — 使用 IBM 提供的 GitHub 应用程序,该应用程序已针对您的 GitHub 服务器进行了预配置。 点击“授权”,系统将重定向至 GitHub,,您可在该页面批准该应用访问您的账户。

      • 自定义 — 请自带 GitHub 应用。 输入 App ID 以及您已在仓库中注册并安装的 GitHub 应用的私钥 (格式为 PEM )。 必须将该应用安装在您希望与该集成配合使用的任何仓库上。 有关创建 GitHub 应用的更多信息,请参阅 GitHub 文档。

  2. 如果您正在自己的 GitHub Enterprise 服务器上使用代码仓库,请在可配置集成部分中点击自定义服务器。

    a. 为您的 GitHub 自定义服务器输入标题,URL 指定服务器的根目录,并输入您的个人访问令牌。

    b. 如果您没有个人访问令牌,那么可以遵循 GitHub Web 站点上的文档来创建个人访问令牌。

    c. 如果您的GitHub服务器被空中屏蔽或无法在公共互联网上访问,您可以连接并集成一个Delivery Pipeline私有 Worker,在自己的Kubernetes基础架构上运行,以访问内部或企业内部资源。 有关 Delivery Pipeline 私人工作者的更多信息,请参阅 使用 Delivery Pipeline 私人工作者。

    d. 如果您的 GitHub Enterprise 服务器已注册了 GitHub 应用,您还可以选择 “GitHub”应用身份验证方式,并提供您的 App ID 和私钥,或者使用已为您的服务器预配置的托管应用。

  3. 复查 GitHub 存储库的缺省目标存储库位置。 那些存储库是从样本存储库克隆而来的。 如果需要,请更改目标存储库的名称。

如果您有工具链且要向其添加此工具集成,请执行以下步骤:

  1. 在控制 IBM Cloud 台中,点击菜单图标(汉堡图标 )> 平台自动化 > 工具链。 在工具链页面上,单击某个工具链以打开其概述页面。

  2. 点击添加工具。

  3. 在“工具集成”部分中,单击 GitHub。

  4. 单击要使用的 GitHub 服务器。

  5. 如果您有 GitHub 或 GitHub Enterprise 存储库并且想要使用该存储库,那么对于存储库类型,请单击现有并输入 URL。

  6. 如果要使用新的 GitHub 或 GitHub Enterprise 存储库,请输入存储库的名称,输入您要克隆或派生的存储库的 URL,然后选择存储库类型:

    a. 要创建空的存储库,请单击新建。

    b. 要创建 GitHub 或 GitHub Enterprise 存储库的副本,请单击克隆。

    c. 要派生 GitHub 或 GitHub Enterprise 存储库以便您可以通过拉出请求来提供更改,请单击派生。

  7. 如果您是具有升级帐户的 GitHub.com 用户,或者选择了 GitHub Enterprise 服务器,并且希望在该服务器上创建新的专用存储库,请选中使此存储库成为专用复选框。

  8. 如果要使用 GitHub 的 Issues 进行问题跟踪,请选中启用 GitHub Issues 复选框。

  9. 如果要通过在提交上创建标记和注释以及在提交所引用的问题上创建标签和注释来跟踪代码更改的部署,请选中跟踪代码更改的部署复选框。

  10. 单击创建集成。

  11. 在工具链的“概述”页面的 存储库 卡上,单击要使用的 GitHub 或 GitHub Enterprise 存储库。 根据您选择的存储库,将打开 GitHub Web 站点或您公司的 GitHub Enterprise 存储库,您可在其中查看存储库的内容。

  12. 如果您已启用 GitHub Issues,请单击 GitHub Issues,以将其打开。 您可以对整个工具链使用此 GitHub Issues 的实例,即使工具链包含多个 GitHub 或 GitHub Enterprise 存储库也是如此。

    如果您对要链接到的存储库没有管理员特权,那么您的集成将受到限制,因为您无法使用 Webhook。 将提交推送到存储库时,需要 Webhook 才能自动运行管道。 没有 Webhook,您必须手动启动管道。

使用 API 配置 GitHub

工具 GitHub 集成支持以下配置参数,您可在 创建、读取和 更新工具集成时 通过工具链 HTTP API 和 SDK 使用这些参数。

必须在请求主体中使用 githubconsolidated 值指定 tool_type_id 属性。

GitHub工具集成参数
参数 用途 类型 Terraform 自变量 描述
API根路径 可选,可更新 字符串 API根路径 API URL 根目录的 服务器 GitHub。
API令牌 可选,可更新 密码 API令牌 个人访问令牌 (PAT)。 仅当 auth_type 设置为 pat 时,才需要此参数,否则将忽略此参数。
auth_type 可选,可更新 字符串 auth_type 设置访问 Git 提供商时要使用的身份验证方法。 有效值为 oauth、pat 和 github_app。 当指定 github_app 时,身份验证将使用 GitHub App 安装令牌,而不是用户 OAuth 令牌或 PAT。
自动初始化 可选、不可变、Default: false 布尔值 自动初始化 将此值设置为 true 以使用自述文件初始化此存储库。 仅当您创建存储库时,才会使用此参数。
盲连接 可选,可更新,Default: false 布尔值 盲连接 将此值设置为 true 表示服务器在公共因特网上不可寻址。IBM Cloud 无法验证您提供的连接详细信息。 将禁用需要对 Git 服务器进行 API 访问的某些功能。 Delivery pipeline 将仅使用对 Git 服务器具有网络访问权的专用工作程序。
缺省分支 可选,可更新 字符串 缺省分支 Git 存储库的缺省分支。
enable_traceability 可选,可更新,Default: false 布尔值 enable_traceability 将此值设置为,通过在提交、拉取请求和相关问题上创建标签、标记和注释,true 来跟踪代码更改的部署情况。
Git ID 可选,不可更改 字符串 Git ID 对于 github.com,请将此值设置为 github,或者设置为定制 GitHub Enterprise 服务器的 GUID。
github_app_auth_method 可选,可更新 字符串 github_app_auth_method 当 auth_type 为 github_app 时,应使用 GitHub 应用的身份验证方法。 将该选项设置为 managed 以使用 IBM 提供的 GitHub 应用(默认),或设置为 custom,通过 github_app_credential_app_id 和 github_app_credential_private_key 提供您自己的 GitHub 应用凭据。
github_app_credential_app_id 可选,可更新 字符串 github_app_credential_app_id GitHub App ID,用于开发自定义的 GitHub 应用程序。 当 github_app_auth_method 为 custom 时,此项为必填项。
github_app_credential_private_key 可选,可更新 密码 github_app_credential_private_key 自定义 GitHub 应用的RSA私钥( PEM 格式)。 当 github_app_auth_method 为 custom 时,此项为必填项。 密钥以加密形式存储。
has_issues 可选,可更新,Default: true 布尔值 工具链问题启用 将此值设置为 true 以在 GitHub 存储库上启用问题,并向工具链添加“问题”工具卡。 将值设置为 false 以从工具链中除去工具集成卡。 此设置不会影响是否在 GitHub 存储库本身上启用了问题。
集成所有者 可选,可更新 字符串 集成所有者 选择执行 Git 操作的用户。
owner_id 可选,不可更改 字符串 owner_id 拥有存储库的 GitHub 用户或组织。 当您创建存储库或克隆或派生存储库时,此参数是必需的。 链接到现有存储库时,将计算此值。
私有仓库 可选、不可变、Default: false 布尔值 私有仓库 将此值设置为 true 以在创建存储库或克隆或派生存储库时使该存储库成为专用存储库。 链接到现有存储库时,不会使用此参数。
repo_id 可选,不可更改 字符串 repo_id GitHub 存储库的标识。
repo_name 可选,不可更改 字符串 repo_name 要创建的 GitHub 仓库名称。 当您创建存储库或克隆或派生存储库时,此参数是必需的。 链接到现有存储库时,将计算此值。
repo_url 可选,不可更改 字符串 repo_url 此工具集成的回购 URLGitHub 协议。 链接到现有存储库时,此参数是必需的。 此值在您创建存储库时计算,或者克隆或派生存储库时计算。
根 URL 可选,可更新 字符串 根 URL 服务 URL 器的根目录。例如:https://github.example.com
源代码仓库网址 可选,不可更改 字符串 源代码仓库网址 您正在分叉或克隆的仓库的 URL 仓库名称。 当您派生或克隆存储库时,此参数是必需的。 创建存储库或链接到现有存储库时,不会使用此参数。
标题 可选,可更新 字符串 标题 服务器的标题。例如,My GitHub Enterprise Server
令牌网址 可选,可更新 字符串 令牌网址 用于向 GitHub 服务器进行身份验证的 URL 令牌。
类型 必需,不可更改 字符串 类型 要执行的用于初始化新工具集成的操作。 使用 new 创建 Git 存储库,使用 clone 将现有存储库克隆到新的 Git 存储库中,使用 fork 派生现有 Git 存储库,或者使用 link 链接到现有 Git 存储库。

使用 GitHub App 身份验证

GitHub 应用身份验证是 OAuth 和个人访问令牌(PAT)方法的替代方案。 GitHub 应用程序以应用程序身份进行身份验证,而非以用户身份,这不仅提供了更精细的仓库权限控制,还无需依赖单个用户账户的凭据,且生成的令牌会自动轮换,并限定在特定仓库范围内。

提供两种模式:

托管 (github_app_auth_method: managed)
IBM Cloud 使用由 IBM 提供的 GitHub 应用程序,该应用程序已针对您的 GitHub 服务器进行了预注册。 您通过 OAuth 授权流程授权该应用,生成的用户到服务器令牌(ghu_ )将被自动存储和使用。
自定义 (github_app_auth_method: custom)
您可以在 GitHub 或 GitHub Enterprise 上注册并管理您自己的 GitHub 应用程序。 您需提供 App ID 以及一个采用 PEM 编码的 RSA 私钥。IBM Cloud 会利用这些凭据自动生成短效的安装访问令牌(ghs_ )。 您必须在每个希望与该集成配合使用的仓库上安装 GitHub 应用。

在开始进行自定义 GitHub 应用身份验证之前

在配置自定义的 GitHub 应用身份验证之前,请完成以下步骤:

  1. 在您的 GitHub 组织或个人账户中 创建一个 GitHub 应用。 请至少授予该应用以下仓库权限:

    • 内容:读写
    • 元数据:只读
    • 拉取请求:读取和写入(如果您使用拉取请求跟踪功能)
    • 工作流:读取和写入(如果您的管道触发了 GitHub 操作)
  2. 为该应用生成一个私钥,并保存 PEM 文件。 在配置集成时,您将需要此密钥。

  3. 在您的工具链将访问的组织或仓库上安装 GitHub 应用。 必须先安装该应用程序,才能验证凭据。

在您使用 App ID 和私钥配置工具集成后,IBM Cloud 将通过调用 GitHub API来验证凭据。 如果指定存储库中尚未安装该应用,您将收到一条错误提示,要求您先安装该应用。