Sintaxe de fluxo de trabalho para o GitHub Actions

Sobre sintaxe YAML para fluxos de trabalho

Os arquivos de fluxo de trabalho usam a sintaxe YAML e precisam ter uma extensão de arquivo .yml ou .yaml. Se você não estiver familiarizado com o YAML e quiser saber mais, confira "Aprenda a usar o YAML em Y minutos".

Você precisa armazenar os arquivos de fluxo de trabalho no diretório .github/workflows do repositório.

name

o nome do fluxo de trabalho. O GitHub exibe os nomes dos fluxos de trabalho na guia "Ações" do repositório. Se você omitir name, o GitHub o definirá como o caminho do arquivo de fluxo de trabalho em relação à raiz do repositório.

on

Para disparar automaticamente um fluxo de trabalho, use on para definir os eventos que podem fazer com que o fluxo de trabalho seja executado. Para obter uma lista de eventos disponíveis, confira "Eventos que disparam fluxos de trabalho".

Você pode definir um ou vários eventos que possam disparar um fluxo de trabalho ou definir um cronograma. Também é possível restringir a execução de um fluxo de trabalho para que ocorra apenas para altearções específicas para arquivos, tags ou alterações no branch. Essas opções são descritas nas seções a seguir.

Usando um evento único

Por exemplo, um fluxo de trabalho com o seguinte valor on será executado quando um push for feito em qualquer branch no repositório do fluxo de trabalho:

on: push

Usando eventos múltiplos

É possível especificar um único evento ou vários eventos. Por exemplo, um fluxo de trabalho com o valor on a seguir será executado quando um push for feito em qualquer branch no repositório ou quando alguém criar um fork do repositório:

on: [push, fork]

Se você especificar vários eventos, apenas um desses eventos deverá ocorrer para acionar seu fluxo de trabalho. Se vários eventos de acionamento para o seu fluxo de trabalho ocorrerem ao mesmo tempo, várias execuções de fluxo de trabalho serão acionadas.

Usando tipos de atividade

Alguns eventos têm tipos de atividade que oferecem mais controle sobre quando o fluxo de trabalho deve ser executado. Use on.<event_name>.types para definir o tipo de atividade de evento que vai disparar uma execução de fluxo de trabalho.

Por exemplo, o evento issue_comment tem os tipos de atividades created, edited e deleted. Se o fluxo de trabalho for disparado no evento label, ele será executado sempre que um rótulo for criado, editado ou excluído. Se você especificar o tipo de atividade created para o evento label, o fluxo de trabalho será executado quando um rótulo for criado, mas não quando um rótulo for editado ou excluído.

on:
  label:
    types:
      - created

Se você especificar vários tipos de atividades, apenas um desses tipos de atividade deverá ocorrer para acionar o fluxo de trabalho. Se vários tipos de atividade do evento de acionamento ocorrer em seu fluxo de trabalho ao mesmo tempo, várias execuções de fluxo de trabalho serão acionadas. Por exemplo, os acionadores de fluxo de trabalho a seguir quando um problema é aberto ou identificado. Se um problema com duas etiquetas for aberta, serão iniciadas três execuções de fluxos de trabalho: uma para o problema aberto e duas para os dois problemas etiquetados.

on:
  issues:
    types:
      - opened
      - labeled

Para obter mais informações sobre cada evento e os respectivos tipos de atividades, confira "Eventos que disparam fluxos de trabalho".

Usando filtros

Alguns eventos têm filtros que dão mais controle sobre quando seu fluxo de trabalho deve ser executado.

Por exemplo, o evento push tem um filtro branches que faz com que seu fluxo de trabalho seja executado somente quando ocorrer um push para um branch que corresponde ao filtro branches, em vez de quando ocorrer qualquer push.

on:
  push:
    branches:
      - main
      - 'releases/**'

Usando tipos de atividade e filtros com vários eventos

Se você especificar tipos de atividade ou filtros para um evento e seu fluxo de trabalho for acionado em vários eventos, você deverá configurar cada evento separadamente. Você deve acrescentar dois-pontos (:) a todos os eventos, incluindo eventos sem configuração.

Por exemplo, um fluxo de trabalho com o seguinte valor on será executado quando:

• Uma etiqueta foi criada
• Um push for feito para o branch main no repositório
• Um push é feito para um branch habilitado para GitHub Pages

on:
  label:
    types:
      - created
  push:
    branches:
      - main
  page_build:

on.<event_name>.types

Use on.<event_name>.types para definir o tipo de atividade que vai disparar uma execução de fluxo de trabalho. A maioria dos eventos GitHub são acionados por mais de um tipo de atividade. Por exemplo, o label é disparado quando um rótulo é created, edited ou deleted. A palavra-chave types permite restringir a atividade que faz com que o fluxo de trabalho seja executado. Quando apenas um tipo de atividade dispara um evento de webhook, a palavra-chave types é desnecessária.

Você pode usar uma matriz de eventos types. Para obter mais informações sobre cada evento e seus tipos de atividade, confira "Eventos que disparam fluxos de trabalho".

on:
  label:
    types: [created, edited]

on.<pull_request|pull_request_target>.<branches|branches-ignore>

Ao usar os eventos pull_request e pull_request_target, você pode configurar um fluxo de trabalho para ser executado somente para solicitações de pull direcionadas a branches específicos.

Use o filtro branches quando quiser incluir padrões de nomes de branches ou quando quiser incluir e excluir padrões de nomes de branches. Use o filtro branches-ignore quando quiser excluir apenas padrões de nomes de branches. Não é possível usar os filtros branches e branches-ignore para o mesmo evento em um fluxo de trabalho.

Se você definir branches/branches-ignore e paths/paths-ignore, o fluxo de trabalho só será executado quando ambos os filtros forem atendidos.

As palavras-chave branches e branches-ignore aceitam padrões glob que usam caracteres como *, **, +, ?, ! e outros para corresponder a mais de um nome de branch. Se um nome contiver um desses caracteres e você quiser ter uma correspondência literal, faça escape de cada um desses caracteres especiais com \. Para obter mais informações sobre padrões glob, confira o "Sintaxe de fluxo de trabalho para o GitHub Actions".

Exemplo: Incluindo branches

Os padrões definidos em branches são avaliados em relação ao nome da referência do Git. Por exemplo, o seguinte fluxo de trabalho será executado sempre que houver um evento pull_request para uma solicitação de pull direcionada a:

• Um branch chamado main (refs/heads/main)
• Um branch chamado mona/octocat (refs/heads/mona/octocat)
• Um branch cujo nome começa com releases/, como releases/10 (refs/heads/releases/10)

on:
  pull_request:
    # Sequence of patterns matched against refs/heads
    branches:    
      - main
      - 'mona/octocat'
      - 'releases/**'

Exemplo: Excluir branches

Quando um padrão corresponder ao padrão branches-ignore, o fluxo de trabalho não será executado. Os padrões definidos em branches são avaliados em relação ao nome da referência do Git. Por exemplo, o seguinte fluxo de trabalho será executado sempre que houver um evento pull_request, a menos que a solicitação de pull seja direcionada a:

