使用 OpenID Connect 和可重用工作流 - GitHub 文档

关于可重用工作流

与其将部署作业从一个工作流复制粘贴到另一个工作流，不如创建一个执行部署步骤的可重用工作流。如果可重用工作流满足“重用工作流”中描述的访问要求之一，则另一个工作流可以使用它。

您应该熟悉“重用工作流”和“关于使用 OpenID Connect 进行安全加固”中描述的概念。

定义信任条件

当与 OpenID Connect (OIDC) 结合使用时，可重用工作流允许您在存储库、组织或企业中强制执行一致的部署。您可以通过基于可重用工作流定义云角色的信任条件来实现这一点。可用的选项将根据您的云提供商而有所不同。

使用 job_workflow_ref:
- 要基于可重用工作流创建信任条件，您的云提供商必须支持 job_workflow_ref 的自定义声明。这允许您的云提供商识别作业最初来自哪个存储库。
- 对于仅支持标准声明（受众 (aud) 和主体 (sub)）的云，您可以使用 API 自定义 sub 声明以包含 job_workflow_ref。有关更多信息，请参阅“关于使用 OpenID Connect 加强安全性”。目前，Google Cloud Platform 和 HashiCorp Vault 支持自定义声明。
自定义令牌声明:
- 您可以通过自定义 JWT 中包含的主体 (sub) 声明来配置更细粒度的信任条件。有关更多信息，请参阅“关于使用 OpenID Connect 加强安全性”。

令牌如何与可重用工作流一起工作

在工作流运行期间，GitHub 的 OIDC 提供程序会向云提供程序呈现一个包含有关作业信息的 OIDC 令牌。如果该作业是可重用工作流的一部分，则令牌将包含包含有关调用工作流的信息的标准声明，并且还将包含一个名为 job_workflow_ref 的自定义声明，其中包含有关被调用工作流的信息。

例如，以下 OIDC 令牌用于作为被调用工作流一部分的作业。workflow、ref 和其他属性描述调用者工作流，而 job_workflow_ref 则引用被调用工作流。

YAML

{
  "typ": "JWT",
  "alg": "RS256",
  "x5t": "example-thumbprint",
  "kid": "example-key-id"
}
{
  "jti": "example-id",
  "sub": "repo:octo-org/octo-repo:environment:prod",
  "aud": "https://github.com/octo-org",
  "ref": "refs/heads/main",
  "sha": "example-sha",
  "repository": "octo-org/octo-repo",
  "repository_owner": "octo-org",
  "actor_id": "12",
  "repository_id": "74",
  "repository_owner_id": "65",
  "run_id": "example-run-id",
  "run_number": "10",
  "run_attempt": "2",
  "actor": "octocat",
  "workflow": "example-workflow",
  "head_ref": "",
  "base_ref": "",
  "event_name": "workflow_dispatch",
  "ref_type": "branch",
  "job_workflow_ref": "octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main",
  "iss": "https://token.actions.githubusercontent.com",
  "nbf": 1632492967,
  "exp": 1632493867,
  "iat": 1632493567
}

{
  "typ": "JWT",
  "alg": "RS256",
  "x5t": "example-thumbprint",
  "kid": "example-key-id"
}
{
  "jti": "example-id",
  "sub": "repo:octo-org/octo-repo:environment:prod",
  "aud": "https://github.com/octo-org",
  "ref": "refs/heads/main",
  "sha": "example-sha",
  "repository": "octo-org/octo-repo",
  "repository_owner": "octo-org",
  "actor_id": "12",
  "repository_id": "74",
  "repository_owner_id": "65",
  "run_id": "example-run-id",
  "run_number": "10",
  "run_attempt": "2",
  "actor": "octocat",
  "workflow": "example-workflow",
  "head_ref": "",
  "base_ref": "",
  "event_name": "workflow_dispatch",
  "ref_type": "branch",
  "job_workflow_ref": "octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main",
  "iss": "https://token.actions.githubusercontent.com",
  "nbf": 1632492967,
  "exp": 1632493867,
  "iat": 1632493567
}

如果您的可重用工作流执行部署步骤，则通常需要访问特定的云角色，并且您可能希望允许组织中的任何存储库调用该可重用工作流。为此，您将创建允许任何存储库和任何调用者工作流的信任条件，然后根据组织和被调用工作流进行筛选。有关一些示例，请参见下一节。

示例

筛选特定存储库内的可重用工作流

您可以配置一个自定义声明，用于筛选特定存储库中的任何可重用工作流。在此示例中，工作流运行必须源自 octo-org/octo-automation 存储库中可重用工作流中定义的作业，以及 octo-org 组织拥有的任何存储库。

主体:
- 语法：repo:ORG_NAME/*
- 示例：repo:octo-org/*
自定义声明:
- 语法：job_workflow_ref:ORG_NAME/REPO_NAME
- 示例：job_workflow_ref:octo-org/octo-automation@*

筛选特定 ref 上的特定可重用工作流

您可以配置一个自定义声明，用于筛选特定的可重用工作流。在此示例中，工作流运行必须源自可重用工作流 octo-org/octo-automation/.github/workflows/deployment.yml 中定义的作业，以及 octo-org 组织拥有的任何存储库。

主体:
- 语法：repo:ORG_NAME/*
- 示例：repo:octo-org/*
自定义声明:
- 语法：job_workflow_ref:ORG_NAME/REPO_NAME/.github/workflows/WORKFLOW_FILE@ref
- 示例：job_workflow_ref:octo-org/octo-automation/.github/workflows/deployment.yml@ 10040c56a8c0253d69db7c1f26a0d227275512e2

将 OpenID Connect 与可重用工作流一起使用

本文内容

关于可重用工作流

定义信任条件

令牌如何与可重用工作流一起工作

示例