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.

Você não pode 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 a partir 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 obter mais informações, consulte 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 obter mais informações, consulte 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.

Repositório do chamador	Repositórios de fluxos de trabalho acessíveis
`private`

          `private`
          
          `internal`, e`public` |

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

Para repositórios internos ou privados, é necessário configurar explicitamente a política de Acesso na página de configurações de Ações do repositório do fluxo de trabalho chamado, permitindo o acesso por repositórios que contenham fluxos de trabalho de origem — consulte Gerenciando configurações de GitHub Actions para um repositório.

Observação

Para aprimorar a segurança, o GitHub Actions não dá suporte a redirecionamentos de ações nem a fluxos de trabalho reutilizáveis. Isso significa que quando o proprietário, o nome do repositório de uma ação ou o nome da ação é alterado, todos os fluxos de trabalho que usarem essa ação com o nome anterior falharão.

Limitações de 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 tarefas que utilizam 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 utiliza o nome do fluxo de trabalho de origem em ${{ github.workflow }}, então, usar esse contexto como o valor de jobs.<job_id>.concurrency.group tanto no fluxo de trabalho de origem quanto no fluxo de trabalho chamado fará com que o fluxo de trabalho de origem seja cancelado quando o fluxo de trabalho chamado for executado.

Como os fluxos de trabalho reutilizáveis usam executores

Executores hospedados em GitHub

A atribuição de executores hospedados em GitHub é sempre avaliada considerando apenas o contexto do chamador. A cobrança de executores hospedados em GitHub está sempre vinculada ao chamador. O fluxo de trabalho do chamador não pode utilizar executores hospedados em GitHub do repositório chamado. Para saber mais, confira Executores hospedados no GitHub.

Executores auto-hospedados

Fluxos de trabalho chamados que pertencem ao mesmo usuário, organização ou empresa que o fluxo de trabalho do chamador podem acessar executores auto-hospedados a partir do contexto do chamador. Isso significa que um fluxo de trabalho chamado pode acessar executores auto-hospedados que estão:

No repositório do chamador
Na organização ou empresa do repositório do chamador, desde que o executor tenha sido disponibilizado para esse repositório.

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 tarefas.
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 tarefas. Para obter mais informações sobre como executar um trabalho específico em um fluxo de trabalho, confira Reexecutando fluxos de trabalho e tarefas.

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.

O espaço reservado `$default-branch`

Se você precisar referir-se ao branch padrão de um repositório, pode usar o marcador de posição $default-branch em seu modelo de fluxo de trabalho. Quando um fluxo de trabalho é criado, o placeholder 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.

YAML

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:

JSON

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

Neste artigo