• Um branch chamado mona/octocat (refs/heads/mona/octocat)
• Um branch cujo nome corresponde a releases/**-alpha, como releases/beta/3-alpha (refs/heads/releases/beta/3-alpha)

on:
  pull_request:
    # Sequence of patterns matched against refs/heads
    branches-ignore:    
      - 'mona/octocat'
      - 'releases/**-alpha'

Exemplo: Incluindo e excluindo branches

Não é possível usar branches e branches-ignore para filtrar o mesmo evento em um só fluxo de trabalho. Caso deseje incluir e excluir padrões de branch para um só evento, use o filtro branches com o caractere ! para indicar os branches que devem ser excluídos.

Se você definir um branch com o caractere !, também precisará definir, pelo menos, um branch sem o caractere !. Caso deseje apenas excluir os branches, use branches-ignore.

A ordem na qual você define os padrões é importante.

• Um padrão de correspondência negativa (precedido por !) após uma correspondência positiva excluirá a referência do Git.
• Um padrão positivo correspondente após uma correspondência negativa incluirá a Git ref novamente.

O fluxo de trabalho a seguir será executado em eventos pull_request para solicitações de pull direcionadas a releases/10 ou releases/beta/mona, mas não para solicitações de pull direcionadas a releases/10-alpha ou releases/beta/3-alpha, porque o padrão !releases/**-alpha negativo segue o padrão positivo.

on:
  pull_request:
    branches:    
      - 'releases/**'
      - '!releases/**-alpha'

on.push.<branches|tags|branches-ignore|tags-ignore>

Ao usar o evento push, você pode configurar um fluxo de trabalho para ser executado em marcas ou em branches específicos.

Use o filtro branches quando quiser incluir padrões de nomes de branches ou quando quiser incluir e excluir padrões de nomes de branches. Use o filtro branches-ignore quando quiser excluir apenas padrões de nomes de branches. Não é possível usar os filtros branches e branches-ignore para o mesmo evento em um fluxo de trabalho.

Use o filtro tags quando quiser incluir padrões de nomes de marcas ou quando quiser incluir e excluir padrões de nomes de marcas. Use o filtro tags-ignore quando quiser excluir apenas padrões de nomes de marcas. Não é possível usar os filtros tags e tags-ignore para o mesmo evento em um fluxo de trabalho.

Se você definir apenas tags/tags-ignore ou apenas branches/branches-ignore, o fluxo de trabalho não será executado para eventos que afetam a referência indefinida do Git. Se você não definir tags/tags-ignore nem branches/branches-ignore, o fluxo de trabalho será executado para eventos que afetam branches ou marcas. Se você definir branches/branches-ignore e paths/paths-ignore, o fluxo de trabalho só será executado quando ambos os filtros forem atendidos.

As palavras-chave branches, branches-ignore, tags e tags-ignore aceitam padrões glob que usam caracteres como *, **, +, ?, ! e outros para corresponder a mais de um nome de marca ou de branch. Se um nome contiver um desses caracteres e você quiser ter uma correspondência literal, faça escape de cada um desses caracteres especiais com \. Para obter mais informações sobre padrões glob, confira o "Sintaxe de fluxo de trabalho para o GitHub Actions".

Exemplo: Incluindo branches e tags

Os padrões definidos em branches e tags são avaliados em relação ao nome de referência do Git. Por exemplo, o seguinte fluxo de trabalho será executado sempre que houver um evento push para:

• Um branch chamado main (refs/heads/main)
• Um branch chamado mona/octocat (refs/heads/mona/octocat)
• Um branch cujo nome começa com releases/, como releases/10 (refs/heads/releases/10)
• Uma marca chamada v2 (refs/tags/v2)
• Uma marca cujo nome começa com v1., como v1.9.1 (refs/tags/v1.9.1)

on:
  push:
    # Sequence of patterns matched against refs/heads
    branches:    
      - main
      - 'mona/octocat'
      - 'releases/**'
    # Sequence of patterns matched against refs/tags
    tags:        
      - v2
      - v1.*

Exemplo: Excluindo branches e tags

Quando um padrão corresponder ao padrão branches-ignore ou tags-ignore, o fluxo de trabalho não será executado. Os padrões definidos em branches e tags são avaliados em relação ao nome de referência do Git. Por exemplo, o seguinte fluxo de trabalho será executado sempre que houver um evento push, a menos que o evento push seja para:

• Um branch chamado mona/octocat (refs/heads/mona/octocat)
• Um branch cujo nome corresponde a releases/**-alpha, como beta/3-alpha (refs/releases/beta/3-alpha)
• Uma marca chamada v2 (refs/tags/v2)
• Uma marca cujo nome começa com v1., como v1.9 (refs/tags/v1.9)

on:
  push:
    # Sequence of patterns matched against refs/heads
    branches-ignore:    
      - 'mona/octocat'
      - 'releases/**-alpha'
    # Sequence of patterns matched against refs/tags
    tags-ignore:        
      - v2
      - v1.*

Exemplo: Incluindo e excluindo branches e tags

Não é possível usar branches e branches-ignore para filtrar o mesmo evento em um fluxo de trabalho individual. Da mesma forma, não é possível usar tags e tags-ignore para filtrar o mesmo evento em um fluxo de trabalho individual. Caso deseje incluir e excluir padrões de branch para um evento individual, use o filtro branches ou tags com o caractere ! para indicar as marcas ou os branches que devem ser excluídos.

Se você definir um branch com o caractere !, também precisará definir, pelo menos, um branch sem o caractere !. Caso deseje apenas excluir os branches, use branches-ignore. Da mesma forma, se você definir uma marca com o caractere !, também precisará definir, pelo menos, uma marca sem o caractere !. Caso deseje apenas excluir as marcas, use tags-ignore.

A ordem na qual você define os padrões é importante.

• Um padrão de correspondência negativa (precedido por !) após uma correspondência positiva excluirá a referência do Git.
• Um padrão positivo correspondente após uma correspondência negativa incluirá a Git ref novamente.

O fluxo de trabalho a seguir será executado em pushes para releases/10 ou releases/beta/mona, mas não em releases/10-alpha ou releases/beta/3-alpha porque o padrão !releases/**-alpha negativo vem após o padrão positivo.

on:
  push:
    branches:
      - 'releases/**'
      - '!releases/**-alpha'

on.<push|pull_request|pull_request_target>.<paths|paths-ignore>

Ao usar os eventos push e pull_request, você pode configurar um fluxo de trabalho para ser executado com base nos caminhos de arquivo alterados. Os filtros de caminho não são avaliados em pushes de tags.

Use o filtro paths quando quiser incluir padrões de caminho de arquivo ou quando quiser incluir e excluir padrões de caminho de arquivo. Use o filtro paths-ignore quando quiser apenas excluir padrões de caminho de arquivo. Não é possível usar os filtros paths e paths-ignore para o mesmo evento em um fluxo de trabalho.

Se você definir branches/branches-ignore e paths, o fluxo de trabalho só será executado quando ambos os filtros forem atendidos.

As palavras-chave paths e paths-ignore aceitam padrões glob que usam os caracteres curinga * e ** para fazer a correspondência com mais de um nome de caminho. Para obter mais informações, confira "Sintaxe de fluxo de trabalho para o GitHub Actions".

Exemplo: Incluindo caminhos

Se, pelo menos, um caminho corresponder a um padrão no filtro paths, o fluxo de trabalho será executado. Por exemplo, o fluxo de trabalho a seguir será executado sempre que você efetuar push de um arquivo JavaScript (.js).

on:
  push:
    paths:
      - '**.js'

Exemplo: Excluindo caminhos

Quando todos os nomes de caminho corresponderem aos padrões de paths-ignore, o fluxo de trabalho não será executado. Se qualquer nome de caminho não corresponder aos padrões de paths-ignore, mesmo que alguns nomes de caminho correspondam aos padrões, o fluxo de trabalho será executado.

Um fluxo de trabalho com o filtro de caminho a seguir só será executado em eventos push que incluem, pelo menos, um arquivo fora do diretório docs na raiz do repositório.

on:
  push:
    paths-ignore:
      - 'docs/**'

Exemplo: Incluindo e excluindo caminhos

Não é possível usar paths e paths-ignore para filtrar o mesmo evento em um fluxo de trabalho individual. Caso deseje incluir e excluir padrões de caminho para um evento individual, use o filtro paths com o caractere ! para indicar os caminhos que devem ser excluídos.

Se você definir um caminho com o caractere !, também precisará definir, pelo menos, um caminho sem o caractere !. Caso você deseje apenas excluir os caminhos, use paths-ignore.

A ordem de definição dos padrões é importante:

• Um padrão de correspondência negativa (precedido por !) após uma correspondência positiva excluirá o caminho do Git.
• Um padrão positivo correspondente após uma correspondência negativa incluirá o caminho novamente.

Este exemplo é executado sempre que o evento push inclui um arquivo no diretório sub-project ou nos respectivos subdiretórios, a menos que o arquivo esteja no diretório sub-project/docs. Por exemplo, um push que alterar sub-project/index.js ou sub-project/src/index.js vai disparar uma execução de fluxo de trabalho, mas um push que só altera sub-project/docs/readme.md não.

on:
  push:
    paths:
      - 'sub-project/**'
      - '!sub-project/docs/**'

Comparações Git diff

O filtro determina se um fluxo de trabalho deve ser executado avaliando os arquivos alterados e executando-os na lista paths-ignore ou paths. Se não houver arquivos alterados, o fluxo de trabalho não será executado.

O GitHub gera a lista de arquivos alterados usando diffs de dois pontos para pushes e diffs de três pontos para pull requests:

• Solicitações de pull: as comparações de três pontos são uma comparação entre a versão mais recente do branch do tópico e o commit em que o branch do tópico foi sincronizado pela última vez com o branch base.
• Pushes para branches existentes: uma comparação de dois pontos compara os SHAs principal e base diretamente um com o outro.
• Pushes para novos branches: uma comparação de dois pontos com o pai do ancestral do commit mais profundo enviado por push.

Os diffs limitam-se a 300 arquivos. Se houver arquivos alterados que não correspondam aos primeiros 300 arquivos retornados pelo filtro, o fluxo de trabalho não será executado. Talvez seja necessário criar filtros mais específicos para que o fluxo de trabalho seja executado automaticamente.

Para obter mais informações, confira "Sobre como comparar branches nas pull requests".

on.schedule

Use on.schedule para definir um agendamento de tempo para seus fluxos de trabalho. Você pode agendar um fluxo de trabalho para ser executado em horários UTC específicos usando a sintaxe cron POSIX. Fluxos de trabalho agendados executados no último commit no branch padrão ou branch de base. O intervalo mais curto que você pode executar fluxos de trabalho agendados é a cada 5 minutos.

Este exemplo aciona o fluxo de trabalho todos os dias às 17:30 e 17:30 UTC:

on:
  schedule:
    # * is a special character in YAML so you have to quote this string
    - cron:  '30 5,17 * * *'

Um fluxo de trabalho individual pode ser disparado por vários eventos schedule. Você pode acessar o evento de agendamento que disparou o fluxo de trabalho por meio do contexto github.event.schedule. Este exemplo dispara o fluxo de trabalho a ser executado às 5h30 UTC todas as segundas e quintas, mas ignora a etapa Not on Monday or Wednesday às segundas e quartas.

on:
  schedule:
    - cron: '30 5 * * 1,3'
    - cron: '30 5 * * 2,4'

jobs:
  test_schedule:
    runs-on: ubuntu-latest
    steps:
      - name: Not on Monday or Wednesday
        if: github.event.schedule != '30 5 * * 1,3'
        run: echo "This step will be skipped on Monday and Wednesday"
      - name: Every time
        run: echo "This step will always run"

Para obter mais informações sobre a sintaxe de cron, confira "Eventos que disparam fluxos de trabalho".

on.workflow_call

Use on.workflow_call para definir as entradas e as saídas de um fluxo de trabalho reutilizável. Você também pode mapear os segredos disponíveis para o fluxo de trabalho chamado. Para obter mais informações sobre os fluxos de trabalho reutilizáveis, confira "Reutilizar fluxos de trabalho".

on.workflow_call.inputs

Ao usar a palavra-chave workflow_call, você poderá, opcionalmente, especificar as entradas que são transmitidas para o fluxo de trabalho chamado do fluxo de trabalho de chamada. Para obter mais informações sobre a palavra-chave workflow_call, confira "Eventos que disparam fluxos de trabalho".

Além dos parâmetros de entrada padrão disponíveis, on.workflow_call.inputs exige um parâmetro type. Para obter mais informações, confira on.workflow_call.inputs.<input_id>.type.

Se um parâmetro default não estiver definido, o valor padrão da entrada será false para um booliano, 0 para um número e "" para uma cadeia de caracteres.

No fluxo de trabalho chamado, você pode usar o contexto inputs para se referir a uma entrada. Para obter mais informações, confira "Contextos".

Se um fluxo de trabalho de chamada passar uma entrada que não é especificada no fluxo de trabalho de chamada, isso irá gerar um erro.

Exemplo de on.workflow_call.inputs

on:
  workflow_call:
    inputs:
      username:
        description: 'A username passed from the caller workflow'
        default: 'john-doe'
        required: false
        type: string

jobs:
  print-username:
    runs-on: ubuntu-latest

    steps:
      - name: Print the input name to STDOUT
        run: echo The username is ${{ inputs.username }}

Para obter mais informações, confira "Reutilizar fluxos de trabalho".

on.workflow_call.inputs.<input_id>.type

Obrigatório se a entrada for definida para a palavra-chave on.workflow_call. O valor deste parâmetro é uma string que especifica o tipo de dados da entrada. Precisa ser boolean, number ou string.

on.workflow_call.outputs

Um mapa de saídas para um fluxo de trabalho chamado. As saídas de fluxo de trabalho chamadas estão disponíveis para todas as tarefas a jusante no fluxo de trabalho de chamadas. Cada saída tem um identificador, uma description, opcional e um value.. O value precisa ser definido como o valor de uma saída de um trabalho no fluxo de trabalho chamado.

No exemplo abaixo, duas saídas são definidas para esse fluxo de trabalho reutilizável: workflow_output1 e workflow_output2. Elas são mapeadas para as saídas chamadas job_output1 e job_output2, ambas de um trabalho chamado my_job.

Exemplo de on.workflow_call.outputs

on:
  workflow_call:
    # Map the workflow outputs to job outputs
    outputs:
      workflow_output1:
        description: "The first job output"
        value: ${{ jobs.my_job.outputs.job_output1 }}
      workflow_output2:
        description: "The second job output"
        value: ${{ jobs.my_job.outputs.job_output2 }}

Para obter informações sobre como referenciar uma saída de trabalho, confira jobs.<job_id>.outputs. Para obter mais informações, confira "Reutilizar fluxos de trabalho".

on.workflow_call.secrets

Um mapa dos segredos que pode ser usado no fluxo de trabalho de chamada.

No fluxo de trabalho chamado, você pode usar o contexto secrets para se referir a um segredo.

Se um fluxo de trabalho de chamada passar um segredo que não é especificado no fluxo de trabalho chamado, isso irá gerar um erro.

Exemplo de on.workflow_call.secrets

on:
  workflow_call:
    secrets:
      access-token:
        description: 'A token passed from the caller workflow'
        required: false

jobs:

  pass-secret-to-action:
    runs-on: ubuntu-latest
    steps:
    # passing the secret to an action
      - name: Pass the received secret to an action
        uses: ./.github/actions/my-action
        with:
          token: ${{ secrets.access-token }}

  # passing the secret to a nested reusable workflow
  pass-secret-to-workflow:
    uses: ./.github/workflows/my-workflow
    secrets:
       token: ${{ secrets.access-token }}

on.workflow_call.secrets.<secret_id>

Um identificador de string para associar ao segredo.

on.workflow_call.secrets.<secret_id>.required

Um booleano que especifica se o segredo deve ser fornecido.

on.workflow_run.<branches|branches-ignore>

Ao usar o evento workflow_run, você pode especificar os branches nos quais o fluxo de trabalho de gatilho precisa ser executado para disparar o fluxo de trabalho.

Os filtros branches e branches-ignore aceitam padrões glob que usam caracteres como *, **, +, ?, ! e outros para corresponder a mais de um nome de branch. Se um nome contiver um desses caracteres e você quiser ter uma correspondência literal, faça escape de cada um desses caracteres especiais com \. Para obter mais informações sobre padrões glob, confira o "Sintaxe de fluxo de trabalho para o GitHub Actions".

Por exemplo, um fluxo de trabalho com o seguinte gatilho só será executado quando o fluxo de trabalho chamado Build for executado em um branch cujo nome começa com releases/:

on:
  workflow_run:
    workflows: ["Build"]
    types: [requested]
    branches:
      - 'releases/**'

Um fluxo de trabalho com o seguinte gatilho só será executado quando o fluxo de trabalho chamado Build for executado em um branch que não seja chamado canary:

on:
  workflow_run:
    workflows: ["Build"]
    types: [requested]
    branches-ignore:
      - "canary"

Não é possível usar os filtros branches e branches-ignore para o mesmo evento em um fluxo de trabalho. Caso deseje incluir e excluir padrões de branch para um só evento, use o filtro branches com o caractere ! para indicar os branches que devem ser excluídos.

A ordem na qual você define os padrões é importante.

• Um padrão de correspondência negativa (precedido por !) após uma correspondência positiva excluirá o branch.
• Um padrão positivo correspondente após uma correspondência negativa incluirá o branch novamente.

Por exemplo, um fluxo de trabalho com o gatilho a seguir será executado quando o fluxo de trabalho chamado Build for executado em um branch chamado releases/10 ou releases/beta/mona que não será releases/10-alpha, releases/beta/3-alpha ou main.

on:
  workflow_run:
    workflows: ["Build"]
    types: [requested]
    branches:
      - 'releases/**'
      - '!releases/**-alpha'

on.workflow_dispatch

Ao usar o evento workflow_dispatch, opcionalmente, você pode especificar as entradas que são transmitidas para o fluxo de trabalho.

on.workflow_dispatch.inputs

O fluxo de trabalho disparado recebe as entradas no contexto do inputs. Para obter mais informações, confira "Contextos".

Exemplo de on.workflow_dispatch.inputs

on:
  workflow_dispatch:
    inputs:
      logLevel:
        description: 'Log level'
        required: true
        default: 'warning'
        type: choice
        options:
          - info
          - warning
          - debug
      print_tags:
        description: 'True to print to STDOUT'
        required: true
        type: boolean
      tags:
        description: 'Test scenario tags'
        required: true
        type: string
      environment:
        description: 'Environment to run tests against'
        type: environment
        required: true

jobs:
  print-tag:
    runs-on: ubuntu-latest
    if:  ${{ inputs.print_tags }} 
    steps:
      - name: Print the input tag to STDOUT
        run: echo  The tags are ${{ inputs.tags }} 

on.workflow_dispatch.inputs.<input_id>.required

Um booliano que especifica se a entrada precisa ser fornecida.

on.workflow_dispatch.inputs.<input_id>.type

O valor deste parâmetro é uma string que especifica o tipo de dados da entrada. Precisa ser boolean, choice, number ou string.

permissions

Use permissions para modificar as permissões padrão concedidas ao GITHUB_TOKEN, adicionando ou removendo o acesso conforme necessário, de modo que você só permita o acesso mínimo necessário. Para obter mais informações, confira "Autenticação automática de token".

Use permissions como uma chave de nível superior a ser aplicada a todos os trabalhos no fluxo de trabalho ou em trabalhos específicos. Quando você adiciona a chave permissions a um trabalho específico, todas as ações e os comandos de execução nesse trabalho que usam o GITHUB_TOKEN obtêm os direitos de acesso especificados. Para obter mais informações, confira jobs.<job_id>.permissions.

Valores de acesso e escopos disponíveis:

permissions:
  actions: read|write|none
  checks: read|write|none
  contents: read|write|none
  deployments: read|write|none
  issues: read|write|none
  discussions: read|write|none
  packages: read|write|none
  pages: read|write|none
  pull-requests: read|write|none
  repository-projects: read|write|none
  security-events: read|write|none
  statuses: read|write|none

Se você especificar o acesso para um desses escopos, todos aqueles que não são especificados serão definidos como none.

Você pode usar a sintaxe a seguir para definir o acesso de leitura ou gravação para todos os escopos disponíveis:

permissions: read-all|write-all

Você pode usar a seguinte sintaxe para desabilitar as permissões para todos os escopos disponíveis:

permissions: {}
``` Além disso, você pode usar a chave `permissions` para adicionar e remover permissões de leitura para repositórios com fork, mas normalmente não pode permitir acesso de gravação. A exceção desse comportamento é quando um usuário administrador selecionou a opção **Enviar tokens para fluxos de trabalho de solicitações de pull** nas configurações do GitHub Actions. Para obter mais informações, confira "[AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#enabling-workflows-for-private-repository-forks)".

### Exemplo: Atribuindo permissões ao GITHUB_TOKEN

Este exemplo mostra as permissões que estão sendo definidas para o `GITHUB_TOKEN` que se aplicará a todos os trabalhos no fluxo de trabalho. É concedido acesso de leitura a todas as permissões.

```yaml
name: "My workflow"

on: [ push ]

permissions: read-all

jobs:
  ...

env

Um map das variáveis que estão disponíveis para as etapas de todos os trabalhos do fluxo de trabalho. Também é possível definir variáveis que estão disponíveis apenas para as etapas de um trabalho ou para uma só etapa. Para obter mais informações, confira jobs.<job_id>.env e jobs.<job_id>.steps[*].env.

As variáveis no mapa env não podem ser definidas em termos de outras variáveis no mapa.

Quando mais de uma variável de ambiente é definida com o mesmo nome, GitHub usa a variável mais específica. Por exemplo, uma variável de ambiente definida em uma etapa substituirá as variáveis de ambiente do trabalho e do fluxo de trabalho que tenham o mesmo nome enquanto a etapa é executada. Uma variável de ambiente definida para um trabalho substituirá uma variável de fluxo de trabalho com o mesmo nome enquanto o trabalho é executado.

Exemplo de env

env:
  SERVER: production

defaults

Use defaults para criar um map das configurações padrão que será aplicado a todos os trabalhos do fluxo de trabalho. Você também pode definir as configurações-padrão disponíveis para um trabalho. Para obter mais informações, confira jobs.<job_id>.defaults.

Quando mais de uma configuração padrão é definida com o mesmo nome, GitHub usa a configuração padrão mais específica. Por exemplo, uma configuração padrão definida em uma tarefa irá substituir uma configuração padrão que tem o mesmo nome definido em um fluxo de trabalho.

defaults.run

Você pode usar defaults.run para fornecer as opções shell e working-directory padrão para todas as etapas do run em um fluxo de trabalho. Você também pode definir configurações padrão para run as quais só estão disponíveis para um trabalho. Para obter mais informações, confira jobs.<job_id>.defaults.run. Você não pode usar contextos ou expressões nesta palavra-chave.

Quando mais de uma configuração padrão é definida com o mesmo nome, GitHub usa a configuração padrão mais específica. Por exemplo, uma configuração padrão definida em uma tarefa irá substituir uma configuração padrão que tem o mesmo nome definido em um fluxo de trabalho.

Exemplo: Defina o shell padrão e o diretório de trabalho

defaults:
  run:
    shell: bash
    working-directory: scripts

concurrency

Use concurrency para garantir que apenas um trabalho ou um fluxo de trabalho que usa o mesmo grupo de simultaneidade seja executado por vez. Um grupo de concorrência pode ser qualquer string ou expressão. A expressão só pode usar o contexto github. Para obter mais informações sobre expressões, confira "Expressões".

Você também pode especificar concurrency no nível do trabalho. Para obter mais informações, confira jobs.<job_id>.concurrency.

Quando um trabalho ou um fluxo de trabalho simultâneo é colocado na fila, se outro trabalho ou fluxo de trabalho que usa o mesmo grupo de simultaneidade no repositório estiver em andamento, o trabalho ou o fluxo de trabalho na fila ficará pending. Qualquer trabalho ou fluxo de trabalho anterior pendente no grupo de concorrência será cancelado. Para também cancelar qualquer trabalho ou fluxo de trabalho em execução no mesmo grupo de simultaneidade, especifique cancel-in-progress: true.

Exemplos: Como usar a concorrência e o comportamento padrão

concurrency: staging_environment

concurrency: ci-${{ github.ref }}

Exemplo: Usar a concorrência para cancelar qualquer trabalho em andamento ou em execução

concurrency:
  group: ${{ github.ref }}
  cancel-in-progress: true

Exemplo: Usando um valor para segunda opção

Se você construir o nome do grupo com uma propriedade que só é definida para eventos específicos, você pode usar um valor de segunda opção. Por exemplo, github.head_ref só é definido em eventos pull_request. Se o fluxo de trabalho responder a outros eventos além de eventos pull_request, você precisará fornecer um fallback para evitar um erro de sintaxe. O grupo de simultaneidade a seguir cancela os trabalhos em andamento ou é executado somente em eventos pull_request. Se github.head_ref for indefinido, o grupo de simultaneidade fará fallback para a ID de execução, que tem a garantia de ser exclusiva e definida para a execução.

concurrency:
  group: ${{ github.head_ref || github.run_id }}
  cancel-in-progress: true

Exemplo: Cancele somente trabalhos em andamento ou execuções no fluxo de trabalho atual

Se você tiver vários fluxos de trabalho no mesmo repositório, os nomes dos grupos de concorrência devem ser únicos em todos os fluxos de trabalho para evitar o cancelamento de trabalhos em andamento ou de executores a partir de outros fluxos de trabalho. Caso contrário, qualquer trabalho em andamento ou pendente será cancelado, independentemente do fluxo de trabalho.

Para cancelar apenas as execuções em andamento do mesmo fluxo de trabalho, use a propriedade github.workflow para criar o grupo de simultaneidade:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs

Uma execução de fluxo de trabalho é composta por um ou mais jobs, que são executados em paralelo por padrão. Para executar trabalhos sequencialmente, você pode definir dependências em outros trabalhos usando a palavra-chave jobs.<job_id>.needs.

Cada trabalho é executado em um ambiente do executor especificado por runs-on.

Você pode executar quantos trabalhos desejar, desde que esteja dentro dos limites de uso do fluxo de trabalho. Para obter mais informações, confira "Limites de uso, cobrança e administração" para executores hospedados no GitHub e "Sobre executores auto-hospedados" para saber os limites de uso dos executores auto-hospedados.

Se precisar encontrar o identificador exclusivo de uma tarefa em execução em um fluxo de trabalho, você poderá usar a API de GitHub Enterprise Server. Para obter mais informações, confira "Ações".

jobs.<job_id>

Use jobs.<job_id> para fornecer ao seu trabalho um identificador exclusivo. A chave job_id é uma cadeia de caracteres, e o valor dela é um mapa dos dados de configuração do trabalho. Você precisa substituir <job_id> por uma cadeia de caracteres exclusiva para o objeto jobs. A <job_id> precisa começar com uma letra ou _ e conter apenas caracteres alfanuméricos, - ou _.

Exemplo: Criando trabalhos

Neste exemplo, dois trabalhos foram criados, e os valores de job_id são my_first_job e my_second_job.

jobs:
  my_first_job:
    name: My first job
  my_second_job:
    name: My second job

jobs.<job_id>.name

Use jobs.<job_id>.name para definir um nome para o trabalho, que é exibido na interface do usuário do GitHub.

jobs.<job_id>.permissions

Para um trabalho específico, você pode usar jobs.<job_id>.permissions para modificar as permissões padrão concedidas ao GITHUB_TOKEN, adicionando ou removendo o acesso conforme necessário, para que você permita apenas o acesso mínimo necessário. Para obter mais informações, confira "Autenticação automática de token".

Ao especificar a permissão em uma definição de trabalho, você pode configurar um conjunto diferente de permissões para o GITHUB_TOKEN em cada trabalho, se necessário. Como alternativa, você pode especificar as permissões para todas as tarefas do fluxo de trabalho. Para obter informações sobre como definir permissões no nível do fluxo de trabalho, confira permissions.

Valores de acesso e escopos disponíveis:

permissions:
  actions: read|write|none
  checks: read|write|none
  contents: read|write|none
  deployments: read|write|none
  issues: read|write|none
  discussions: read|write|none
  packages: read|write|none
  pages: read|write|none
  pull-requests: read|write|none
  repository-projects: read|write|none
  security-events: read|write|none
  statuses: read|write|none

Se você especificar o acesso para um desses escopos, todos aqueles que não são especificados serão definidos como none.

Você pode usar a sintaxe a seguir para definir o acesso de leitura ou gravação para todos os escopos disponíveis:

permissions: read-all|write-all

Você pode usar a seguinte sintaxe para desabilitar as permissões para todos os escopos disponíveis:

permissions: {}
``` Além disso, você pode usar a chave `permissions` para adicionar e remover permissões de leitura para repositórios com fork, mas normalmente não pode permitir acesso de gravação. A exceção desse comportamento é quando um usuário administrador selecionou a opção **Enviar tokens para fluxos de trabalho de solicitações de pull** nas configurações do GitHub Actions. Para obter mais informações, confira "[AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#enabling-workflows-for-private-repository-forks)".

### Exemplo: Configurar permissões para um trabalho específico

Este exemplo mostra as permissões que estão sendo definidas para o `GITHUB_TOKEN` que se aplicará somente ao trabalho chamado `stale`. O acesso de gravação é permitido para os escopos `issues` e `pull-requests`. Todos os outros escopos não terão acesso.

```yaml
jobs:
  stale:
    runs-on: ubuntu-latest

    permissions:
      issues: write
      pull-requests: write

    steps:
      - uses: actions/stale@v5

jobs.<job_id>.needs

Use jobs.<job_id>.needs para identificar todos os trabalhos que precisam ser concluídos com êxito antes que este trabalho seja executado. Esse código pode ser uma string ou array de strings. Se houver falha em um trabalho ou ele for ignorado, todos os trabalhos que dependem dele serão ignorados, a menos que os trabalhos usem uma expressão condicional que faça o trabalho continuar. Se uma execução contiver uma série de trabalhos que precisem uns dos outros, uma falha ou omissão se aplicará a todos os trabalhos na cadeia de dependência do ponto de falha ou omissão em diante.

Exemplo: Exigindo trabalhos dependentes com sucesso

jobs:
  job1:
  job2:
    needs: job1
  job3:
    needs: [job1, job2]

Neste exemplo, job1 precisa ser concluído com êxito antes que job2 seja iniciado, e job3 aguarda a conclusão de job1 e de job2.

Os trabalhos neste exemplo são executados sequencialmente:

1. job1
2. job2
3. job3

Exemplo: Não exigindo trabalhos dependentes com sucesso

jobs:
  job1:
  job2:
    needs: job1
  job3:
    if: ${{ always() }}
    needs: [job1, job2]

Neste exemplo, job3 usa a expressão condicional always() para que ela sempre seja executada após a conclusão de job1 e de job2, independentemente de elas terem sido bem-sucedidas. Para obter mais informações, confira "Expressões".

jobs.<job_id>.if

Use o condicional jobs.<job_id>.if para impedir que um trabalho seja executado, a não ser que uma condição seja atendida. Você pode usar qualquer contexto e expressão compatível para criar uma condicional. Para obter mais informações sobre quais contextos têm suporte nessa chave, confira "Disponibilidade de contexto".

Ao usar expressões em um condicional if, você pode omitir a sintaxe de expressão (${{ }}), porque o GitHub avalia automaticamente o condicional if como uma expressão. Para obter mais informações, confira "Expressões".

Exemplo: Somente executar o trabalho para um repositório específico

Este exemplo usa if para controlar quando o trabalho production-deploy pode ser executado. Ele só será executado se o repositório for chamado octo-repo-prod e estiver na organização octo-org. Caso contrário, o trabalho será marcado como ignorado.

name: example-workflow
on: [push]
jobs:
  production-deploy:
    if: github.repository == 'octo-org/octo-repo-prod'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '14'
      - run: npm install -g bats

jobs.<job_id>.runs-on

Use jobs.<job_id>.runs-on para definir o tipo de computador no qual o trabalho será executado.

• O computador de destino pode ser um executor auto-hospedado.

• Você pode direcionar executores com base nos rótulos atribuídos a eles.

• Você pode fornecer runs-on como uma única cadeia de caracteres ou como uma matriz de cadeias de caracteres.

• Se você especificar uma matriz de cadeias de caracteres, o fluxo de trabalho será executado em qualquer executor que corresponda a todos os valores runs-on especificados.

• Se você quiser executar seu fluxo de trabalho em vários computadores, use jobs.<job_id>.strategy.

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.

Escolhendo executores hospedados em GitHub

Se você usar um executor hospedado no GitHub, cada trabalho será executado em uma nova instância de uma imagem do executor especificada por runs-on.

Os tipos de executor disponíveis para GitHub são:

Exemplo: Especificar um sistema operacional

runs-on: ubuntu-latest

Para obter mais informações, confira "Sobre executores hospedados no GitHub".

Escolhendo executores auto-hospedados

Para especificar um executor auto-hospedado para seu trabalho, configure runs-on no arquivo de fluxo de trabalho com rótulos do executor auto-hospedado.

Todos os executores auto-hospedados têm o rótulo self-hosted. Se você só usar esse rótulo, isso selecionará qualquer executor auto-hospedado. Para selecionar os executores que atendem a determinados critérios, como sistema operacional ou arquitetura, recomendamos fornecer uma matriz de rótulos que começa com self-hosted (isso precisa ser listado primeiro) e, em seguida, inclui rótulos adicionais, conforme necessário. Quando você especificar uma matriz de rótulos, os trabalhos serão colocados na fila nos executores que têm todos os rótulos especificados.

Embora o rótulo self-hosted não seja necessário, recomendamos fortemente especificá-lo ao usar executores auto-hospedados para garantir que o seu trabalho não especifique acidentalmente nenhum executor atual ou futuro hospedado no GitHub.

Exemplo: Usando etiquetas para seleção do executor

runs-on: [self-hosted, linux]

Para obter mais informações, confira "Sobre executores auto-hospedados" e "Usar os executores auto-hospedados em um fluxo de trabalho."

jobs.<job_id>.environment

Use jobs.<job_id>.environment para definir o ambiente que o trabalho referencia. Todas as regras de proteção do ambiente têm de ser aprovadas para que um trabalho que faça referência ao ambiente seja enviado a um executor. Para obter mais informações, confira "Usando ambientes para implantação".

Você pode fornecer o ambiente como apenas o ambiente name ou como um objeto de ambiente com o name e a url. A URL é mapeada para environment_url na a API de implantações. Para obter mais informações sobre a API de implantações, confira "Repositórios".

Exemplo: Usando um único nome de ambiente

environment: staging_environment

Exemplo: Usando o nome de ambiente e URL

environment:
  name: production_environment
  url: https://github.com

A URL pode ser uma expressão e pode usar qualquer contexto, exceto o contexto secrets. Para obter mais informações sobre expressões, confira "Expressões".

Exemplo: Usando a saída como URL

environment:
  name: production_environment
  url: ${{ steps.step_id.outputs.url_output }}

jobs.<job_id>.concurrency

Você pode usar jobs.<job_id>.concurrency para garantir que apenas um trabalho ou fluxo de trabalho que usa o mesmo grupo de simultaneidade seja executado por vez. Um grupo de concorrência pode ser qualquer string ou expressão. A expressão pode usar qualquer contexto, exceto o contexto secrets. Para obter mais informações sobre expressões, confira "Expressões".

Especifique também concurrency no nível do fluxo de trabalho. Para obter mais informações, confira concurrency.

Quando um trabalho ou um fluxo de trabalho simultâneo é colocado na fila, se outro trabalho ou fluxo de trabalho que usa o mesmo grupo de simultaneidade no repositório estiver em andamento, o trabalho ou o fluxo de trabalho na fila ficará pending. Qualquer trabalho ou fluxo de trabalho anterior pendente no grupo de concorrência será cancelado. Para também cancelar qualquer trabalho ou fluxo de trabalho em execução no mesmo grupo de simultaneidade, especifique cancel-in-progress: true.

Exemplos: Como usar a concorrência e o comportamento padrão

concurrency: staging_environment

concurrency: ci-${{ github.ref }}

Exemplo: Usar a concorrência para cancelar qualquer trabalho em andamento ou em execução

concurrency:
  group: ${{ github.ref }}
  cancel-in-progress: true

Exemplo: Usando um valor para segunda opção

Se você construir o nome do grupo com uma propriedade que só é definida para eventos específicos, você pode usar um valor de segunda opção. Por exemplo, github.head_ref só é definido em eventos pull_request. Se o fluxo de trabalho responder a outros eventos além de eventos pull_request, você precisará fornecer um fallback para evitar um erro de sintaxe. O grupo de simultaneidade a seguir cancela os trabalhos em andamento ou é executado somente em eventos pull_request. Se github.head_ref for indefinido, o grupo de simultaneidade fará fallback para a ID de execução, que tem a garantia de ser exclusiva e definida para a execução.

concurrency:
  group: ${{ github.head_ref || github.run_id }}
  cancel-in-progress: true

Exemplo: Cancele somente trabalhos em andamento ou execuções no fluxo de trabalho atual

Se você tiver vários fluxos de trabalho no mesmo repositório, os nomes dos grupos de concorrência devem ser únicos em todos os fluxos de trabalho para evitar o cancelamento de trabalhos em andamento ou de executores a partir de outros fluxos de trabalho. Caso contrário, qualquer trabalho em andamento ou pendente será cancelado, independentemente do fluxo de trabalho.

Para cancelar apenas as execuções em andamento do mesmo fluxo de trabalho, use a propriedade github.workflow para criar o grupo de simultaneidade:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs.<job_id>.outputs

Você pode usar jobs.<job_id>.outputs para criar um map das saídas para um trabalho. As saídas de trabalho estão disponíveis para todos os trabalhos downstream que dependem deste trabalho. Para obter mais informações sobre como definir dependências de trabalho, confira jobs.<job_id>.needs.

As saídas são cadeias de caracteres Unicode e podem ter no máximo 1 MB. O total de todas as saídas em uma execução de fluxo de trabalho pode ter no máximo 50 MB.

As saídas de trabalho que contêm expressões são avaliadas no executor ao final de cada trabalho. As saídas que contêm segredos são eliminadas no executor e não são enviadas para GitHub Actions.

Para usar saídas de trabalho em um trabalho dependente, você pode usar o contexto needs. Para obter mais informações, confira "Contextos".

Exemplo: Definindo saídas para um trabalho

jobs:
  job1:
    runs-on: ubuntu-latest
    # Map a step output to a job output
    outputs:
      output1: ${{ steps.step1.outputs.test }}
      output2: ${{ steps.step2.outputs.test }}
    steps:
      - id: step1
        run: echo "::set-output name=test::hello"
      - id: step2
        run: echo "::set-output name=test::world"
  job2:
    runs-on: ubuntu-latest
    needs: job1
    steps:
      - env:
          OUTPUT1: ${{needs.job1.outputs.output1}}
          OUTPUT2: ${{needs.job1.outputs.output2}}
        run: echo "$OUTPUT1 $OUTPUT2"

jobs.<job_id>.env

Um map das variáveis que estão disponíveis para todas as etapas do trabalho. Também é possível definir variáveis para todo o fluxo de trabalho ou uma etapa individual. Para obter mais informações, confira env e jobs.<job_id>.steps[*].env.

Quando mais de uma variável de ambiente é definida com o mesmo nome, GitHub usa a variável mais específica. Por exemplo, uma variável de ambiente definida em uma etapa substituirá as variáveis de ambiente do trabalho e do fluxo de trabalho que tenham o mesmo nome enquanto a etapa é executada. Uma variável de ambiente definida para um trabalho substituirá uma variável de fluxo de trabalho com o mesmo nome enquanto o trabalho é executado.

Exemplo de jobs.<job_id>.env

jobs:
  job1:
    env:
      FIRST_NAME: Mona

jobs.<job_id>.defaults

Use jobs.<job_id>.defaults para criar um map das configurações padrão que será aplicado a todas as etapas do trabalho. Você também pode definir as configurações-padrão para todo o fluxo de trabalho. Para obter mais informações, confira defaults.

Quando mais de uma configuração padrão é definida com o mesmo nome, GitHub usa a configuração padrão mais específica. Por exemplo, uma configuração padrão definida em uma tarefa irá substituir uma configuração padrão que tem o mesmo nome definido em um fluxo de trabalho.

jobs.<job_id>.defaults.run

Use jobs.<job_id>.defaults.run para fornecer o shell e o working-directory padrão para todas as etapas run do trabalho. Não são permitidos contexto e expressão nesta seção.

Você pode fornecer as opções shell e working-directory padrão para todas as etapas run de um trabalho. Também pode definir as configurações padrão para run em todo o fluxo de trabalho. Para obter mais informações, confira jobs.defaults.run. Você não pode usar contextos ou expressões nesta palavra-chave.

Quando mais de uma configuração padrão é definida com o mesmo nome, GitHub usa a configuração padrão mais específica. Por exemplo, uma configuração padrão definida em uma tarefa irá substituir uma configuração padrão que tem o mesmo nome definido em um fluxo de trabalho.

Exemplo: definição das opções da etapa run padrão para um trabalho

jobs:
  job1:
    runs-on: ubuntu-latest
    defaults:
      run:
        shell: bash
        working-directory: scripts

jobs.<job_id>.steps

Um trabalho contém uma sequência de tarefas chamada steps. As etapas podem executar comandos, executar trabalhos de configuração ou executar ações no seu repositório, em repositórios públicos, ou ações publicadas em registros do Docker. Nem todas as etapas executam ações, mas todas as ações são executadas como etapas. Cada etapa é executada em seu próprio processo no ambiente do executor, tendo acesso ao espaço de trabalho e ao sistema de arquivos. Como as etapas são executadas em seus próprios processos, as alterações nas variáveis de ambiente não são preservadas entre as etapas. O GitHub fornece etapas integradas para configurar e concluir trabalhos.

Você pode executar quantas etapas quiser, desde que esteja dentro dos limites de uso do fluxo de trabalho. Para obter mais informações, confira "Limites de uso, cobrança e administração" para executores hospedados no GitHub e "Sobre executores auto-hospedados" para saber os limites de uso dos executores auto-hospedados.

Exemplo de jobs.<job_id>.steps

name: Greeting from Mona

on: push

jobs:
  my-job:
    name: My Job
    runs-on: ubuntu-latest
    steps:
      - name: Print a greeting
        env:
          MY_VAR: Hi there! My name is
          FIRST_NAME: Mona
          MIDDLE_NAME: The
          LAST_NAME: Octocat
        run: |
          echo $MY_VAR $FIRST_NAME $MIDDLE_NAME $LAST_NAME.

jobs.<job_id>.steps[*].id

Identificador exclusivo da etapa. Use a id para referenciar a etapa em contextos. Para obter mais informações, confira "Contextos".

jobs.<job_id>.steps[*].if

Use o condicional if para impedir que uma etapa seja executada, a não ser que uma condição seja atendida. Você pode usar qualquer contexto e expressão compatível para criar uma condicional. Para obter mais informações sobre quais contextos têm suporte nessa chave, confira "Disponibilidade de contexto".

Ao usar expressões em um condicional if, você pode omitir a sintaxe de expressão (${{ }}), porque o GitHub avalia automaticamente o condicional if como uma expressão. Para obter mais informações, confira "Expressões".

Exemplo: Usando contextos

Essa etapa só é executada quando o tipo de evento é uma pull_request e a ação do evento é unassigned.

steps:
 - name: My first step
   if: ${{ github.event_name == 'pull_request' && github.event.action == 'unassigned' }}
   run: echo This event is a pull request that had an assignee removed.

Exemplo: Usando funções de verificação de status

A my backup step só é executada quando a etapa anterior de um trabalho falha. Para obter mais informações, confira "Expressões".

steps:
  - name: My first step
    uses: octo-org/action-name@main
  - name: My backup step
    if: ${{ failure() }}
    uses: actions/heroku@1.0.0

Exemplo: Usando segredos

Não é possível referenciar segredos diretamente em condicionais if:. Em vez disso, considere definir segredos como variáveis de ambiente no nível de trabalho e, em seguida, fazer referência às variáveis de ambiente para executar etapas condicionalmente no trabalho.

Se um segredo não for definido, o valor retornado de uma expressão que referencia o segredo (como ${{ secrets.SuperSecret }} no exemplo) será uma cadeia de caracteres vazia.

name: Run a step if a secret has been set
on: push
jobs:
  my-jobname:
    runs-on: ubuntu-latest
    env:
      super_secret: ${{ secrets.SuperSecret }}
    steps:
      - if: ${{ env.super_secret != '' }}
        run: echo 'This step will only run if the secret has a value set.'
      - if: ${{ env.super_secret == '' }}
        run: echo 'This step will only run if the secret does not have a value set.'

Para obter mais informações, confira "Contextos" e "Segredos criptografados."

jobs.<job_id>.steps[*].name

Nome da sua etapa exibido em GitHub.

jobs.<job_id>.steps[*].uses

Seleciona uma ação para executar como parte de uma etapa no trabalho. A ação é uma unidade reutilizável de código. Você pode usar uma ação definida no mesmo repositório do fluxo de trabalho, um repositório público ou em uma imagem publicada de um contêiner do Docker.

É altamente recomendável incluir a versão da ação que você está usando especificando uma referência de Git, SHA ou uma marca do Docker. Se você não especificar uma versão, ela poderá interromper seus fluxos de trabalho ou causar um comportamento inesperado quando o proprietário da ação publicar uma atualização.

• Usar o commit SHA de uma versão de ação lançada é a maneira mais garantida de obter estabilidade e segurança.
• Se a ação publicar marcas de versão principal, você deverá esperar receber correções críticas e patches de segurança enquanto ainda mantém a compatibilidade. Observe que esse comportamento fica a critério do autor da ação.
• Usar o branch-padrão de uma ação pode ser conveniente, mas se alguém lançar uma nova versão principal com uma mudança significativa, seu fluxo de trabalho poderá ter problemas.

Algumas ações exigem entradas que precisam ser definidas com a palavra-chave with. Revise o arquivo README da ação para determinar as entradas obrigatórias.

Ações são arquivos do JavaScript ou contêineres Docker. Se a ação em uso for um contêiner do Docker, você deverá executar o trabalho em um ambiente do Linux. Para obter mais informações, consulte runs-on.

Exemplo: Usando ações de versão

steps:
  # Reference a specific commit
  - uses: actions/checkout@8f4b7f84864484a7bf31766abe9204da3cbe65b3
  # Reference the major version of a release
  - uses: actions/checkout@v3
  # Reference a specific version
  - uses: actions/checkout@v3.2.0
  # Reference a branch
  - uses: actions/checkout@main

Exemplo: Usando uma ação pública

{owner}/{repo}@{ref}

É possível especificar um branch, ref, ou SHA em um repositório público de GitHub.

jobs:
  my_first_job:
    steps:
      - name: My first step
        # Uses the default branch of a public repository
        uses: actions/heroku@main
      - name: My second step
        # Uses a specific version tag of a public repository
        uses: actions/aws@v2.0.1

Exemplo: Usando uma ação pública em um subdiretório

{owner}/{repo}/{path}@{ref}

Subdiretório em um repositório público do GitHub em um branch, ref ou SHA específico.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: actions/aws/ec2@main

Exemplo: Usando uma ação no mesmo repositório que o fluxo de trabalho

./path/to/dir

Caminho para o diretório que contém a ação no repositório do seu fluxo de trabalho. Você deve reservar seu repositório antes de usar a ação.

jobs:
  my_first_job:
    steps:
      - name: Check out repository
        uses: actions/checkout@v3
      - name: Use local my-action
        uses: ./.github/actions/my-action

Exemplo: Usando uma ação do Docker Hub

docker://{image}:{tag}

Uma imagem do Docker publicada no Docker Hub.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: docker://alpine:3.8

Exemplo: Usando uma ação do registro público do Docker

docker://{host}/{image}:{tag}

Imagem Docker em um registro público. Este exemplo usa o Registro de Contêiner do Google em gcr.io.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: docker://gcr.io/cloud-builders/gradle

Exemplo: Usando uma ação dentro de um repositório privado diferente do fluxo de trabalho

Seu fluxo de trabalho deve fazer checkout no repositório privado e referenciar a ação localmente. Gere um personal access token e adicione o token como um segredo criptografado. Para obter mais informações, confira "Criando um token de acesso pessoal" e "Segredos criptografados."

Substitua PERSONAL_ACCESS_TOKEN no exemplo pelo nome do segredo.

jobs:
  my_first_job:
    steps:
      - name: Check out repository
        uses: actions/checkout@v3
        with:
          repository: octocat/my-private-repo
          ref: v1.0
          token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
          path: ./.github/actions/my-private-repo
      - name: Run my action
        uses: ./.github/actions/my-private-repo/my-action

Como alternativa, use um GitHub App em vez de um personal access token para garantir que o fluxo de trabalho continue em execução, mesmo que o proprietário do personal access token saia da organização. Para obter mais informações, confira "Fazer solicitações de API autenticadas com um Aplicativo do GitHub em um fluxo de trabalho do GitHub Actions".

jobs.<job_id>.steps[*].run

Executa programas de linha de comando usando o shell do sistema operacional. Se você não informar um name, o nome da etapa usará como padrão o texto indicado no comando run.

Por padrão, os comandos run usam shells que nao são de login. Você pode escolher um shell diferente e personalizar o shell usado para executar comandos. Para obter mais informações, confira jobs.<job_id>.steps[*].shell.

Cada palavra-chave run representa um novo processo e um shell no ambiente do executor. Ao fornecer comandos de várias linhas, cada linha será executada no mesmo shell. Por exemplo:

• Um comando de linha única:

  - name: Install Dependencies
    run: npm install
  

• Um comando de várias linhas:

  - name: Clean install dependencies and build
    run: |
      npm ci
      npm run build
  

Com a palavra-chave working-directory, é possível especificar o diretório de trabalho do qual o comando será executado.

- name: Clean temp directory
  run: rm -rf *
  working-directory: ./temp

jobs.<job_id>.steps[*].shell

Substitua as configurações padrão do shell no sistema operacional do executor usando a palavra-chave shell. É possível usar palavras-chave shell internas ou definir um conjunto personalizado de opções de shell. O comando do shell que é executado internamente executa um arquivo temporário que contém os comandos especificados na palavra-chave run.

Exemplo: Executando um script usando o bash

steps:
  - name: Display the path
    run: echo $PATH
    shell: bash

Exemplo: execução de um script usando o cmd do Windows

steps:
  - name: Display the path
    run: echo %PATH%
    shell: cmd

Exemplo: Executando um script usando PowerShell Core

steps:
  - name: Display the path
    run: echo ${env:PATH}
    shell: pwsh

Exemplo: Usar o PowerShell Desktop para executar um script

steps:
  - name: Display the path
    run: echo ${env:PATH}
    shell: powershell

Exemplo: Executando um script do Python

steps:
  - name: Display the path
    run: |
      import os
      print(os.environ['PATH'])
    shell: python

Shell personalizado

Você pode definir o valor shell como uma cadeia de caracteres de modelo usando command […options] {0} [..more_options]. O GitHub interpreta a primeira palavra da cadeia de caracteres delimitada por um espaço em branco como o comando e insere o nome do arquivo para o script temporário em {0}.

Por exemplo:

steps:
  - name: Display the environment variables and their values
    run: |
      print %ENV
    shell: perl {0}

O comando usado, perl neste exemplo, precisa ser instalado no executor.

Preferências de ação de erro e códigos de saída

Para palavras-chave de shell integradas, fornecemos os seguintes padrões usados por executores hospedados no GitHub. Você deve seguir estas diretrizes quando executar scripts shell.

• bash/sh:

  • Comportamento rápido de falha usandoset -eo pipefail: essa opção é definida quando shell: bash é explicitamente especificado. Isso não é aplicado por padrão.
  • Você pode ter controle total sobre os parâmetros do shell fornecendo uma string de modelo para as opções do shell. Por exemplo, bash {0}.
  • Shells do tipo sh saem com o código de saída do último comando executado em um script, que também é o comportamento padrão das ações. O executor relatará o status da etapa como falha/êxito com base nesse código de saída.

• powershell/pwsh

  • Comportamento fail-fast quando possível. Para pwsh e o shell interno powershell, prefixaremos $ErrorActionPreference = 'stop' ao conteúdo do script.
  • Prefixamos if ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE } aos scripts do PowerShell para que os status de ação reflitam o último código de saída do script.
  • Os usuários sempre podem recusar o uso do shell interno e fornecer uma opção de shell personalizada como: pwsh -File {0} ou powershell -Command "& '{0}'", dependendo da necessidade.

• cmd

  • Parece não haver uma forma de optar totalmente por um comportamento fail-fast que não seja gravar seu script para verificar cada código de erro e reagir de acordo. Como não podemos fornecer esse comportamento por padrão, você precisa gravá-lo em seu script.
  • cmd.exe sairá com o nível de erro do último programa que executou e retornará o código de erro para o executor. Esse comportamento é internamente consistente com o comportamento anterior de sh e pwsh padrão e é o cmd.exe padrão. Portanto, esse comportamento permanece intacto.

jobs.<job_id>.steps[*].with

Um map dos parâmetros de entrada definidos pela ação. Cada parâmetro de entrada é um par chave/valor. Parâmetros de entrada são definidos como variáveis de ambiente. A variável é precedida por INPUT_ e convertida em letras maiúsculas.

Exemplo de jobs.<job_id>.steps[*].with

Define os três parâmetros de entrada (first_name, middle_name e last_name) definidos pela ação hello_world. Essas variáveis de entrada estarão acessíveis para a ação hello-world como variáveis de ambiente INPUT_FIRST_NAME, INPUT_MIDDLE_NAME e INPUT_LAST_NAME.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: actions/hello_world@main
        with:
          first_name: Mona
          middle_name: The
          last_name: Octocat

jobs.<job_id>.steps[*].with.args

Uma string que define as entradas para um contêiner do Docker. O GitHub transmite os args para o ENTRYPOINT do contêiner quando o contêiner é iniciado. Não há suporte para uma array of strings nesse parâmetro. Um único argumento que inclui espaços deve ser cercado por aspas duplas "".

Exemplo de jobs.<job_id>.steps[*].with.args

steps:
  - name: Explain why this job ran
    uses: octo-org/action-name@main
    with:
      entrypoint: /bin/echo
      args: The ${{ github.event_name }} event triggered this step.

Os args são usados no lugar da instrução CMD em um Dockerfile. Se você usar CMD no Dockerfile, use as diretrizes ordenadas por preferência:

1. Documente os argumentos necessários no README da ação e omita-os da instrução CMD.
2. Use padrões que permitam o uso da ação sem a especificação de args.
3. Se a ação expõe um sinalizador --help ou algo do tipo, use isso como o padrão para que a ação seja documentada automaticamente.

jobs.<job_id>.steps[*].with.entrypoint

Substitui o ENTRYPOINT do Docker no Dockerfile ou define-o se um ainda não foi especificado. Ao contrário da instrução ENTRYPOINT do Docker que tem um shell e um formulário executável, a palavra-chave entrypoint só aceita uma cadeia de caracteres individual que define o executável para execução.

Exemplo de jobs.<job_id>.steps[*].with.entrypoint

steps:
  - name: Run a custom command
    uses: octo-org/action-name@main
    with:
      entrypoint: /a/different/executable

A palavra-chave entrypoint destina-se a ser usada com as ações de contêiner do Docker, mas você também pode usá-la com as ações JavaScript que não definem nenhuma entrada.

jobs.<job_id>.steps[*].env

Define variáveis para etapas a serem usadas no ambiente do executor. Também é possível definir variáveis para todo o fluxo de trabalho ou para um trabalho. Para obter mais informações, confira env e jobs.<job_id>.env.

Quando mais de uma variável de ambiente é definida com o mesmo nome, GitHub usa a variável mais específica. Por exemplo, uma variável de ambiente definida em uma etapa substituirá as variáveis de ambiente do trabalho e do fluxo de trabalho que tenham o mesmo nome enquanto a etapa é executada. Uma variável de ambiente definida para um trabalho substituirá uma variável de fluxo de trabalho com o mesmo nome enquanto o trabalho é executado.

Ações públicas podem especificar variáveis esperadas no arquivo LEIAME. Se você estiver definindo um valor secreto ou confidencial, como uma senha ou um token, deverá definir segredos usando o contexto secrets. Para obter mais informações, confira "Contextos".

Exemplo de jobs.<job_id>.steps[*].env

steps:
  - name: My first action
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      FIRST_NAME: Mona
      LAST_NAME: Octocat

jobs.<job_id>.steps[*].continue-on-error

Impede a falha de um trabalho se uma etapa não funcionar. Defina isso como true para permitir que um trabalho seja aprovado quando houver uma falha nessa etapa.

jobs.<job_id>.steps[*].timeout-minutes

Número máximo de minutos para executar a etapa antes de interromper o processo.

jobs.<job_id>.timeout-minutes

Número máximo de minutos para permitir a execução de um trabalho o antes que o GitHub o cancele automaticamente. Padrão: 360

Se o tempo-limite exceder o tempo limite de execução do trabalho para o executor, o trabalho será cancelado quando o tempo limite de execução for atingido. Para obter mais informações sobre os limites de tempo de execução dos trabalhos, confira "Limites de uso, cobrança e administração" para executores hospedados no GitHub e "Sobre executores auto-hospedados" para saber os limites de uso dos executores auto-hospedados.

jobs.<job_id>.strategy

Com o jobs.<job_id>.strategy você usa uma estratégia de matriz para seus trabalhos. 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 para testar seu código em várias versões de um idioma ou em vários sistemas operacionais. Para obter mais informações, confira "Usando uma matriz para seus trabalhos".

jobs.<job_id>.strategy.matrix

Use jobs.<job_id>.strategy.matrix para definir uma matriz de diferentes configurações de trabalho. Dentro de sua matriz, defina uma ou mais variáveis seguidas por uma matriz de valores. Por exemplo, a matriz a seguir tem uma variável chamada version com o valor [10, 12, 14] e uma variável chamada os com o valor [ubuntu-latest, windows-latest]:

jobs:
  example_matrix:
    strategy:
      matrix:
        version: [10, 12, 14]
        os: [ubuntu-latest, windows-latest]

Um trabalho será executado para cada combinação possível das variáveis. Neste exemplo, o fluxo de trabalho executará seis trabalhos, um para cada combinação das variáveis os e version.

Por padrão, o GitHub Enterprise Server maximizará o número de trabalhos executados em paralelo, dependendo da disponibilidade do executor. A ordem das variáveis na matriz determina a ordem na qual os trabalhos são criados. A primeira variável definida será o primeiro trabalho criado na execução do fluxo de trabalho. Por exemplo, a matriz acima criará os trabalhos na seguinte ordem:

• {version: 10, os: ubuntu-latest}
• {version: 10, os: windows-latest}
• {version: 12, os: ubuntu-latest}
• {version: 12, os: windows-latest}
• {version: 14, os: ubuntu-latest}
• {version: 14, os: windows-latest}

Uma matriz pode gerar 256 tarefas no máximo por execução do fluxo de trabalho. Esse limite se aplica a executores hospedados pelo GitHub Enterprise Servere auto-hospedados.

As variáveis que você define se tornam propriedades no contexto matrix, e você pode referenciar a propriedade em outras áreas do arquivo de fluxo de trabalho. Neste exemplo, você pode usar matrix.version e matrix.os para acessar o valor atual de version e os que o trabalho está usando. Para obter mais informações, confira "Contextos".

Exemplo: usando uma matriz unidimensional

Você pode especificar uma única variável para criar uma matriz unidimensional.

Por exemplo, o fluxo de trabalho a seguir define a variável version com os valores [10, 12, 14]. O fluxo de trabalho executará três trabalhos, um para cada valor na variável. Cada trabalho acessará o valor version por meio do contexto matrix.version e passará o valor como node-version à ação actions/setup-node.

jobs:
  example_matrix:
    strategy:
      matrix:
        version: [10, 12, 14]
    steps:
      - uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.version }}

Exemplo: usando uma matriz multidimensional

Você pode especificar diversas variáveis para criar uma matriz multidimensional. Um trabalho será executado para cada combinação possível das variáveis.

Por exemplo, o fluxo de trabalho a seguir especifica duas variáveis:

• Dois sistemas operacionais especificados na variável os
• Três versões do Node.js especificadas na variável version

O fluxo de trabalho executará seis trabalhos, um para cada combinação entre as variáveis os e version. Cada trabalho definirá o valor runs-on como o valor atual os e passará o valor atual version para a ação actions/setup-node.

jobs:
  example_matrix:
    strategy:
      matrix:
        os: [ubuntu-22.04, ubuntu-20.04]
        version: [10, 12, 14]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.version }}

Exemplo: usar contextos para criar matrizes

Você pode usar contextos para criar matrizes. Para obter mais informações sobre contextos, confira "Contextos".

Por exemplo, o fluxo de trabalho a seguir dispara no evento repository_dispatch e usa informações do conteúdo do evento para criar a matriz. Quando um evento de expedição de repositório é criado com um conteúdo como o abaixo, a variável da matriz version terá um valor de [12, 14, 16]. Para obter mais informações sobre o gatilho repository_dispatch, confira "Eventos que disparam fluxos de trabalho".

{
  "event_type": "test",
  "client_payload": {
    "versions": [12, 14, 16]
  }
}

on:
  repository_dispatch:
    types:
      - test
 
jobs:
  example_matrix:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        version: ${{ github.event.client_payload.versions }}
    steps:
      - uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.version }}

jobs.<job_id>.strategy.matrix.include

Use jobs.<job_id>.strategy.matrix.include para expandir as configurações de matriz existentes ou para adicionar novas configurações. O valor de include é uma lista de objetos.

Para cada objeto na lista include, os pares key:value no objeto serão adicionados a cada uma das combinações de matriz se nenhum dos pares key:value substituir qualquer um dos valores de matriz originais. Se o objeto não puder ser adicionado a nenhuma das combinações de matriz, uma nova combinação de matriz será criada. Observe que os valores de matriz originais não serão substituídos, mas os valores de matriz adicionados podem ser substituídos.

Por exemplo, esta matriz:

strategy:
  matrix:
    fruit: [apple, pear]
    animal: [cat, dog]
    include:
      - color: green
      - color: pink
        animal: cat
      - fruit: apple
        shape: circle
      - fruit: banana
      - fruit: banana
        animal: cat

resultará em seis trabalhos com as seguintes combinações de matriz:

• {fruit: apple, animal: cat, color: pink, shape: circle}
• {fruit: apple, animal: dog, color: green, shape: circle}
• {fruit: pear, animal: cat, color: pink}
• {fruit: pear, animal: dog, color: green}
• {fruit: banana}
• {fruit: banana, animal: cat}

seguindo esta lógica:

• {color: green} será adicionado a todas as combinações de matriz originais porque ele pode ser adicionado sem substituir nenhuma parte das combinações originais.
• {color: pink, animal: cat} adiciona color:pink apenas às combinações de matriz originais que incluem animal: cat. Isso substitui o color: green que foi adicionado pela entrada anterior include.
• O {fruit: apple, shape: circle} adiciona shape: circle apenas às combinações de matriz originais que incluem fruit: apple.
• O {fruit: banana} não pode ser adicionado a nenhuma combinação de matriz original sem substituir um valor, portanto, ele é adicionado como uma combinação de matriz adicional.
• O {fruit: banana, animal: cat} não pode ser adicionado a nenhuma combinação de matriz original sem substituir um valor, portanto, ele é adicionado como uma combinação de matriz adicional. Ele não adiciona à combinação de matriz {fruit: banana} porque essa combinação não era uma das combinações de matriz originais.

Exemplo: expandindo configurações

Por exemplo, o fluxo de trabalho a seguir executará seis trabalhos, um para cada combinação de os e node. Quando o trabalho para o valor os de windows-latest e valor node as execuções 16, uma variável adicional chamada npm com o valor de 6 será incluída no trabalho.

jobs:
  example_matrix:
    strategy:
      matrix:
        os: [windows-latest, ubuntu-latest]
        node: [12, 14, 16]
        include:
          - os: windows-latest
            node: 16
            npm: 6
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node }}
      - if: ${{ matrix.npm }}
        run: npm install -g npm@${{ matrix.npm }}
      - run: npm --version

Exemplo: adicionando configurações

Por exemplo, essa matriz executará dez trabalhos, um para cada combinação de os e version na matriz, além de um trabalho para o valor os de windows-latest e o valor version de 17.

jobs:
  example_matrix:
    strategy:
      matrix:
        os: [macos-latest, windows-latest, ubuntu-latest]
        version: [12, 14, 16]
        include:
          - os: windows-latest
            version: 17

Se você não especificar nenhuma variável de matriz, todas as configurações abaixo de include serão executadas. Por exemplo, o fluxo de trabalho a seguir executaria dois trabalhos, um para cada entrada include. Isso permite que você aproveite a estratégia de matriz sem ter uma matriz totalmente populada.

jobs:
  includes_only:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        include:
          - site: "production"
            datacenter: "site-a"
          - site: "staging"
            datacenter: "site-b"

jobs.<job_id>.strategy.matrix.exclude

Para remover configurações específicas definidas na matriz, use jobs.<job_id>.strategy.matrix.exclude. Uma configuração excluída só precisa ser uma correspondência parcial para que ela seja excluída. Por exemplo, o fluxo de trabalho a seguir executará nove trabalhos: um trabalho para cada uma das 12 configurações, menos o trabalho excluído correspondente {os: macos-latest, version: 12, environment: production}e os dois trabalhos excluídos correspondentes {os: windows-latest, version: 16}.

strategy:
  matrix:
    os: [macos-latest, windows-latest]
    version: [12, 14, 16]
    environment: [staging, production]
    exclude:
      - os: macos-latest
        version: 12
        environment: production
      - os: windows-latest
        version: 16
runs-on: ${{ matrix.os }}

jobs.<job_id>.strategy.fail-fast

Você pode controlar como as falhas de trabalho são tratadas com jobs.<job_id>.strategy.fail-fast e jobs.<job_id>.continue-on-error.

jobs.<job_id>.strategy.fail-fast aplica-se a toda a matriz. Se jobs.<job_id>.strategy.fail-fast estiver definido como true, GitHub Enterprise Server cancelará todos os trabalhos em andamento e enfileirados na matriz se algum trabalho na matriz falhar. Essa propriedade tem como padrão true.

jobs.<job_id>.continue-on-error aplica-se a um único trabalho. Se jobs.<job_id>.continue-on-error for true, outros trabalhos na matriz continuarão em execução mesmo que o trabalho com jobs.<job_id>.continue-on-error: true falhe.

Você não pode usar jobs.<job_id>.strategy.fail-fast e jobs.<job_id>.continue-on-error juntos. Por exemplo, o fluxo de trabalho a seguir iniciará quatro trabalhos. Para cada trabalho, continue-on-error é determinado pelo valor de matrix.experimental. Se algum dos trabalhos com continue-on-error: false falhar, todos os trabalhos em andamento ou enfileirados serão cancelados. Se o trabalho com continue-on-error: true falhar, os outros trabalhos não serão afetados.

jobs:
  test:
    runs-on: ubuntu-latest
    continue-on-error: ${{ matrix.experimental }}
    strategy:
      fail-fast: true
      matrix:
        version: [6, 7, 8]
        experimental: [false]
        include:
          - version: 9
            experimental: true

jobs.<job_id>.strategy.max-parallel

Por padrão, o GitHub Enterprise Server maximizará o número de trabalhos executados em paralelo, dependendo da disponibilidade do executor. Para definir o número máximo de trabalhos que podem ser executados simultaneamente com uma estratégia de trabalho matrix, use jobs.<job_id>.strategy.max-parallel.

Por exemplo, o fluxo de trabalho a seguir executará no máximo dois trabalhos por vez, mesmo que haja executores disponíveis para executar todos os seis trabalhos ao mesmo tempo.

jobs:
  example_matrix:
    strategy:
      max-parallel: 2
      matrix:
        version: [10, 12, 14]
        os: [ubuntu-latest, windows-latest]

jobs.<job_id>.continue-on-error

Impede que ocorra falha na execução de um fluxo de trabalho quando ocorrer uma falha em um trabalho. Defina isso como true para permitir que uma execução de fluxo de trabalho seja aprovada quando houver uma falha nesse trabalho.

Exemplo: Evitando uma falha específica na matriz de trabalho por falha na execução de um fluxo de trabalho

Você pode permitir que as tarefas específicas em uma matriz de tarefas falhem sem que ocorra falha na execução do fluxo de trabalho. Por exemplo, caso deseje permitir apenas um trabalho experimental com o node definido como 15 para falhar sem falhar a execução de fluxo de trabalho.

runs-on: ${{ matrix.os }}
continue-on-error: ${{ matrix.experimental }}
strategy:
  fail-fast: false
  matrix:
    node: [13, 14]
    os: [macos-latest, ubuntu-latest]
    experimental: [false]
    include:
      - node: 15
        os: ubuntu-latest
        experimental: true

jobs.<job_id>.container

Use jobs.<job_id>.container para criar um contêiner e executar as etapas de um trabalho que ainda não especificam um contêiner. Se você tiver etapas que usam ações de script e de contêiner, as ações de contêiner serão executadas como contêineres irmãos na mesma rede e com as mesmas montagens de volume.

Se você não definir um container, todas as etapas serão executadas diretamente no host especificado por runs-on, a menos que uma etapa se refira a uma ação configurada para ser executada em um contêiner.

Exemplo: Executar um trabalho dentro de um contêiner

name: CI
on:
  push:
    branches: [ main ]
jobs:
  container-test-job:
    runs-on: ubuntu-latest
    container:
      image: node:14.16
      env:
        NODE_ENV: development
      ports:
        - 80
      volumes:
        - my_docker_volume:/volume_mount
      options: --cpus 1
    steps:
      - name: Check for dockerenv file
        run: (ls /.dockerenv && echo Found dockerenv) || (echo No dockerenv)

Quando você especifica apenas uma imagem de contêiner, pode omitir a palavra-chave image.

jobs:
  container-test-job:
    runs-on: ubuntu-latest
    container: node:14.16

jobs.<job_id>.container.image

Use jobs.<job_id>.container.image para definir a imagem do Docker a ser usada como o contêiner para executar a ação. O valor pode ser o nome da imagem do Docker Hub ou um nome de registro.

jobs.<job_id>.container.credentials

Se o registro de contêiner da imagem exigir autenticação para efetuar pull da imagem, use jobs.<job_id>.container.credentials para definir um map do username e da password. As credenciais são os mesmos valores que você fornecerá ao comando docker login.

Exemplo: Definindo credenciais para o registro de um contêiner

container:
  image: ghcr.io/owner/image
  credentials:
     username: ${{ github.actor }}
     password: ${{ secrets.github_token }}

jobs.<job_id>.container.env

Use jobs.<job_id>.container.env para definir um map das variáveis de ambiente no contêiner.

jobs.<job_id>.container.ports

Use jobs.<job_id>.container.ports para definir uma array das portas a serem expostas no contêiner.

jobs.<job_id>.container.volumes

Use jobs.<job_id>.container.volumes para definir uma array de volumes para uso do contêiner. É possível usar volumes para compartilhar dados entre serviços ou outras etapas em um trabalho. Você pode especificar volumes de nome Docker, volumes Docker anônimos ou vincular montagens no host.

Para especificar um volume, especifique o caminho de origem e destino:

<source>:<destinationPath>.

<source> é um nome de volume ou um caminho absoluto no computador host, e <destinationPath> é um caminho absoluto no contêiner.

Exemplo: Montando volumes em um contêiner

volumes:
  - my_docker_volume:/volume_mount
  - /data/my_data
  - /source/directory:/destination/directory

jobs.<job_id>.container.options

Use jobs.<job_id>.container.options para configurar opções adicionais de recurso de contêiner do Docker. Para obter uma lista de opções, confira "Opções de docker create".

jobs.<job_id>.services

Usado para hospedar contêineres de serviço para um trabalho em um fluxo de trabalho. Contêineres de serviço são úteis para a criação de bancos de dados ou serviços armazenamento em cache como o Redis. O executor cria automaticamente uma rede do Docker e gerencia o ciclo de vida dos contêineres do serviço.

Se você configurar seu trabalho para ser executado em um contêiner, ou a sua etapa usar ações ao contêiner, você não precisará mapear as portas para acessar o serviço ou a ação. O Docker expõe automaticamente todas as portas entre os contêineres da mesma rede de ponte definida pelo usuário. Você pode fazer referência ao contêiner de serviço diretamente pelo seu nome de host. O nome do host é mapeado automaticamente com o nome da etiqueta que você configurar para o serviço no fluxo de trabalho.

Se você configurar a tarefa para executar diretamente na máquina do executor e sua etapa não usar uma ação de contêiner, você deverá mapear todas as portas de contêiner de serviço do Docker necessárias para o host do Docker (a máquina do executor). Você pode acessar o contêiner de serviço usando host local e a porta mapeada.

Para obter mais informações sobre as diferenças entre os contêineres de serviço de rede, confira "Sobre os contêineres de serviço".

Exemplo: Usando host local

Este exemplo cria dois serviços: nginx e redis. Ao especificar a porta do host do Docker mas não a porta do contêiner, a porta do contêiner será atribuída aleatoriamente a uma porta grátis. O GitHub define a porta do contêiner atribuída no contexto do ${{job.services.<service_name>.ports}}. Neste exemplo, você pode acessar as portas do contêiner de serviço usando os contextos ${{ job.services.nginx.ports['8080'] }} e ${{ job.services.redis.ports['6379'] }}.

services:
  nginx:
    image: nginx
    # Map port 8080 on the Docker host to port 80 on the nginx container
    ports:
      - 8080:80
  redis:
    image: redis
    # Map TCP port 6379 on Docker host to a random free port on the Redis container
    ports:
      - 6379/tcp

jobs.<job_id>.services.<service_id>.image

Imagem Docker a ser usada como contêiner de serviço para executar a ação. O valor pode ser o nome da imagem do Docker Hub ou um nome de registro.

jobs.<job_id>.services.<service_id>.credentials

Se o registro de contêiner da imagem exigir autenticação para efetuar pull da imagem, use jobs.<job_id>.container.credentials para definir um map do username e da password. As credenciais são os mesmos valores que você fornecerá ao comando docker login.

Exemplo de jobs.<job_id>.services.<service_id>.credentials

services:
  myservice1:
    image: ghcr.io/owner/myservice1
    credentials:
      username: ${{ github.actor }}
      password: ${{ secrets.github_token }}
  myservice2:
    image: dockerhub_org/myservice2
    credentials:
      username: ${{ secrets.DOCKER_USER }}
      password: ${{ secrets.DOCKER_PASSWORD }}

jobs.<job_id>.services.<service_id>.env

Define um map das variáveis de ambiente no contêiner de serviço.

jobs.<job_id>.services.<service_id>.ports

Define uma array de portas a serem expostas no contêiner de serviço.

jobs.<job_id>.services.<service_id>.volumes

Define uma array de volumes para uso do contêiner de serviço. É possível usar volumes para compartilhar dados entre serviços ou outras etapas em um trabalho. Você pode especificar volumes de nome Docker, volumes Docker anônimos ou vincular montagens no host.

Para especificar um volume, especifique o caminho de origem e destino:

<source>:<destinationPath>.

<source> é um nome de volume ou um caminho absoluto no computador host, e <destinationPath> é um caminho absoluto no contêiner.

Exemplo de jobs.<job_id>.services.<service_id>.volumes

volumes:
  - my_docker_volume:/volume_mount
  - /data/my_data
  - /source/directory:/destination/directory

jobs.<job_id>.services.<service_id>.options

Opções adicionais de recursos do contêiner Docker. Para obter uma lista de opções, confira "Opções de docker create".

jobs.<job_id>.uses

O local e a versão de um arquivo de fluxo de trabalho reutilizável para ser executado como trabalho. Use 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.

Exemplo de jobs.<job_id>.uses

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

Para obter mais informações, confira "Reutilizar fluxos de trabalho".

jobs.<job_id>.with

Quando um trabalho é usado para chamar um fluxo de trabalho reutilizável, você pode usar with para fornecer um mapa das entradas que são transmitidas para o fluxo de trabalho chamado.

Qualquer entrada que você passe deve corresponder às especificações de entrada definidas no fluxo de trabalho de chamada.

Ao contrário de jobs.<job_id>.steps[*].with, as entradas transmitidas com jobs.<job_id>.with não estarão disponíveis como variáveis de ambiente no fluxo de trabalho chamado. Você pode referenciar as entradas usando o contexto inputs.

Exemplo de jobs.<job_id>.with

jobs:
  call-workflow:
    uses: octo-org/example-repo/.github/workflows/called-workflow.yml@main
    with:
      username: mona

jobs.<job_id>.with.<input_id>

Um par composto de um identificador de string para a entrada e o valor da entrada. O identificador precisa corresponder ao nome de uma entrada definida por on.workflow_call.inputs.<inputs_id> no fluxo de trabalho chamado. O tipo de dados do valor precisa corresponder ao tipo definido por on.workflow_call.inputs.<input_id>.type no fluxo de trabalho chamado.

Contextos de expressão permitidos: github e needs.

jobs.<job_id>.secrets

Quando um trabalho é usado para chamar um fluxo de trabalho reutilizável, você pode usar secrets para fornecer um mapa de segredos que são transmitidos para o fluxo de trabalho chamado.

Qualquer segredo que você passar deve corresponder aos nomes definidos no fluxo de trabalho chamado.

Exemplo de jobs.<job_id>.secrets

jobs:
  call-workflow:
    uses: octo-org/example-repo/.github/workflows/called-workflow.yml@main
    secrets:
      access-token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}

jobs.<job_id>.secrets.inherit

Use a palavra-chave inherit para passar todos os segredos do fluxo de trabalho que faz a chamada para o fluxo de trabalho chamado. Isso inclui todos os segredos aos quais o fluxo de trabalho que faz a chamada tem acesso, ou seja, segredos de organização, repositório e ambiente. A palavra-chave inherit pode ser usada para passar segredos entre repositórios dentro da mesma organização ou entre organizações dentro da mesma empresa.

Exemplo de jobs.<job_id>.secrets.inherit

on:
  workflow_dispatch:

jobs:
  pass-secrets-to-workflow:
    uses: ./.github/workflows/called-workflow.yml
    secrets: inherit

on:
  workflow_call:

jobs:
  pass-secret-to-action:
    runs-on: ubuntu-latest
    steps:
      - name: Use a repo or org secret from the calling workflow.
        run: echo ${{ secrets.CALLING_WORKFLOW_SECRET }}

jobs.<job_id>.secrets.<secret_id>

Um par composto por um identificador string para o segredo e o valor do segredo. O identificador precisa corresponder ao nome de um segredo definido por on.workflow_call.secrets.<secret_id> no fluxo de trabalho chamado.

Contextos de expressão permitidos: github, needs e secrets.

Folha de dados de padrão de filtro

Você pode usar caracteres especiais nos filtros de caminhos, branches e tags.

• *: corresponde a zero ou mais caracteres, mas não corresponde ao caractere /. Por exemplo, Octo* corresponde a Octocat.
• **: corresponde a zero ou mais de qualquer caractere.
• ?: corresponde a zero ou a um dos caracteres anteriores.
• +: corresponde a um ou mais dos caracteres anteriores.
• []: corresponde a um caractere listado entre colchetes ou incluído nos intervalos. Os intervalos só podem incluir a-z, A-Z e 0-9. Por exemplo, o intervalo [0-9a-z] corresponde a qualquer dígito ou letra minúscula. Por exemplo, [CB]at corresponde a Cat ou Bat e [1-2]00 correspondem a 100 e a 200.
• !: no início de um padrão, faz com que ele anule os padrões positivos anteriores. Não tem nenhum significado especial caso não seja o primeiro caractere.

Os caracteres *, [ e ! são caracteres especiais no YAML. Se você iniciar um padrão com *, [ ou !, precisará colocar o padrão entre aspas. Além disso, se você usar uma sequência de fluxo com um padrão contendo [ e/ou ], o padrão deverá estar entre aspas.

# Valid
paths:
  - '**/README.md'

# Invalid - creates a parse error that
# prevents your workflow from running.
paths:
  - **/README.md

# Valid
branches: [ main, 'release/v[0-9].[0-9]' ]

# Invalid - creates a parse error
branches: [ main, release/v[0-9].[0-9] ]

Para obter mais informações sobre a sintaxe de filtro de branch, marca e caminho, confira "on.<push>.<branches|tags>", "on.<pull_request>.<branches|tags>" e "on.<push|pull_request>.paths".

Padrões para corresponder branches e tags

Padrões para corresponder a caminhos de arquivos

Padrões de caminhos devem corresponder ao caminho completo e iniciar a partir da raiz do repositório.