Skip to main content

Enabling GitHub Actions with Amazon S3 storage

You can enable GitHub Actions on GitHub Enterprise Server and use Amazon S3 storage to store data generated by workflow runs.

谁可以使用此功能?

Site administrators can enable GitHub Actions and configure enterprise settings.

关于 GitHub Actions

的外部存储

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

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

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

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

Prerequisites

Note: The only GitHub-supported S3 storage providers are Amazon S3 and MinIO Gateway for NAS.

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

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

Before enabling GitHub Actions, make sure you have completed the following steps:

  • Create your Amazon S3 bucket for storing data generated by workflow runs.

  • 查看 GitHub Actions 的硬件要求。 有关详细信息,请参阅“Getting started with GitHub Actions for GitHub Enterprise Server”。

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

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

  • 如果在 你的 GitHub Enterprise Server 实例 上配置了 HTTP 代理服务器:

  • 必须将 .localhost127.0.0.1::1 添加到“HTTP 代理排除”**** 列表(以此顺序)。

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

有关更改代理设置的详细信息,请参阅“Configuring an outbound web proxy server”。

  • 如果使用 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 实例 进行身份验证。

To configure GitHub Enterprise Server to use OIDC with an Amazon S3 bucket, you must first create an Amazon OIDC provider, then create an Identity and Access Management (IAM) role, and finally configure GitHub Enterprise Server to use the provider and role to access your S3 bucket.

1. Create an Amazon OIDC provider

  1. Get the thumbprint for 你的 GitHub Enterprise Server 实例.

    1. Use the following OpenSSL command to get the SHA1 thumbprint for 你的 GitHub Enterprise Server 实例, replacing HOSTNAME with the public hostname for 你的 GitHub Enterprise Server 实例

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

      For example:

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

      The command returns a thumbprint in the following format:

      SHA1 Fingerprint=AB:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56
      
    2. Remove the colons (:) from the thumbprint value, and save the value to use later.

      For example, the thumbprint for the value returned in the previous step is:

      AB1234567890ABCDEF1234567890ABCDEF123456
      
  2. Using the AWS CLI, use the following command to create an OIDC provider for 你的 GitHub Enterprise Server 实例. Replace HOSTNAME with the public hostname for 你的 GitHub Enterprise Server 实例, and THUMBPRINT with the thumbprint value from the previous step.

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

    For example:

    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"
    

    For more information on installing the AWS CLI, see the Amazon documentation.

    Warning: If the certificate for 你的 GitHub Enterprise Server 实例 changes in the future, you must update the thumbprint value in the Amazon OIDC provider for the OIDC trust to continue to work.

2. Create an IAM role

  1. Open the AWS Console, and navigate to the Identity and Access Management (IAM) service.

  2. In the left menu, under "Access management", click Roles, then click Create Role.

  3. On the "Select trusted entity" page, enter the following options:

    • For "Trusted entity type", click Web identity.
    • For "Identity provider", use the Choose provider drop-down menu and select the OIDC provider you created in the previous steps. It should be named HOSTNAME/_services/token, where HOSTNAME is the public hostname for 你的 GitHub Enterprise Server 实例.
    • For "Audience", select sts.amazonaws.com.
  4. Click Next.

  5. On the "Add permissions" page, use the filter to find and select the AmazonS3FullAccess policy.

  6. Click Next.

  7. On the "Name, review, and create" page, enter a name for the role, and click Create role.

  8. On the IAM "Roles" page, select the role you just created.

  9. Under "Summary", note the ARN value for the role, as this is needed later.

  10. Click the Trust relationships tab, then click Edit trust policy.

  11. Edit the trust policy to add a new sub claim. The value for Condition must match the following example, replacing HOSTNAME with the public hostname for 你的 GitHub Enterprise Server 实例:

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

    For example:

    ...
    "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. Click Update policy.

3. Configure GitHub Enterprise Server to connect to Amazon S3 using OIDC

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

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

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

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

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

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

  7. Under "Authentication", select OpenID Connect (OIDC), and enter the values for your storage:

    • AWS S3 Bucket: The name of your S3 bucket.
    • AWS Role: The ARN for the role you created in the previous procedures. For example, arn:aws:iam::123456789:role/my-role-name.
    • AWS Region: The AWS region for your bucket. For example, us-east-1.
  8. 单击“测试存储设置”按钮验证存储设置。

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

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

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

  10. 等待配置运行完毕。

Enabling GitHub Actions with Amazon S3 storage using access keys

  1. Using the AWS Console or CLI, create an access key for your storage bucket. GitHub Actions 需要以下访问密钥的权限才可访问存储桶:

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

    For more information on managing AWS access keys, see the "AWS Identity and Access Management Documentation."

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

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

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

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

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

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

  8. Under "Authentication", select Credentials-based, and enter your storage bucket's details:

    • 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 Enterprise Server 实例 上启用。 对于后续步骤,例如管理 GitHub Actions 访问权限和添加自托管运行器,请返回到“Getting started with GitHub Actions for GitHub Enterprise Server”。