Usando o OpenID Connect com fluxos de trabalho reutilizáveis

Você pode usar fluxos de trabalho reutilizáveis com o OIDC para padronizar e melhorar as suas etapas de implantação.

Neste artigo

Observação: no momento, não há suporte para os executores hospedados no GitHub no GitHub Enterprise Server. Você pode ver mais informações sobre o suporte futuro planejado no GitHub public roadmap.

Sobre fluxos de trabalho reutilizáveis

Em vez de copiar e colar trabalhos de implantação de um fluxo de trabalho para outro, é possível criar um fluxo de trabalho reutilizável que executa as etapas de implantação. Um fluxo de trabalho reutilizável poderá ser usado por outro fluxo de trabalho se atender a um dos requisitos de acesso descritos em Reutilizar fluxos de trabalho".

Você deve ter familiaridade com os conceitos descritos em "Reutilizar fluxos de trabalho" e "Sobre o enrijecimento de segurança com o OpenID Connect".

Definindo as condições de confiança

Quando combinado com o OpenID Connect (OIDC), os fluxos de trabalho reutilizáveis permitem que você aplique implantações consistentes no seu repositório, organização ou empresa. Você pode fazer isso definindo condições de confiança nas funções da nuvem com base em fluxos de trabalho reutilizáveis. As opções disponíveis variam dependendo do provedor de nuvem:

  • Usando job_workflow_ref:

    • Para criar condições de relação de confiança com base em fluxos de trabalho reutilizáveis, o provedor de nuvem precisa dar suporte a declarações personalizadas de job_workflow_ref. Isso permite que seu provedor de nuvem identifique de qual repositório veio originalmente.
    • Para nuvens que dão suporte apenas às declarações padrão (audiência [aud] e assunto [sub]), você pode usar a API para personalizar a declaração sub para incluir job_workflow_ref. Para obter mais informações, confira "Sobre o enrijecimento de segurança com o OpenID Connect". O suporte para declarações personalizadas está disponível atualmente para o Google Cloud Platform e o HashiCorp Vault.

  • Personalizando as declarações de token:

Como o token funciona com fluxos de trabalho reutilizáveis

Durante uma execução de um fluxo de trabalho, o provedor do OIDC de GitHub apresenta um token de OIDC para o provedor de nuvem que contém informações sobre o trabalho. Se esse trabalho fizer parte de um fluxo de trabalho reutilizável, o token incluirá as declarações padrão que contêm informações sobre o fluxo de trabalho chamador e incluirá uma declaração personalizada chamada job_workflow_ref que contém informações sobre o fluxo de trabalho chamado.

Por exemplo, o token do OIDC a seguir é para um trabalho que fazia parte de um fluxo de trabalho chamado. O workflow, a ref e outros atributos descrevem o fluxo de trabalho chamador, enquanto a job_workflow_ref se refere ao fluxo de trabalho chamado:

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://HOSTNAME/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://HOSTNAME/_services/token",
  "nbf": 1632492967,
  "exp": 1632493867,
  "iat": 1632493567
}

Se o seu fluxo de trabalho reutilizável executa etapas de implantação, ele, de modo geral, irá precisar de acesso a um função de nuvem específica, e você deverá permitir que qualquer repositório da sua organização chame esse fluxo de trabalho reutilizável. Para permitir isso, você criará uma condição de confiança que permite qualquer repositório e fluxo de trabalho de chamadas, e, em seguida, irá filtrar a organização e o fluxo de trabalho chamado. Veja a próxima seção para obter alguns exemplos.

Exemplos

Filtragem para fluxos de trabalho reutilizáveis em um repositório específico

É possível configurar uma reivindicação personalizada que filtra para qualquer fluxo de trabalho reutilizável em um repositório específico. Neste exemplo, a execução de fluxo de trabalho precisa ter se originado de um trabalho definido em um fluxo de trabalho reutilizável no repositório octo-org/octo-automation e em qualquer repositório pertencente à organização octo-org.

  • Assunto:

    • Sintaxe: repo:ORG_NAME/*
    • Exemplo: repo:octo-org/*

  • Declaração personalizada:

    • Sintaxe: job_workflow_ref:ORG_NAME/REPO_NAME
    • Exemplo: job_workflow_ref:octo-org/octo-automation@*

Filtragem de um fluxo de trabalho específico reutilizável em uma referência específica

Você pode configurar uma reivindicação personalizada que filtra um fluxo de trabalho específico reutilizável. Neste exemplo, a execução de fluxo de trabalho precisa ter se originado de um trabalho definido no fluxo de trabalho reutilizável octo-org/octo-automation/.github/workflows/deployment.yml e em qualquer repositório pertencente à organização octo-org.

  • Assunto:

    • Sintaxe: repo:ORG_NAME/*
    • Exemplo: repo:octo-org/*

  • Declaração personalizada:

    • Sintaxe: job_workflow_ref:ORG_NAME/REPO_NAME/.github/workflows/WORKFLOW_FILE@ref
    • Exemplo: job_workflow_ref:octo-org/octo-automation/.github/workflows/deployment.yml@ 10040c56a8c0253d69db7c1f26a0d227275512e2