Reutilizar fluxos de trabalho

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.

Visão geral

Em vez de copiar e colar de um fluxo de trabalho para outro, você pode tornar os fluxos de trabalho reutilizáveis. Você e qualquer pessoa com acesso ao fluxo de trabalho reutilizável pode chamar o fluxo de trabalho reutilizável a partir de outro fluxo de trabalho.

A reutilização dosfluxos de trabalho evita duplicação. Isso torna os fluxos de trabalho mais fáceis de manter e permite que você crie novos fluxos de trabalho mais rapidamente, desenvolvendo sobre o trabalho dos outros, assim como você faz com ações. A reutilização do fluxo de trabalho também promove práticas recomendadas, ajudando você a usar os fluxos de trabalho bem projetados, já testados e com a eficiência comprovada. Sua organização pode criar uma biblioteca de fluxos de trabalho reutilizáveis que pode ser mantida centralmente.

O diagrama abaixo mostra uma execução de fluxo de trabalho em andamento que usa um fluxo de trabalho reutilizável.

Depois que cada um dos três trabalhos de build à esquerda do diagrama for concluído com êxito, um trabalho dependente chamado "Implantar" será executado.
O trabalho "Implantar" chama um fluxo de trabalho reutilizável que contém três trabalhos: "Treinamento", "Revisão" e "Produção".
A tarefa de implantação "Produção" só é executada após a tarefa de "Treinamento" ter sido concluída com sucesso.
Quando um trabalho é direcionado a um ambiente, a execução do fluxo de trabalho exibe uma barra de progresso que mostra o número de etapas no trabalho. No diagrama abaixo, o trabalho "Produção" contém 8 etapas, com a etapa 6 sendo processada no momento.
O uso um fluxo de trabalho reutilizável para executar trabalhos de implantação permite que você execute esses trabalhos para cada compilação sem duplicar o código nos fluxos de trabalho.

Diagrama de um fluxo de trabalho chamando um fluxo de trabalho reutilizável.

Um fluxo de trabalho que usa outro fluxo de trabalho é referido como um fluxo de trabalho "de chamada". O fluxo de trabalho reutilizável é um fluxo de trabalho "chamado". Um fluxo de trabalho de chamada pode usar vários fluxos de trabalho chamados. Cada fluxo de trabalho chamado é referenciado em uma única linha. O resultado é que o arquivo de fluxo de trabalho de chamadas pode conter apenas algumas linhas de YAML mas pode executar um grande número de tarefas quando for executado. Quando um fluxo de trabalho é reutilizado, todo o fluxo de trabalho chamado é usado, como se fosse parte do fluxo de trabalho de chamada.

Se você reutilizar um fluxo de trabalho de um repositório diferente, todas as ações no fluxo de trabalho chamado são como se fizessem parte do fluxo de trabalho de chamada. Por exemplo, se o fluxo de trabalho chamado usar actions/checkout, a ação fará check-out do conteúdo do repositório que hospeda o fluxo de trabalho do chamador, não o fluxo de trabalho chamado.

Quando um fluxo de trabalho reutilizável é disparado por um fluxo de trabalho do chamador, o contexto github é sempre associado ao fluxo de trabalho do chamador. O fluxo de trabalho chamado recebe automaticamente o acesso a github.token e a secrets.GITHUB_TOKEN. Para saber mais sobre o contexto github, confira "Contextos".

Você pode visualizar os fluxos de trabalho referenciados nos seus fluxos de trabalho de GitHub Actions como dependências no gráfico de dependências do repositório que contém seus fluxos de trabalho. Para obter mais informações, confira “Sobre o grafo de dependência”.

Fluxos de trabalho e fluxos de trabalho iniciais reutilizáveis

