Reutilizando fluxos de trabalho

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á foram testados e sua 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 três trabalhos de criação à esquerda do diagrama. Depois que cada um desses trabalhos é concluído com sucesso, executa-se uma tarefa dependente denominada "Implantação". Esse trabalho 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. 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.

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 ações/checkout, a ação verifica o conteúdo do repositório que hospeda o fluxo de trabalho de chamada, não o fluxo de trabalho chamado.

Quando um fluxo de trabalho reutilizável é acionado por um fluxo de trabalho de chamadas, o contexto github está sempre associado ao fluxo de trabalho de chamada. O fluxo de trabalho chamado tem acesso automaticamente a github.token e secrets.GITHUB_TOKEN. Para obter mais informações sobre o contexto do github ``, consulte "Contexto e sintaxe de expressão para o GitHub Actions".

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, consulte “Sobre o gráfico de dependências”.

Fluxos de trabalho e fluxos de trabalho iniciais reutilizáveis

Starter workflows allow everyone in your organization who has permission to create workflows to do so more quickly and easily. 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 tag ou nome de branch 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, consulte "Fortalecimento da segurança para GitHub Actions".

Para obter mais informações, consulte "Criando fluxos de trabalho iniciais para a 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 ou dos pontos a seguir for verdadeiro:

• Ambos os fluxos de trabalho estão no mesmo repositório.
• O fluxo de trabalho chamado é armazenado em um repositório público, e sua organização permite que você use fluxos de trabalho públicos reutilizáveis.

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, consulte "Sobre executores hospedados em GitHub".

Usando executores auto-hospedados

Fluxos de trabalho chamados que são propriedade do mesmo usuário ou organização, 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çãodo 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.
• Os fluxos de trabalho armazenados dentro de um repositório privado só podem ser usados por fluxos de trabalho dentro do mesmo repositório.
• Qualquer variável de ambiente definida em um contexto env definido no nível do fluxo de trabalho no fluxo de trabalho da chamada não é propagada para o fluxo de trabalho chamado. Para obter mais informações sobre o contexto env, consulte "Contexto e sintaxe de expressão para o GitHub Actions".
• A propriedade estratégia não é compatível com nenhum trabalho que chame um fluxo de trabalho reutilizável.

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. Como em outros arquivos de fluxo de trabalho, você localiza os fluxos de trabalho reutilizáveis no diretório .github/workflows de um repositório. Os subdiretórios do diretóriio fluxos de trabalho não são compatíveis.

Para que um fluxo de trabalho seja reutilizável, os valores de on devem 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 entradas e segredos para definir entradas ou segredos que serão passados de um fluxo de trabalho chamado.

   on:
     workflow_call:
       inputs:
         username:
           required: true
           type: string
       secrets:
         envPAT:
           required: true
   

   Para detalhes da sintaxe para definir entradas e segredos, consulte on.workflow_call.inputs, on.workflow_call.secrets and on.workflow_call.secrets.inherit.

2. No fluxo de trabalho reutilizável, faça referência à entrada ou segredo que você definiu na chave on chave na etapa anterior. Se os segredos são herdados usando secrets: inherit, você pode referenciá-los mesmo que eles não estejam definidos na chave on.

   jobs:
     reusable_workflow_job:
       runs-on: ubuntu-latest
       environment: production
       steps:
         - uses: ./.github/workflows/my-action
           with:
             username: ${{ inputs.username }}
             token: ${{ secrets.envPAT }}
   

   No exemplo acima, envPAT é um segredo de ambiente que foi adicionado ao ambiente de produção. Por conseguinte, este ambiente é mencionado no trabalho.

   Observação: Os segredos do ambiente são strings 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, consulte "Usando ambientes para implantação".

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

   Para passar entradas de nome para um fluxo de trabalho chamado, use a palavra-chave com em um trabalho. Use a palavra-chave segredos para passar 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:
         username: mona
       secrets:
         envPAT: ${{ secrets.envPAT }}
   

   Workflows that call reusable workflows in the same organization or enterprise can use the inherit keyword to implicitly pass the secrets.

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

Exemplo de fluxo de trabalho reutilizável

Este arquivo de workflow reutilizável chamado workflow-B.yml (faremos referência a ele mais adiante no exemplo do fluxo de trabalho de chamada) tem uma entrada e um segredo do fluxo de trabalho de chamadas e os usa em uma ação.

name: Reusable workflow example

on:
  workflow_call:
    inputs:
      username:
        required: true
        type: string
    secrets:
      token:
        required: true

jobs:
  example_job:
    name: Pass input and secrets to my-action
    runs-on: ubuntu-latest
    steps:
      - uses: ./.github/workflows/my-action
        with:
          username: ${{ inputs.username }}
          token: ${{ secrets.token }}

Chamando um fluxo de trabalho reutilizável

Você chama um fluxo de trabalho reutilizável usando a chave usa. 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

Você faz referência aos arquivos reutilizáveis do fluxo de trabalho usando uma das seguintes sintaxes:

• {owner}/{repo}/.github/workflows/{filename}@{ref} for reusable workflows in public repositories.
• ./.github/workflows/{filename} for reusable workflows in the same repository.

{ref} pode ser um SHA, uma tag de 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, consulte "Enrijecimento 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 é do mesmo commit que o fluxo de trabalho de chamada.

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 passar entradas de nome para um fluxo de trabalho chamado, use a palavra-chave com em um trabalho. Use a palavra-chave segredos para passar 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:
      username: mona
    secrets:
      envPAT: ${{ secrets.envPAT }}

Workflows that call reusable workflows in the same organization or enterprise can use the inherit keyword to implicitly pass the secrets.

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

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>.secrets.inherit

• 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 chamadas, o fluxo de trabalho chamado terá as permissões padrão para o GITHUB_TOKEN. Para obter mais informações, consulte "Autenticação em um fluxo de trabalho".

  • As permissões de GITHUB_TOKEN passadas do fluxo de trabalho de de cahamada 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 destes, workflow-B.yml (mostrado no exemplo exemplo do fluxo de trabalho reutilizável), fica depois de uma entrada (nome de usuário) e um segredo (token).

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:
    uses: octo-org/example-repo/.github/workflows/workflow-B.yml@main
    with:
      username: mona
    secrets:
      token: ${{ secrets.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 saídas do trabalho, nós mapeamos esses saídas de etapa para o trabalho chamada: ouput1 e ouput2. Em seguida, na seção on.workflow_call.outputs, definimos duas saídas para o próprio fluxo de trabalho, uma chamada firstword que mapeamos com output1, e uma chamada secondword que mapeamos com output2.

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. Fazemos referência às saídas usando os nomes definidos no nível do fluxo de trabalho no fluxo de trabalho reutilizável: firstword e secondword. Neste fluxo de trabalho, job1 chama o fluxo de trabalho reutilizável e job2 imprime as saídas do fluxo de trabalho reutilizável ("hello world") para a saída padrão no registro do fluxo de trabalho.

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 obter mais informações sobre o uso de saídas de trabalho, consulte "Sintaxe do Fluxo de trabalho para 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 do log de auditoria prepared_workflow_job é acionada quando um trabalho de fluxo de trabalho é iniciado. Incluído nos dados registrados:

• repo - a organização/repositório onde o trabalho do 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 epoch do Unix.
• job_name - o nome do trabalho executado.
• job_workflow_ref - o arquivo de fluxo de trabalho 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 obter informações sobre o uso da API REST para consultar o log de auditoria para uma organização, consulte "Organizações".

Próximas etapas

Para continuar aprendendo sobre GitHub Actions, consulte "Eventos que desencadeiam fluxos de trabalho".