Reutilizar fluxos de trabalho

Aprenda a evitar a duplicação ao criar um fluxo de trabalho reutilizando os fluxos de trabalho existentes.

Neste artigo

Criar um fluxo de trabalho reutilizável

Os fluxos de trabalho reutilizáveis são arquivos formatados com YAML, muito semelhantes a qualquer outro arquivo de fluxo de trabalho. Assim como acontece com outros arquivos de fluxo de trabalho, você localiza fluxos de trabalho reutilizáveis no diretório .github/workflows de um repositório. Não há suporte para subdiretórios do diretório workflows.

É possível padronizar implantações criando um grupo de executores auto-hospedados para executar apenas um fluxo de trabalho reutilizável específico. Para saber mais, confira Gerenciar o acesso a executores auto-hospedados usando grupos.

Para que um fluxo de trabalho seja reutilizável, os valores de on precisam incluir workflow_call:

on:
  workflow_call:

Usando entradas e segredos em um fluxo de trabalho reutilizável

Você pode definir entradas e segredos, que podem ser passados do fluxo de trabalho de de chamada e, em seguida, usados no fluxo de trabalho chamado. Há três etapas para usar uma entrada ou um segredo em um fluxo de trabalho reutilizável.

  1. No fluxo de trabalho reutilizável, use as palavras-chave inputs e secrets para definir entradas ou segredos que serão transmitidos de um fluxo de trabalho do chamador.

    on:
  workflow_call:
    inputs:
      config-path:
        required: true
        type: string
    secrets:
      personal_access_token:
        required: true

Para obter detalhes da sintaxe usada para definir entradas e segredos, confira on.workflow_call.inputs e on.workflow_call.secrets.

  1. No fluxo de trabalho reutilizável, faça referência à entrada ou ao segredo que você definiu na chave on na etapa anterior.

    Observação

    Se os segredos forem herdados usando secrets: inherit no fluxo de trabalho de chamada, você poderá referenciá-los mesmo que não estejam explicitamente definidos na chave on. Para saber mais, confira Sintaxe de fluxo de trabalho para o GitHub Actions.

    jobs:
  reusable_workflow_job:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/labeler@v6
      with:
        repo-token: ${{ secrets.personal_access_token }}
        configuration-path: ${{ inputs.config-path }}

    No exemplo acima, personal_access_token é um segredo definido no nível do repositório ou da organização.

    Aviso

    Os segredos do ambiente não podem ser transmitidos do fluxo de trabalho do chamador, pois on.workflow_call não dá suporte à palavra-chave environment. Se você incluir environment no fluxo de trabalho reutilizável no nível do trabalho, o segredo do ambiente será usado, não o segredo passado do fluxo de trabalho do chamador. Para saber mais, confira Gerenciar ambientes para implantação e Sintaxe de fluxo de trabalho para o GitHub Actions.

  2. Passe a entrada ou o segredo do fluxo de trabalho da chamada.

    Para transmitir entradas nomeadas para um fluxo de trabalho chamado, use a palavra-chave with em um trabalho. Use a palavra-chave secrets para transmitir segredos nomeados. Para entradas, o tipo de dado do valor de entrada deve corresponder ao tipo especificado no fluxo de trabalho chamado (booleano, número ou string).

    jobs:
  call-workflow-passing-data:
    uses: octo-org/example-repo/.github/workflows/reusable-workflow.yml@main
    with:
      config-path: .github/labeler.yml
    secrets:
      personal_access_token: ${{ secrets.token }}

    Fluxos de trabalho que chamam fluxos de trabalho reutilizáveis na mesma organização ou empresa podem usar a palavra-chave inherit para passar implicitamente os segredos.

    jobs:
  call-workflow-passing-data:
    uses: octo-org/example-repo/.github/workflows/reusable-workflow.yml@main
    with:
      config-path: .github/labeler.yml
    secrets: inherit

Exemplo de fluxo de trabalho reutilizável

Esse arquivo de fluxo de trabalho reutilizável chamado workflow-B.yml (vamos nos referir a ele mais adiante no exemplo de fluxo de trabalho do chamador) usa uma cadeia de caracteres de entrada e um segredo do fluxo de trabalho do chamador e os usa em uma ação.

YAML
name: Reusable workflow example

on:
  workflow_call:
    inputs:
      config-path:
        required: true
        type: string
    secrets:
      token:
        required: true