Os fluxos de trabalho iniciais permitem que todos na sua organização que tenham permissão para criar fluxos de trabalho façam isso com mais rapidez e facilidade. Quando as pessoas criam um novo fluxo de trabalho, eles podem escolher um fluxo de trabalho inicial e uma parte ou todo o trabalho de escrita do fluxo de trabalho será feito para essas pessoas. Dentro de um fluxo de trabalho inicial, você também pode fazer referência a fluxos de trabalho reutilizáveis para facilitar a utilização de código de fluxo de trabalho gerenciado centralmente. Se você usar uma confirmação SHA ao fazer referência ao fluxo de trabalho reutilizável, você poderá garantir que todos que reutilizarem esse fluxo de trabalho sempre usarão o mesmo código YAML. No entanto, se você fizer referência a um fluxo de trabalho reutilizável por uma tag ou branch, certifique-se de que você poderá confiar nessa versão do fluxo de trabalho. Para obter mais informações, confira "Fortalecimento de segurança para o GitHub Actions".

Para obter mais informações, confira "Criando fluxos de trabalho iniciais para sua organização".

Acesso a fluxos de trabalho reutilizáveis

Um fluxo de trabalho reutilizável pode ser usado por outro fluxo de trabalho se qualquer uma das seguintes opções for verdadeira:

Ambos os fluxos de trabalho estão no mesmo repositório.
O fluxo de trabalho chamado é armazenado em um repositório público do .
O fluxo de trabalho chamado é armazenado em um repositório interno e as configurações para esse repositório permitem que ele seja acessado. Para saber mais, confira "Compartilhando ações e fluxos de trabalho com sua empresa".

Usando executores

Usar executores hospedados no GitHub

A atribuição de executores hospedados em GitHub é sempre avaliada usando apenas o contexto do chamador. A cobrança para executores hospedados em GitHub está sempre associada ao chamador. O fluxo de trabalho de chamadas não pode usar executores hospedados em GitHub a partir do repositório chamado. Para obter mais informações, confira "Sobre executores hospedados no GitHub".

Usando executores auto-hospedados

Fluxos de trabalho chamados que são propriedade do mesmo usuário ou organização ou empresa, uma vez que o fluxo de trabalho de chamadas pode acessar runners auto-hospedados no contexto do invocador. Isso significa que um fluxo de trabalho chamado pode acessar executores auto-hospedados que estão:

No repositório de chamada
Na organização ou empresa do repositório de chamadas, desde que o executor tenha sido disponibilizado para o repositório de chamada

Limitações

Os fluxos de trabalho reutilizáveis não podem chamar outros fluxos de trabalho reutilizáveis.
Você pode chamar até 20 fluxos de trabalho reutilizáveis por meio de um só arquivo de fluxo de trabalho.
Fluxos de trabalho reutilizáveis armazenados em um repositório privado só podem ser usados por fluxos de trabalho do mesmo repositório. * Não há suporte para a propriedade strategy em nenhum trabalho que chame um fluxo de trabalho reutilizável.
As variáveis de ambiente definidas em um contexto env definido no nível do fluxo de trabalho do chamador não são propagadas para o fluxo de trabalho chamado. Para obter mais informações, confira "Variáveis" e "Contextos."
Para reutilizar variáveis em vários fluxos de trabalho, defina-as nos níveis da organização, do repositório ou do ambiente e faça referência a elas usando o contexto vars. Para saber mais, confira "Variáveis" e "Contextos".

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.

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.

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:
      envPAT:
        required: true
```
Para obter detalhes da sintaxe usada para definir entradas e segredos, confira on.workflow_call.inputs e on.workflow_call.secrets.
No fluxo de trabalho reutilizável, faça referência à entrada ou ao segredo que você definiu na chave on na etapa anterior.
```
jobs:
  reusable_workflow_job:
    runs-on: ubuntu-latest
    environment: production
    steps:
    - uses: actions/labeler@v4
      with:
        repo-token: ${{ secrets.envPAT }}
        configuration-path: ${{ inputs.config-path }}
