使用 Amazon S3 存储启用 GitHub Actions

可以在 GitHub Enterprise Server 上启用 GitHub Actions，并使用 Amazon S3 存储来存储工作流运行生成的数据。

谁可以使用此功能？

Site administrators can enable GitHub Actions and configure enterprise settings.

本文内容

关于 GitHub Actions

的外部存储

GitHub Actions 使用外部 blob 存储来存储工作流运行生成的数据。 存储的数据包括工作流日志、缓存和用户上传的生成工件。有关详细信息，请参阅“GitHub Actions for GitHub Enterprise Server 使用入门”。

可通过两个选项将 GitHub Enterprise Server 配置为连接到外部存储提供程序：

  • OpenID Connect (OIDC)
  • 使用机密的传统基于凭据的身份验证

建议尽可能使用 OIDC，因为不需要为存储提供程序创建或管理敏感且生存期较长的凭据机密，也不需要冒暴露这些机密的风险。 使用 OIDC 定义信任后，云存储提供程序会自动向 你的 GitHub Enterprise Server 实例 颁发短期访问令牌，这些令牌会自动过期。

先决条件

Note

支持 GitHub 的 S3 存储提供程序只有 Amazon S3 和适用于 NAS 的 MinIO 网关。

还有其他与 S3 API 兼容的存储产品，GitHub 合作伙伴已经将它们自我验证为可以与 GitHub Actions 在 GitHub Enterprise Server 上运行。 有关详细信息，请参阅 GHES 存储合作伙伴存储库。

对于通过 GitHub 技术合作伙伴计划验证的存储产品，存储提供商负责为将存储产品与 GitHub Actions 配合使用提供支持和文档。

在启用 GitHub Actions 之前，请确保您已完成以下步骤：

  • 创建 Amazon S3 存储桶，用于存储工作流程运行生成的数据。

  • 查看 GitHub Actions 的硬件要求。 有关详细信息，请参阅“GitHub Actions for GitHub Enterprise Server 使用入门”。

  • 必须为 GitHub Enterprise Server 的域配置 TLS。 有关详细信息，请参阅“配置 TLS”。

    注意： 我们强烈建议您在 GitHub Enterprise Server 上配置 TLS，并有信任的机构签名的证书。 虽然自签名证书可以工作，但自托管的运行器需要额外的配置，不推荐用于生产环境。

  • 如果在 GitHub 上配置了 HTTP 代理服务器：

  • 必须将 .localhost、127.0.0.1 和 ::1 添加到“HTTP 代理排除”**** 列表（以此顺序）。

  • 如果外部存储位置不可路由，则还必须将外部存储 URL 添加到排除列表中。

有关更改代理设置的详细信息，请参阅“配置出站 Web 代理服务器”。

  • 如果使用 OIDC 连接到存储提供商，则必须将 你的 GitHub Enterprise Server 实例 上的以下 OIDC 令牌服务 URL 公开到公共 Internet：

    https://HOSTNAME/_services/token/.well-known/openid-configuration
https://HOSTNAME/_services/token/.well-known/jwks

    这确保存储提供商可以联系 你的 GitHub Enterprise Server 实例 进行身份验证。

使用 OIDC 通过 Amazon S3 启用 GitHub Actions（推荐）

若要将 GitHub Enterprise Server 配置为将 OIDC 与 Amazon S3 存储桶配合使用，必须先创建 Amazon OIDC 提供程序，然后创建标识和访问管理 (IAM) 角色，最后配置 GitHub Enterprise Server 以使用该提供程序和角色访问 S3 存储桶。

1. 创建 Amazon OIDC 提供程序

  1. 获取 你的 GitHub Enterprise Server 实例 的指纹。

    1. 使用以下 OpenSSL 命令获取 你的 GitHub Enterprise Server 实例 的 SHA1 指纹，并将 HOSTNAME 替换为 你的 GitHub Enterprise Server 实例 的公共主机名

      Shell
      openssl s_client -connect HOSTNAME:443 < /dev/null 2>/dev/null | openssl x509 -fingerprint -noout -sha1 -in /dev/stdin

      例如：

      openssl s_client -connect my-ghes-host.example.com:443 < /dev/null 2>/dev/null | openssl x509 -fingerprint -noout -sha1 -in /dev/stdin

      此命令返回以下格式的指纹：

      SHA1 Fingerprint=AB:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56

    2. 从指纹值中删除冒号 (:)，并保存该值以供以后使用。

      例如，上一步中所返回值的指纹为：

      AB1234567890ABCDEF1234567890ABCDEF123456

  2. 使用 AWS CLI，使用以下命令为 你的 GitHub Enterprise Server 实例 创建 OIDC 提供程序。 将 HOSTNAME 替换为 你的 GitHub Enterprise Server 实例 的公共主机名，再将 THUMBPRINT 替换为上一步中的指纹值。

    Shell
    aws iam create-open-id-connect-provider \
  --url https://HOSTNAME/_services/token \
  --client-id-list "sts.amazonaws.com" \
  --thumbprint-list "THUMBPRINT"

    例如：

    Shell
    aws iam create-open-id-connect-provider \
  --url https://my-ghes-host.example.com/_services/token \
  --client-id-list "sts.amazonaws.com" \
  --thumbprint-list "AB1234567890ABCDEF1234567890ABCDEF123456"

    有关安装 AWS CLI 的详细信息，请参阅 Amazon 文档。

    Warning

    如果 你的 GitHub Enterprise Server 实例 的证书将来发生更改，则必须更新 Amazon OIDC 提供程序中的指纹值，获得 OIDC 信任以继续工作。