jobs:
  triage:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/labeler@v6
      with:
        repo-token: ${{ secrets.token }}
        configuration-path: ${{ inputs.config-path }}

Chamando um fluxo de trabalho reutilizável

Um fluxo de trabalho reutilizável é chamado por meio da palavra-chave uses. Ao contrário de quando você usa ações em um fluxo de trabalho, você chama os fluxos de trabalho reutilizáveis diretamente em um trabalho, e não de dentro de etapas de trabalho.

jobs.<job_id>.uses

Para fazer referência a arquivos reutilizáveis do fluxo de trabalho, use uma destas sintaxes:

  • {owner}/{repo}/.github/workflows/{filename}@{ref} para fluxos de trabalho reutilizáveis em repositórios públicos e privadospúblicos, internos e privados.
  • ./.github/workflows/{filename} para fluxos de trabalho reutilizáveis no mesmo repositório.

Na primeira opção, {ref} pode ser um SHA, uma marca de versão ou um nome de ramificação. Se uma marca de versão e um branch tiverem o mesmo nome, a marca terá precedência sobre o nome do branch. Usar o commit SHA é a opção mais segura para fins de estabilidade e segurança. Para saber mais, confira Referência de uso seguro.

Se você usar a segunda opção de sintaxe (sem {owner}/{repo} e @{ref}), o fluxo de trabalho chamado será proveniente do mesmo commit do fluxo de trabalho chamador. Prefixos de referência como refs/heads e refs/tags não são permitidos. Você não pode usar contextos ou expressões nesta palavra-chave.

Você pode chamar vários fluxos de trabalho, fazendo referência a cada um em um trabalho separado.

jobs:
  call-workflow-1-in-local-repo:
    uses: octo-org/this-repo/.github/workflows/workflow-1.yml@172239021f7ba04fe7327647b213799853a9eb89
  call-workflow-2-in-local-repo:
    uses: ./.github/workflows/workflow-2.yml
  call-workflow-in-another-repo:
    uses: octo-org/another-repo/.github/workflows/workflow.yml@v1

Exemplo de fluxo de trabalho do chamador

Este arquivo de fluxo de trabalho chama dois arquivos de fluxo de trabalho. O segundo deles, workflow-B.yml (mostrado no exemplo de fluxo de trabalho reutilizável), recebe uma entrada (config-path) e um segredo (token).

YAML
name: Call a reusable workflow

on:
  pull_request:
    branches:
      - main

jobs:
  call-workflow:
    uses: octo-org/example-repo/.github/workflows/workflow-A.yml@v1

  call-workflow-passing-data:
    permissions:
      contents: read
      pull-requests: write
    uses: octo-org/example-repo/.github/workflows/workflow-B.yml@main
    with:
      config-path: .github/labeler.yml
    secrets:
      token: ${{ secrets.GITHUB_TOKEN }}

Passando entradas e segredos para um fluxo de trabalho reutilizável

Para transmitir entradas nomeadas para um fluxo de trabalho chamado, use a palavra-chave with em um trabalho. Use a palavra-chave secrets para transmitir segredos nomeados. Para entradas, o tipo de dado do valor de entrada deve corresponder ao tipo especificado no fluxo de trabalho chamado (booleano, número ou string).

jobs:
  call-workflow-passing-data:
    uses: octo-org/example-repo/.github/workflows/reusable-workflow.yml@main
    with:
      config-path: .github/labeler.yml
    secrets:
      personal_access_token: ${{ secrets.token }}

Fluxos de trabalho que chamam fluxos de trabalho reutilizáveis na mesma organização ou empresa podem usar a palavra-chave inherit para passar implicitamente os segredos.

jobs:
  call-workflow-passing-data:
    uses: octo-org/example-repo/.github/workflows/reusable-workflow.yml@main
    with:
      config-path: .github/labeler.yml
    secrets: inherit

Como usar uma estratégia de matriz com um fluxo de trabalho reutilizável

Trabalhos que usam a estratégia de matriz podem chamar um fluxo de trabalho reutilizável.

Uma estratégia de matriz permite que você use variáveis em uma única definição de trabalho para criar automaticamente várias execuções de trabalho baseadas nas combinações das variáveis. Por exemplo, você pode usar uma estratégia de matriz a fim de passar entradas diferentes para um fluxo de trabalho reutilizável. Para obter mais informações sobre matrizes, confira Executando variações de tarefas em um workflow.