```
No exemplo acima, envPAT está um segredo de ambiente que foi adicionado ao ambiente production. Por conseguinte, este ambiente é mencionado no trabalho.

Observação: os segredos de ambiente são cadeias de caracteres criptografadas armazenadas em um ambiente que você definiu para um repositório. Os segredos de ambiente só estão disponíveis para trabalhos de fluxo de trabalho que fazem referência ao ambiente apropriado. Para obter mais informações, confira "Usando ambientes para implantação".
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:
      envPAT: ${{ secrets.envPAT }}
```

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@v4
      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

Referencie os arquivos do fluxo de trabalho reutilizável usando uma das seguintes sintaxes:

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

{ref} pode ser um SHA, uma tag de versão ou um nome de branch. Usar o commit SHA é o mais seguro para a estabilidade e segurança. Para obter mais informações, confira "Fortalecimento de segurança para o GitHub Actions". 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.

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

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:
      envPAT: ${{ secrets.envPAT }}

Palavras-chave compatíveis com trabalhos que chamam um fluxo de trabalho reutilizável

Ao chamar um fluxo de trabalho reutilizável, você só poderá usar as palavras-chave a seguir no trabalho que contém a chamada:

jobs.<job_id>.name
jobs.<job_id>.uses
jobs.<job_id>.with
jobs.<job_id>.with.<input_id>
jobs.<job_id>.secrets
jobs.<job_id>.secrets.<secret_id>
jobs.<job_id>.needs
jobs.<job_id>.if
jobs.<job_id>.permissions
jobs.<job_id>.concurrency
Observação:
- Se jobs.<job_id>.permissions não for especificado no trabalho de chamada, o fluxo de trabalho chamado terá as permissões padrão para o GITHUB_TOKEN. Para obter mais informações, confira "Autenticação automática de token".
- As permissões GITHUB_TOKEN transmitidas do fluxo de trabalho do chamador só podem ser rebaixadas (não elevadas) pelo fluxo de trabalho chamado.

Exemplo de fluxo de trabalho de chamada

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 }}

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.

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.

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 "::set-output name=firstword::hello"
      - id: step2
        run: echo "::set-output name=secondword::world"

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".

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. Incluído nos dados registrados:

repo – A organização/o repositório em que o trabalho de fluxo de trabalho está localizado. 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.
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 sobre como usar a API REST para consultar o log de auditoria de uma organização, confira "Organizações".

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.

Executar novamente fluxos de trabalho e trabalhos com fluxos de trabalho reutilizáveis

Fluxos de trabalho reutilizáveis de repositórios públicos podem ser referenciados usando um SHA, uma tag de lançamento ou um nome de branch. Para obter mais informações, confira "Reutilizar fluxos de trabalho".

Quando você executa novamente um fluxo de trabalho que usa um fluxo de trabalho reutilizável e a referência não é um SHA, há alguns comportamentos a serem observados:

A reexecução de todos os trabalhos em um fluxo de trabalho usará o fluxo de trabalho reutilizável da referência especificada. Para obter mais informações sobre como executar novamente todos os trabalhos em um fluxo de trabalho, confira "Reexecutando fluxos de trabalho e trabalhos".
Reexecutar trabalhos com falha ou um trabalho específico em um fluxo usará o fluxo de trabalho reutilizável do mesmo SHA de commit da primeira tentativa. Para obter mais informações sobre como executar novamente trabalhos com falha em um fluxo de trabalho, confira "Reexecutando fluxos de trabalho e trabalhos". Para obter mais informações sobre como executar um trabalho específico em um fluxo de trabalho, confira "Reexecutando fluxos de trabalho e trabalhos".

Próximas etapas

Para continuar aprendendo sobre o GitHub Actions, confira "Eventos que disparam fluxos de trabalho".

Você pode padronizar implantações criando um grupo de executores auto-hospedados que só pode executar um fluxo de trabalho específico reutilizável. Para obter mais informações, confira "Gerenciar o acesso a executores auto-hospedados usando grupos".

Reutilizar fluxos de trabalho

Neste artigo