Reutilizando configurações de fluxo de trabalho

Fluxos de trabalho reutilizáveis

Informações de referência para fluxos de trabalho reutilizáveis.

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 em GitHub Enterprise Server.

  Não é possível usar diretamente fluxos de trabalho reutilizáveis definidos em GitHub.com. Em vez disso, armazene uma cópia do fluxo de trabalho reutilizável em sua instância do GitHub Enterprise Server e chame o fluxo de trabalho desse caminho.

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

• O fluxo de trabalho chamado é armazenado em um repositório privado e as configurações desse repositório permitem que ele seja acessado. Para saber mais, confira Compartilhando ações e fluxos de trabalho com sua empresa.

A tabela a seguir mostra a acessibilidade de fluxos de trabalho reutilizáveis a um fluxo de trabalho do chamador, dependendo da visibilidade do repositório do host.

As permissões de Ações na página de configurações Ações do repositório de chamadores devem ser configuradas para permitir o uso de ações e fluxos de trabalho reutilizáveis. Confira Gerenciando as configurações do GitHub Actions para um repositório.

Para repositórios internos ou privados, a política de acesso na página de configurações de Ações do repositório do fluxo de trabalho chamado deve ser explicitamente configurada para permitir o acesso de repositórios que contenham fluxos de trabalho do chamado. Confira Gerenciando as configurações do GitHub Actions para um repositório.

Limitações dos fluxos de trabalho reutilizáveis

• Você pode conectar até quatro níveis de fluxos de trabalho. Para obter mais informações, confira Aninhar fluxos de trabalho reutilizáveis.

• Você pode chamar até 20 fluxos de trabalho reutilizáveis exclusivos por meio de um só arquivo de fluxo de trabalho. Esse limite inclui árvores de fluxos de trabalho aninhados reutilizáveis que podem ser chamados começando do arquivo de fluxo de trabalho do chamador de nível superior.

  Por exemplo, top-level-caller-workflow.yml → called-workflow-1.yml → called-workflow-2.yml conta como 2 fluxos de trabalho reutilizáveis.

• 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 saber mais, confira Armazenar informações em variáveis e Referência de contextos.

• Da mesma forma, as variáveis de ambiente definidas no contexto de env, definidas no fluxo de trabalho chamado, não são acessíveis no contexto do fluxo de trabalho do chamador env. Em vez disso, você deve usar saídas do fluxo de trabalho reutilizável. Para obter mais informações, consulte Usando saídas de um fluxo de trabalho reutilizável.

• 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 Armazenar informações em variáveis e Referência de contextos.

• Fluxos de trabalho reutilizáveis são chamados diretamente dentro de um trabalho, e não de dentro de uma etapa de trabalho. Portanto, você não pode usar GITHUB_ENV para passar valores para as etapas de trabalho no fluxo de trabalho do chamador.

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

• jobs.<job_id>.needs

• jobs.<job_id>.if

• jobs.<job_id>.concurrency

• jobs.<job_id>.permissions

  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 saber mais, confira Sintaxe de fluxo de trabalho para o GitHub Actions.
  • As permissões GITHUB_TOKEN transmitidas do fluxo de trabalho do chamador só podem ser rebaixadas (não elevadas) pelo fluxo de trabalho chamado.
  • Se você usar jobs.<job_id>.concurrency.cancel-in-progress: true, não use o mesmo valor para jobs.<job_id>.concurrency.group nos fluxos de trabalho chamado e chamador, pois isso fará com que o fluxo de trabalho que já está em execução seja cancelado. Um fluxo de trabalho chamado usa o nome de seu fluxo de trabalho chamador em ${{ github.workflow }}. Portanto, usar esse contexto como o valor de jobs.<job_id>.concurrency.group nos fluxos de trabalho chamador e chamado fará com que o fluxo de trabalho chamador seja cancelado quando o fluxo de trabalho chamado for executado.

Como os fluxos de trabalho reutilizáveis usam executores

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 saber mais, confira Executores hospedados no GitHub.

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

Acesso e permissões para fluxos de trabalho aninhados

Um fluxo de trabalho que contém fluxos de trabalho aninhados reutilizáveis falhará se qualquer um dos fluxos de trabalho aninhados estiver inacessível ao fluxo de trabalho inicial do chamador. Para obter mais informações, confira "Como acessar a fluxos de trabalho reutilizáveis".

As permissões GITHUB_TOKEN só podem ser as mesmas ou mais restritivas nos fluxos de trabalho aninhados. Por exemplo, na cadeia de fluxo de trabalho A > B > C, se o fluxo de trabalho A tiver permissão do token package: read, B e C não poderão ter a permissão package: write. Para saber mais, confira Usar GITHUB_TOKEN para autenticação em fluxos de trabalho.