Este trabalho de exemplo abaixo chama um fluxo de trabalho reutilizável e faz referência ao contexto de matriz definindo a variável target com os valores [dev, stage, prod]. Ele executará três trabalhos, um para cada valor na variável.

YAML
jobs:
  ReusableMatrixJobForDeployment:
    strategy:
      matrix:
        target: [dev, stage, prod]
    uses: octocat/octo-repo/.github/workflows/deployment.yml@main
    with:
      target: ${{ matrix.target }}

Como aninhar fluxos de trabalho reutilizáveis

Você pode conectar um máximo de dez níveis de fluxos de trabalho - ou seja, o fluxo de trabalho do chamador de nível superior e até nove níveis de fluxos de trabalho reutilizáveis. Por exemplo: caller-workflow.yml → called-workflow-1.yml → called-workflow-2.yml → called-workflow-3.yml → ... → called-workflow-9.yml.

Loops na árvore de fluxo de trabalho não são permitidos.

Observação

Fluxos de trabalho reutilizáveis aninhados exigem que todos os fluxos de trabalho na cadeia sejam acessíveis ao chamador, e as permissões só podem ser mantidas ou reduzidas, e não elevadas, em toda a cadeia. Para saber mais, confira Reutilizando configurações de fluxo de trabalho.

De dentro de um fluxo de trabalho reutilizável, você pode chamar outro fluxo de trabalho reutilizável.

YAML
name: Reusable workflow

on:
  workflow_call:

jobs:
  call-another-reusable:
    uses: octo-org/example-repo/.github/workflows/another-reusable.yml@v1

Como passar informações confidenciais para fluxos de trabalho aninhados

Você pode usar jobs.<job_id>.secrets em um fluxo de trabalho de chamada para passar segredos nomeados para um fluxo de trabalho chamado diretamente. Como alternativa, você pode usar jobs.<job_id>.secrets.inherit para passar todos os segredos do fluxo de trabalho que efetuou a chamada para um fluxo de trabalho chamado diretamente. Para saber mais, confira a seção Reutilizar fluxos de trabalho acima e o artigo de referência Sintaxe de fluxo de trabalho para o GitHub Actions. Os segredos são passados apenas para o fluxo de trabalho chamado diretamente, portanto, na cadeia de fluxo de trabalho A > B > C, o fluxo de trabalho C só receberá segredos de A se tiverem sido passados de A para B e, em seguida, de B para C.

No exemplo a seguir, o fluxo de trabalho A passa todos os segredos dele para o fluxo de trabalho B, usando a palavra-chave inherit, mas o fluxo de trabalho B passa apenas um segredo para o fluxo de trabalho C. Qualquer um dos outros segredos passados para o fluxo de trabalho B não está disponível para o fluxo de trabalho C.

jobs:
  workflowA-calls-workflowB:
    uses: octo-org/example-repo/.github/workflows/B.yml@main
    secrets: inherit # pass all secrets

jobs:
  workflowB-calls-workflowC:
    uses: different-org/example-repo/.github/workflows/C.yml@main
    secrets:
      repo-token: ${{ secrets.personal_access_token }} # pass just this secret

Usando saídas de um fluxo de trabalho reutilizável

Um fluxo de trabalho reutilizável pode gerar dados que você deseja usar no fluxo de trabalho da chamada. Para usar essas saídas, você deve especificá-las como saídas do fluxo de trabalho reutilizável.

Se um fluxo de trabalho reutilizável que define uma saída for executado com uma estratégia de matriz, a saída será aquela definida pelo último fluxo de trabalho reutilizável que foi concluído com sucesso na matriz e que realmente definiu um valor. Isso significa que se o último fluxo de trabalho reutilizável bem-sucedido definir uma cadeia de caracteres vazia para sua saída e a segunda última conclusão bem-sucedida do fluxo de trabalho reutilizável definir um valor real para sua saída, a saída conterá o valor do segundo último fluxo de trabalho reutilizável.

O seguinte fluxo de trabalho reutilizável tem um único trabalho que contém duas etapas. Em cada uma dessas etapas, definimos uma única palavra como a saída: "olá" e "mundo". Na seção outputs do trabalho, mapeamos essas saídas de etapa para saídas de trabalho chamadas: output1 e output2. Na seção on.workflow_call.outputs, definimos duas saídas para o fluxo de trabalho em si, uma chamada firstword, que mapeamos para output1, e outra chamada secondword, que mapeamos para output2.