2. 创建 IAM 角色

  1. 打开 AWS 控制台，导航到标识和访问管理 (IAM) 服务。

  2. 在左侧菜单中的“访问管理”下，单击“角色”，然后单击“创建角色” 。

  3. 在“选择受信任的实体”页上，输入以下选项：

    • 对于“受信任的实体类型”，请单击“Web 标识”。
    • 对于“标识提供者”，请使用“选择提供程序”下拉菜单并选择在前面步骤中创建的 OIDC 提供程序。 应将其命名为 HOSTNAME/_services/token，其中 HOSTNAME 是 你的 GitHub Enterprise Server 实例 的公共主机名。
    • 对于“受众”，请选择 sts.amazonaws.com。

  4. 单击“下一步”。

  5. 在“添加权限”页上，使用筛选器查找并选择 AmazonS3FullAccess 策略。

  6. 单击“下一步”。

  7. 在“命名、查看和创建”页上，输入角色的名称，然后单击“创建角色”。

  8. 在 IAM“角色”页上，选择刚刚创建的角色。

  9. 在“摘要”下，记下角色的 ARN 值，因为稍后需要用到此值。

  10. 单击“信任关系”选项卡，然后单击“编辑信任策略” 。

  11. 编辑信任策略以添加新的 sub 声明。 Condition 的值必须匹配以下示例，将 HOSTNAME 替换为 你的 GitHub Enterprise Server 实例 的公共主机名：

    ...
"Condition": {
  "StringEquals": {
    "HOSTNAME/_services/token:aud": "sts.amazonaws.com",
    "HOSTNAME/_services/token:sub": "HOSTNAME"
  }
}
...

    例如：

    ...
"Condition": {
  "StringEquals": {
    "my-ghes-host.example.com/_services/token:aud": "sts.amazonaws.com",
    "my-ghes-host.example.com/_services/token:sub": "my-ghes-host.example.com"
  }
}
...

  12. 单击“更新策略”。

3. 将 GitHub Enterprise Server 配置为使用 OIDC 连接到 Amazon S3

  1. 在 GitHub Enterprise Server 上的管理帐户中，在任一页面的右上角，单击 。

  2. 如果你尚未在“站点管理员”页上，请在左上角单击“站点管理员”。

  3. 在“ 站点管理”边栏中，单击“管理控制台”。

  4. 在“设置”边栏中，单击“操作”。

  5. 在“GitHub Actions”下，选择“启用 GitHub Actions”。

  6. 在“项目和日志存储”下的“Amazon S3”旁，单击“设置”。

  7. 在“身份验证”下，选择“OpenID Connect (OIDC)”，然后输入存储的值：

    • AWS S3 存储桶：S3 存储桶的名称。
    • AWS 角色：在前面的过程中创建的角色的 ARN。 例如，arn:aws:iam::123456789:role/my-role-name。
    • AWS 区域：存储桶的 AWS 区域。 例如，us-east-1。

  8. 单击“测试存储设置”按钮验证存储设置。

    如果在验证存储设置时出现任何错误，请检查存储提供程序设置并重试。

  9. 在“设置”边栏下，单击“保存设置”。

    注意：保存 管理控制台 中的设置会重启系统服务，这可能会导致用户可察觉的停机时间。

  10. 等待配置运行完毕。

使用访问密钥通过 Amazon S3 存储启用 GitHub Actions

  1. 使用 AWS 控制台或 CLI 为存储桶创建访问密钥。 GitHub Actions 需要以下访问密钥的权限才可访问存储桶：

    • s3:PutObject
    • s3:GetObject
    • s3:ListBucketMultipartUploads
    • s3:ListMultipartUploadParts
    • s3:AbortMultipartUpload
    • s3:DeleteObject
    • s3:ListBucket
    • kms:GenerateDataKey（如果已启用密钥管理服务 (KMS) 加密）

    有关管理 AWS 访问密钥的详细信息，请参阅“AWS 标识和访问管理文档”。

  2. 在 GitHub Enterprise Server 上的管理帐户中，在任一页面的右上角，单击 。

  3. 如果你尚未在“站点管理员”页上，请在左上角单击“站点管理员”。

  4. 在“ 站点管理”边栏中，单击“管理控制台”。

  5. 在“设置”边栏中，单击“操作”。

  6. 在“GitHub Actions”下，选择“启用 GitHub Actions”。

  7. 在“项目和日志存储”下的“Amazon S3”旁，单击“设置”。

  8. 在“身份验证”下，选择“基于凭据”，然后输入存储桶的详细信息：

    • AWS 服务 URL：存储桶的服务 URL。 例如，如果你的 S3 存储桶是在 us-west-2 区域中创建的，则此值应为 https://s3.us-west-2.amazonaws.com。

      有关详细信息，请参阅 AWS 文档中的“AWS 服务终结点”。

    • AWS S3 存储桶：S3 存储桶的名称。

    • AWS S3 访问密钥和 AWS S3 密钥：存储桶的 AWS 访问密钥 ID 和密钥 。

  9. 单击“测试存储设置”按钮验证存储设置。

    如果在验证存储设置时出现任何错误，请检查存储提供程序设置并重试。

  10. 在“设置”边栏下，单击“保存设置”。

    注意：保存 管理控制台 中的设置会重启系统服务，这可能会导致用户可察觉的停机时间。

  11. 等待配置运行完毕。

后续步骤

配置运行成功完成后，GitHub Actions 将在 GitHub 上启用。 对于后续步骤，例如管理 GitHub Actions 访问权限和添加自托管运行器，请返回到“GitHub Actions for GitHub Enterprise Server 使用入门”。