Para obter informações sobre como usar a API para determinar quais arquivos de fluxo de trabalho estavam envolvidos em uma execução de fluxo de trabalho específica, confira Reutilizar fluxos de trabalho.

Comportamento de fluxos de trabalho reutilizáveis ao executar trabalhos novamente

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 saber mais, 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.

Contexto github

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 Referência de contextos.

Modelos de fluxo de trabalho

Informações de referência a serem usadas ao criar modelos de fluxo de trabalho para sua organização.

Disponibilidade do modelo de fluxo de trabalho

Você pode usar modelos em repositórios que correspondem ou têm visibilidade mais restrita do que o repositório modelo.

• Modelos de fluxo de trabalho em um repositório público do .github estão disponíveis para todos os tipos de repositório.
• Modelos de fluxo de trabalho em um repositório interno do .github só estão disponíveis para repositórios internos e privados.
• Modelos de fluxo de trabalho em um repositório privado do .github só estão disponíveis para repositórios privados.

Concedendo acesso a repositórios privados/internos

Se você estiver usando um repositório privado ou interno do .github, precisará conceder acesso de leitura aos usuários ou às equipes que precisarão usar os modelos.

O espaço reservado $default-branch

Caso precise se referir ao branch padrão de um repositório, use o espaço reservado $default-branch no modelo de fluxo de trabalho. Quando um fluxo de trabalho é criado, o espaço reservado será automaticamente substituído pelo nome do branch padrão do repositório.

Valores de espaço reservado na chave runs-on

Os seguintes valores na chave runs-on também são tratados como espaços reservados:

• ubuntu-latest é substituído por [ self-hosted ]
• windows-latest é substituído por [ self-hosted, windows ]
• macos-latest" é substituído por [ self-hosted, macOS ]

Exemplo de arquivo de modelo de fluxo de trabalho

Este arquivo chamado octo-organization-ci.yml demonstra um fluxo de trabalho básico.

name: Octo Organization CI
on:
  push:
    branches: [ $default-branch ]
  pull_request:
    branches: [ $default-branch ]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - name: Run a one-line script
        run: echo Hello from Octo Organization

name: Octo Organization CI
on:
  push:
    branches: [ $default-branch ]
  pull_request:
    branches: [ $default-branch ]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - name: Run a one-line script
        run: echo Hello from Octo Organization

Requisitos de arquivo de metadados

O arquivo de metadados precisa ter o mesmo nome do arquivo de fluxo de trabalho, mas, em vez da extensão .yml, é preciso acrescentar .properties.json a ele. Por exemplo, este arquivo chamado octo-organization-ci.properties.json contém os metadados para o arquivo de fluxo de trabalho chamado octo-organization-ci.yml:

{
    "name": "Octo Organization Workflow",
    "description": "Octo Organization CI workflow template.",
    "iconName": "example-icon",
    "categories": [
        "Go"
    ],
    "filePatterns": [
        "package.json$",
        "^Dockerfile",
        ".*\\.md$"
    ]
}

{
    "name": "Octo Organization Workflow",
    "description": "Octo Organization CI workflow template.",
    "iconName": "example-icon",
    "categories": [
        "Go"
    ],
    "filePatterns": [
        "package.json$",
        "^Dockerfile",
        ".*\\.md$"
    ]
}

• name - Obrigatório. Nome do fluxo de trabalho. É exibido na lista de fluxos de trabalho disponíveis.

• description - Obrigatório. Descrição do fluxo de trabalho. É exibido na lista de fluxos de trabalho disponíveis.

• iconName - Opcional. Especifica um ícone para o fluxo de trabalho exibido na lista correspondente. iconName pode ser de um dos seguintes tipos:

  • Um arquivo SVG armazenado no diretório de workflow-templates. Para fazer referência a um arquivo, o valor deve ser o nome do arquivo sem a extensão dele. Por exemplo, um arquivo SVG chamado example-icon.svg é referenciado como example-icon.
  • Um ícone do conjunto de Octicons do GitHub. Para fazer referência a um octicon, o valor dele deve ser octicon <icon name>. Por exemplo, octicon smiley.

• categories - Opcional. Define as categorias em que o fluxo de trabalho é mostrado. Você pode usar nomes de categoria das seguintes listas:

  • Nomes de categorias gerais do repositório starter-workflows.
  • Linguagens Linguist da lista de repositório em linguist.
  • Pilhas de tecnologia com suporte da lista no repositório starter-workflows.

• filePatterns - Opcional. Permite que o modelo seja usado caso o repositório do usuário tenha um arquivo no diretório raiz que corresponda a uma expressão regular definida.