O value deve ser definido como o valor de uma saída de nível de trabalho no fluxo de trabalho chamado. As saídas em nível de etapa devem primeiro ser mapeadas às saídas em nível de trabalho, conforme mostrado abaixo.

Para saber mais, confira Passando informações entre tarefas e Sintaxe de fluxo de trabalho para o GitHub Actions.

YAML
name: Reusable workflow

on:
  workflow_call:
    # Map the workflow outputs to job outputs
    outputs:
      firstword:
        description: "The first output string"
        value: ${{ jobs.example_job.outputs.output1 }}
      secondword:
        description: "The second output string"
        value: ${{ jobs.example_job.outputs.output2 }}

jobs:
  example_job:
    name: Generate output
    runs-on: ubuntu-latest
    # Map the job outputs to step outputs
    outputs:
      output1: ${{ steps.step1.outputs.firstword }}
      output2: ${{ steps.step2.outputs.secondword }}
    steps:
      - id: step1
        run: echo "firstword=hello" >> $GITHUB_OUTPUT
      - id: step2
        run: echo "secondword=world" >> $GITHUB_OUTPUT

Agora podemos usar as saídas no fluxo de trabalho da chamada, da mesma forma que você usaria as saídas de um trabalho dentro do mesmo fluxo de trabalho. Referenciamos as saídas usando os nomes definidos no nível do fluxo de trabalho no fluxo de trabalho reutilizável: firstword e secondword. Nesse fluxo de trabalho, job1 chama o fluxo de trabalho reutilizável e job2 imprime as saídas do fluxo de trabalho reutilizável ("olá, mundo") para a saída padrão no log do fluxo de trabalho.

YAML
name: Call a reusable workflow and use its outputs

on:
  workflow_dispatch:

jobs:
  job1:
    uses: octo-org/example-repo/.github/workflows/called-workflow.yml@v1

  job2:
    runs-on: ubuntu-latest
    needs: job1
    steps:
      - run: echo ${{ needs.job1.outputs.firstword }} ${{ needs.job1.outputs.secondword }}

Para saber mais sobre como usar saídas de trabalho, confira Sintaxe de fluxo de trabalho para o GitHub Actions. Se você desejar compartilhar algo diferente de uma variável (por exemplo, um artefato de criação) entre fluxos de trabalho, consulte Armazenar e compartilhar dados com artefatos de fluxo de trabalho.

Monitorando quais fluxos de trabalho estão sendo utilizados

Você pode usar a API REST de GitHub para monitorar como os fluxos de trabalho reutilizáveis são usados. A ação prepared_workflow_job do log de auditoria é disparada quando um trabalho de fluxo de trabalho é iniciado. Estão incluídos nos dados registrados:

  • repo – A organização/o repositório em que a tarefa de fluxo de trabalho está localizada. Para um trabalho que chama outro fluxo de trabalho, este é a organização/repositório do fluxo de trabalho chamador.
  •           `@timestamp`: a data e a hora em que o trabalho foi iniciado, no formato de época do UNIX.
  • job_name – O nome do trabalho que foi executado.
  •           `calling_workflow_refs`: uma matriz de caminhos de arquivo para todos os fluxos de trabalho de chamador envolvidos neste trabalho de fluxo de trabalho. Os itens na matriz estão na ordem inversa em que foram chamados. Por exemplo, em uma cadeia de fluxos de trabalho A > B > C, ao exibir os logs de um trabalho no fluxo de trabalho C, a matriz seria `["octo-org/octo-repo/.github/workflows/B.yml", "octo-org/octo-repo/.github/workflows/A.yml"]`.

  •           `calling_workflow_shas`: uma matriz de SHAs para todos os fluxos de trabalho de chamador envolvidos neste trabalho de fluxo de trabalho. A matriz contém o mesmo número de itens, na mesma ordem, que a matriz `calling_workflow_refs`.
  • job_workflow_ref – O arquivo de fluxo de trabalho que foi usado, no formato {owner}/{repo}/{path}/{filename}@{ref}. Para um trabalho que chama outro fluxo de trabalho, isso identifica o fluxo de trabalho chamado.

Para saber mais, confira Revisar o log de auditoria da organização.

Observação

Os dados de auditoria de prepared_workflow_job só podem ser vistos por meio da API REST. Eles não são visíveis na interface web de GitHub ou incluídos nos dados de auditoria exportados pelo JSON/CSV.

Próximas etapas

Para encontrar informações sobre os meandros da reutilização de fluxos de trabalho, consulte Reutilizando configurações de fluxo de trabalho.