Skip to main content

Workflow syntax for GitHub Actions

In this article

A workflow is a configurable automated process made up of one or more jobs. You must create a YAML file to define your workflow configuration.

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.

About YAML syntax for workflows

Workflow files use YAML syntax, and must have either a .yml or .yaml file extension. Se você não estiver familiarizado com o YAML e quiser saber mais, confira "Aprenda a usar o YAML em Y minutos".

You must store workflow files in the .github/workflows directory of your repository.

name

The name of your workflow. GitHub displays the names of your workflows on your repository's "Actions" tab. If you omit name, GitHub sets it to the workflow file path relative to the root of the repository.

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 ver uma lista dos eventos disponíveis, confira "Eventos que disparam fluxos de trabalho".

Você pode definir um ou vários eventos que possam acionar 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 os respectivos tipos de atividades, 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, 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 a "Folha de referências de padrões de filtro".

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, 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 a "Folha de referências de padrões de filtro".

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 a "Folha de referências de padrões de filtro".

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'

Observação: se um fluxo de trabalho for ignorado devido à filtragem de caminho, à filtragem de branch ou a uma mensagem de commit, as verificações associadas a esse fluxo de trabalho permanecerão em um estado "Pendente". Uma solicitação de pull que exige que essas verificações sejam bem-sucedidas não poderá ser mesclada. Para obter mais informações, confira "Como lidar com verificações ignoradas mas obrigatórias".

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

Observação: se você efetuar push de mais de mil commits ou se o GitHub não gerar a comparação devido a um tempo limite, o fluxo de trabalho sempre será executado.

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 a comparação de branches em solicitações de pull".

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 cron, confira "Eventos que disparam fluxos de trabalho".

on.workflow_call

Use on.workflow_call to define the inputs and outputs for a reusable workflow. You can also map the secrets that are available to the called workflow. For more information on reusable workflows, see "Reusing workflows."

on.workflow_call.inputs

When using the workflow_call keyword, you can optionally specify inputs that are passed to the called workflow from the caller workflow. For more information about the workflow_call keyword, see "Events that trigger workflows."

In addition to the standard input parameters that are available, on.workflow_call.inputs requires a type parameter. For more information, see on.workflow_call.inputs.<input_id>.type.

If a default parameter is not set, the default value of the input is false for a boolean, 0 for a number, and "" for a string.

Within the called workflow, you can use the inputs context to refer to an input.

If a caller workflow passes an input that is not specified in the called workflow, this results in an error.

Example

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

For more information, see "Reusing workflows."

on.workflow_call.inputs.<input_id>.type

Required if input is defined for the on.workflow_call keyword. The value of this parameter is a string specifying the data type of the input. This must be one of: boolean, number, or string.

on.workflow_call.outputs

A map of outputs for a called workflow. Called workflow outputs are available to all downstream jobs in the caller workflow. Each output has an identifier, an optional description, and a value. The value must be set to the value of an output from a job within the called workflow.

In the example below, two outputs are defined for this reusable workflow: workflow_output1 and workflow_output2. These are mapped to outputs called job_output1 and job_output2, both from a job called my_job.

Example

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

For information on how to reference a job output, see jobs.<job_id>.outputs. For more information, see "Reusing workflows."

on.workflow_call.secrets

A map of the secrets that can be used in the called workflow.

Within the called workflow, you can use the secrets context to refer to a secret.

If a caller workflow passes a secret that is not specified in the called workflow, this results in an error.

Example

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:
      - name: Pass the received secret to an action
        uses: ./.github/actions/my-action
        with:
          token: ${{ secrets.access-token }}

on.workflow_call.secrets.<secret_id>

A string identifier to associate with the secret.

on.workflow_call.secrets.<secret_id>.required

A boolean specifying whether the secret must be supplied.

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 a "Folha de referências de padrões de filtro".

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

When using the workflow_dispatch event, you can optionally specify inputs that are passed to the workflow.

The triggered workflow receives the inputs in the github.event.inputs context. For more information, see "Contexts."

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:  ${{ github.event.inputs.print_tags == 'true' }} 
    steps:
      - name: Print the input tag to STDOUT
        run: echo  The tags are ${{ github.event.inputs.tags }} 

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 em um fluxo de trabalho".

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 "[Como gerenciar as configurações do GitHub Actions de um repositório](/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

A map of environment variables that are available to the steps of all jobs in the workflow. You can also set environment variables that are only available to the steps of a single job or to a single step. For more information, see jobs.<job_id>.env and jobs.<job_id>.steps[*].env.

Variables in the env map cannot be defined in terms of other variables in the map.

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

Example

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 e cobrança" para executores hospedados no GitHub e "Sobre os 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 "Trabalhos de fluxo de trabalho".

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 em um fluxo de trabalho".

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 "[Como gerenciar as configurações do GitHub Actions de um repositório](/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, 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 se aplicará a todos os trabalhos na cadeia de dependência do ponto de falha 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.

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.

YAML
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:

Imagem do executor Rótulo de fluxo de trabalho YAML Observações
Windows Server 2022 windows-latest ou windows-2022 Atualmente, o rótulo windows-latest usa a imagem do executor do Windows Server 2022.
Windows Server 2019 windows-2019
Ubuntu 22.04 ubuntu-22.04
Ubuntu 20.04 ubuntu-latest ou ubuntu-20.04 Neste momento, o rótulo ubuntu-latest está fazendo a transição para a imagem do executor do Ubuntu 22.04. Durante a transição, o rótulo pode se referir à imagem do executor para Ubuntu 20.04 ou 22.04. Para obter mais informações, confira esta postagem no blog GitHub.
Ubuntu 18.04 [preterido] ubuntu-18.04 Migre para ubuntu-20.04 ou ubuntu-22.04. Para saber mais, confira esta postagem no blog do GitHub.
macOS Monterey 12 macos-12
macOS Big Sur 11 macos-latest ou macos-11 Neste momento, o rótulo macos-latest está fazendo a transição para a imagem do executor de Monterey 12 no macOS. Durante a transição, o rótulo pode se referir à imagem do executor para macOS 11 ou 12. Para obter mais informações, confira esta postagem no blog GitHub.
macOS Catalina 10.15 [preterido] macos-10.15 Migre para macOS-11 ou macOS-12. Para saber mais, confira esta postagem no blog do GitHub.

Observação: as imagens do executor -latest são as imagens estáveis mais recentes fornecidas pelo GitHub e talvez não seja a versão mais recente do sistema operacional disponível do fornecedor do sistema operacional.

Aviso: as imagens beta e preteridas são fornecidas "no estado em que se encontram", "com todas as falhas" e "conforme disponível" e são excluídas do contrato de nível de serviço e da garantia. As imagens beta podem não ser cobertas pelo atendimento ao cliente.

Exemplo: Especificar um sistema operacional

runs-on: ubuntu-latest

Para obter mais informações, confira "Sobre os 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 "Como usar 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 "Como usar 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 "Implantações".

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

Observação: quando a simultaneidade é especificada no nível do trabalho, a ordem não é garantida para execuções ou trabalhos que são colocados na fila em intervalos de cinco minutos com relação um ao outro.

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

You can use jobs.<job_id>.outputs to create a map of outputs for a job. Job outputs are available to all downstream jobs that depend on this job. For more information on defining job dependencies, see 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.

Job outputs containing expressions are evaluated on the runner at the end of each job. Outputs containing secrets are redacted on the runner and not sent to GitHub Actions.

To use job outputs in a dependent job, you can use the needs context. For more information, see "Contexts."

Example: Defining outputs for a job

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:
      - run: echo ${{needs.job1.outputs.output1}} ${{needs.job1.outputs.output2}}

jobs.<job_id>.env

A map of environment variables that are available to all steps in the job. You can also set environment variables for the entire workflow or an individual step. For more information, see env and jobs.<job_id>.steps[*].env.

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

Example

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

A job contains a sequence of tasks called steps. Steps can run commands, run setup tasks, or run an action in your repository, a public repository, or an action published in a Docker registry. Not all steps run actions, but all actions run as a step. Each step runs in its own process in the runner environment and has access to the workspace and filesystem. Because steps run in their own process, changes to environment variables are not preserved between steps. GitHub provides built-in steps to set up and complete a job.

You can run an unlimited number of steps as long as you are within the workflow usage limits. For more information, see "Usage limits and billing" for GitHub-hosted runners and "About self-hosted runners" for self-hosted runner usage limits.

Example

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

A unique identifier for the step. You can use the id to reference the step in contexts. For more information, see "Contexts."

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

You can use the if conditional to prevent a step from running unless a condition is met. You can use any supported context and expression to create a conditional.

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. For more information, see "Expressions."

Example: Using contexts

This step only runs when the event type is a pull_request and the event action is 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.

Example: Using status check functions

The my backup step only runs when the previous step of a job fails. For more information, see "Expressions."

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

Example: Using secrets

Secrets cannot be directly referenced in if: conditionals. Instead, consider setting secrets as job-level environment variables, then referencing the environment variables to conditionally run steps in the job.

If a secret has not been set, the return value of an expression referencing the secret (such as ${{ secrets.SuperSecret }} in the example) will be an empty string.

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

For more information, see "Context availability" and "Encrypted secrets."

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

A name for your step to display on GitHub.

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

Selects an action to run as part of a step in your job. An action is a reusable unit of code. You can use an action defined in the same repository as the workflow, a public repository, or in a published Docker container image.

We strongly recommend that you include the version of the action you are using by specifying a Git ref, SHA, or Docker tag. If you don't specify a version, it could break your workflows or cause unexpected behavior when the action owner publishes an update.

  • Using the commit SHA of a released action version is the safest for stability and security.
  • If the action publishes major version tags, you should expect to receive critical fixes and security patches while still retaining compatibility. Note that this behavior is at the discretion of the action's author.
  • Using the default branch of an action may be convenient, but if someone releases a new major version with a breaking change, your workflow could break.

Some actions require inputs that you must set using the with keyword. Review the action's README file to determine the inputs required.

Actions are either JavaScript files or Docker containers. If the action you're using is a Docker container you must run the job in a Linux environment. For more details, see runs-on.

Example: Using versioned actions

steps:
  # Reference a specific commit
  - uses: actions/checkout@a81bbbf8298c0fa03ea29cdc473d45769f953675
  # 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

Example: Using a public action

{owner}/{repo}@{ref}

You can specify a branch, ref, or SHA in a public GitHub repository.

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

Example: Using a public action in a subdirectory

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

A subdirectory in a public GitHub repository at a specific branch, ref, or SHA.

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

Example: Using an action in the same repository as the workflow

./path/to/dir

The path to the directory that contains the action in your workflow's repository. You must check out your repository before using the action.

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

Example: Using a Docker Hub action

docker://{image}:{tag}

A Docker image published on Docker Hub.

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

Example: Using a Docker public registry action

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

A Docker image in a public registry. This example uses the Google Container Registry at gcr.io.

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

Example: Using an action inside a different private repository than the workflow

Your workflow must checkout the private repository and reference the action locally. Generate a personal access token and add the token as an encrypted secret. For more information, see "Creating a personal access token" and "Encrypted secrets."

Replace PERSONAL_ACCESS_TOKEN in the example with the name of your secret.

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

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

Runs command-line programs using the operating system's shell. If you do not provide a name, the step name will default to the text specified in the run command.

Commands run using non-login shells by default. You can choose a different shell and customize the shell used to run commands. For more information, see jobs.<job_id>.steps[*].shell.

Each run keyword represents a new process and shell in the runner environment. When you provide multi-line commands, each line runs in the same shell. For example:

  • A single-line command:

    - name: Install Dependencies
      run: npm install
    
  • A multi-line command:

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

Using the working-directory keyword, you can specify the working directory of where to run the command.

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

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

You can override the default shell settings in the runner's operating system using the shell keyword. You can use built-in shell keywords, or you can define a custom set of shell options. The shell command that is run internally executes a temporary file that contains the commands specified in the run keyword.

Supported platformshell parameterDescriptionCommand run internally
Linux / macOSunspecifiedThe default shell on non-Windows platforms. Note that this runs a different command to when bash is specified explicitly. If bash is not found in the path, this is treated as sh.bash -e {0}
AllbashThe default shell on non-Windows platforms with a fallback to sh. When specifying a bash shell on Windows, the bash shell included with Git for Windows is used.bash --noprofile --norc -eo pipefail {0}
AllpwshThe PowerShell Core. GitHub appends the extension .ps1 to your script name.pwsh -command ". '{0}'"
AllpythonExecutes the python command.python {0}
Linux / macOSshThe fallback behavior for non-Windows platforms if no shell is provided and bash is not found in the path.sh -e {0}
WindowscmdGitHub appends the extension .cmd to your script name and substitutes for {0}.%ComSpec% /D /E:ON /V:OFF /S /C "CALL "{0}"".
WindowspwshThis is the default shell used on Windows. The PowerShell Core. GitHub appends the extension .ps1 to your script name. If your self-hosted Windows runner does not have PowerShell Core installed, then PowerShell Desktop is used instead.pwsh -command ". '{0}'".
WindowspowershellThe PowerShell Desktop. GitHub appends the extension .ps1 to your script name.powershell -command ". '{0}'".

Example: Running a script using bash

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

Example: Running a script using Windows cmd

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

Example: Running a script using PowerShell Core

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

Example: Using PowerShell Desktop to run a script

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

Example: Running a python script

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

Custom shell

You can set the shell value to a template string using command […options] {0} [..more_options]. GitHub interprets the first whitespace-delimited word of the string as the command, and inserts the file name for the temporary script at {0}.

For example:

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

The command used, perl in this example, must be installed on the runner.

Exit codes and error action preference

For built-in shell keywords, we provide the following defaults that are executed by GitHub-hosted runners. You should use these guidelines when running shell scripts.

  • bash/sh:

    • Fail-fast behavior using set -eo pipefail: This option is set when shell: bash is explicitly specified. It is not applied by default.
    • You can take full control over shell parameters by providing a template string to the shell options. For example, bash {0}.
    • sh-like shells exit with the exit code of the last command executed in a script, which is also the default behavior for actions. The runner will report the status of the step as fail/succeed based on this exit code.
  • powershell/pwsh

    • Fail-fast behavior when possible. For pwsh and powershell built-in shell, we will prepend $ErrorActionPreference = 'stop' to script contents.
    • We append if ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE } to powershell scripts so action statuses reflect the script's last exit code.
    • Users can always opt out by not using the built-in shell, and providing a custom shell option like: pwsh -File {0}, or powershell -Command "& '{0}'", depending on need.
  • cmd

    • There doesn't seem to be a way to fully opt into fail-fast behavior other than writing your script to check each error code and respond accordingly. Because we can't actually provide that behavior by default, you need to write this behavior into your script.
    • cmd.exe will exit with the error level of the last program it executed, and it will return the error code to the runner. This behavior is internally consistent with the previous sh and pwsh default behavior and is the cmd.exe default, so this behavior remains intact.

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

A map of the input parameters defined by the action. Each input parameter is a key/value pair. Input parameters are set as environment variables. The variable is prefixed with INPUT_ and converted to upper case.

Example

Defines the three input parameters (first_name, middle_name, and last_name) defined by the hello_world action. These input variables will be accessible to the hello-world action as INPUT_FIRST_NAME, INPUT_MIDDLE_NAME, and INPUT_LAST_NAME environment variables.

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

A string that defines the inputs for a Docker container. GitHub passes the args to the container's ENTRYPOINT when the container starts up. An array of strings is not supported by this parameter.

Example

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.

The args are used in place of the CMD instruction in a Dockerfile. If you use CMD in your Dockerfile, use the guidelines ordered by preference:

  1. Document required arguments in the action's README and omit them from the CMD instruction.
  2. Use defaults that allow using the action without specifying any args.
  3. If the action exposes a --help flag, or something similar, use that as the default to make your action self-documenting.

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

Overrides the Docker ENTRYPOINT in the Dockerfile, or sets it if one wasn't already specified. Unlike the Docker ENTRYPOINT instruction which has a shell and exec form, entrypoint keyword accepts only a single string defining the executable to be run.

Example

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

The entrypoint keyword is meant to be used with Docker container actions, but you can also use it with JavaScript actions that don't define any inputs.

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

Sets environment variables for steps to use in the runner environment. You can also set environment variables for the entire workflow or a job. For more information, see env and jobs.<job_id>.env.

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

Public actions may specify expected environment variables in the README file. If you are setting a secret in an environment variable, you must set secrets using the secrets context. For more information, see "Using environment variables" and "Contexts."

Example

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

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

Prevents a job from failing when a step fails. Set to true to allow a job to pass when this step fails.

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

The maximum number of minutes to run the step before killing the process.

jobs.<job_id>.timeout-minutes

The maximum number of minutes to let a job run before GitHub automatically cancels it. Default: 360

If the timeout exceeds the job execution time limit for the runner, the job will be canceled when the execution time limit is met instead. For more information about job execution time limits, see "Usage limits and billing" for GitHub-hosted runners and "About self-hosted runners" for self-hosted runner usage limits.

Note: O GITHUB_TOKEN expira quando um trabalho é concluído ou após, no máximo, 24 horas. For self-hosted runners, the token may be the limiting factor if the job timeout is greater than 24 hours. For more information on the GITHUB_TOKEN, see "About the GITHUB_TOKEN secret."

jobs.<job_id>.strategy

Use jobs.<job_id>.strategy to use a matrix strategy for your jobs. 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. For more information, see "Using a matrix for your jobs."

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

Example: Using a single-dimension matrix

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

Example: Using a multi-dimension matrix

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

Example: Using contexts to create matrices

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.

Example: Expanding configurations

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

Example: Adding configurations

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

Observação: todas as combinações de include são processadas após exclude. Isso permite que você use include para adicionar combinações anteriores que já foram excluídas.

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

Prevents a workflow run from failing when a job fails. Set to true to allow a workflow run to pass when this job fails.

Example: Preventing a specific failing matrix job from failing a workflow run

You can allow specific jobs in a job matrix to fail without failing the workflow run. For example, if you wanted to only allow an experimental job with node set to 15 to fail without failing the workflow run.

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

Observação: se os fluxos de trabalho usarem ações de contêiner do Docker, contêineres de trabalho ou contêineres de serviço, você precisará usar um executor do Linux:

  • Se você estiver usando executores hospedados em GitHub, você deverá usar um executor do Ubuntu.
  • Se você estiver usando executores auto-hospedados, você deve usar uma máquina Linux, pois seu executor e o Docker precisam ser instalados.

Use jobs.<job_id>.container to create a container to run any steps in a job that don't already specify a container. If you have steps that use both script and container actions, the container actions will run as sibling containers on the same network with the same volume mounts.

If you do not set a container, all steps will run directly on the host specified by runs-on unless a step refers to an action configured to run in a container.

Note: The default shell for run steps inside a container is sh instead of bash. This can be overridden with jobs.<job_id>.defaults.run or jobs.<job_id>.steps[*].shell.

Example: Running a job within a container

YAML
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)

When you only specify a container image, you can omit the image keyword.

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

Aviso: não há suporte para a opção --network.

jobs.<job_id>.services

Observação: se os fluxos de trabalho usarem ações de contêiner do Docker, contêineres de trabalho ou contêineres de serviço, você precisará usar um executor do Linux:

  • Se você estiver usando executores hospedados em GitHub, você deverá usar um executor do Ubuntu.
  • Se você estiver usando executores auto-hospedados, você deve usar uma máquina Linux, pois seu executor e o Docker precisam ser instalados.

Used to host service containers for a job in a workflow. Service containers are useful for creating databases or cache services like Redis. The runner automatically creates a Docker network and manages the life cycle of the service containers.

If you configure your job to run in a container, or your step uses container actions, you don't need to map ports to access the service or action. Docker automatically exposes all ports between containers on the same Docker user-defined bridge network. You can directly reference the service container by its hostname. The hostname is automatically mapped to the label name you configure for the service in the workflow.

If you configure the job to run directly on the runner machine and your step doesn't use a container action, you must map any required Docker service container ports to the Docker host (the runner machine). You can access the service container using localhost and the mapped port.

For more information about the differences between networking service containers, see "About service containers."

Example: Using localhost

This example creates two services: nginx and redis. When you specify the Docker host port but not the container port, the container port is randomly assigned to a free port. GitHub sets the assigned container port in the ${{job.services.<service_name>.ports}} context. In this example, you can access the service container ports using the ${{ job.services.nginx.ports['8080'] }} and ${{ job.services.redis.ports['6379'] }} contexts.

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

The Docker image to use as the service container to run the action. The value can be the Docker Hub image name or a registry name.

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.

Example

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

Sets a map of environment variables in the service container.

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

Sets an array of ports to expose on the service container.

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

Sets an array of volumes for the service container to use. You can use volumes to share data between services or other steps in a job. You can specify named Docker volumes, anonymous Docker volumes, or bind mounts on the host.

To specify a volume, you specify the source and destination path:

<source>:<destinationPath>.

The <source> is a volume name or an absolute path on the host machine, and <destinationPath> is an absolute path in the container.

Example

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

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

Additional Docker container resource options. For a list of options, see "docker create options."

Warning: The --network option is not supported.

jobs.<job_id>.uses

The location and version of a reusable workflow file to run as a job. Use one of the following syntaxes:

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

{ref} can be a SHA, a release tag, or a branch name. Using the commit SHA is the safest for stability and security. For more information, see "Security hardening for GitHub Actions." If you use the second syntax option (without {owner}/{repo} and @{ref}) the called workflow is from the same commit as the caller workflow.

Example

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

For more information, see "Reusing workflows."

jobs.<job_id>.with

When a job is used to call a reusable workflow, you can use with to provide a map of inputs that are passed to the called workflow.

Any inputs that you pass must match the input specifications defined in the called workflow.

Unlike jobs.<job_id>.steps[*].with, the inputs you pass with jobs.<job_id>.with are not be available as environment variables in the called workflow. Instead, you can reference the inputs by using the inputs context.

Example

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

jobs.<job_id>.with.<input_id>

A pair consisting of a string identifier for the input and the value of the input. The identifier must match the name of an input defined by on.workflow_call.inputs.<inputs_id> in the called workflow. The data type of the value must match the type defined by on.workflow_call.inputs.<input_id>.type in the called workflow.

Allowed expression contexts: github, and needs.

jobs.<job_id>.secrets

When a job is used to call a reusable workflow, you can use secrets to provide a map of secrets that are passed to the called workflow.

Any secrets that you pass must match the names defined in the called workflow.

Example

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

A pair consisting of a string identifier for the secret and the value of the secret. The identifier must match the name of a secret defined by on.workflow_call.secrets.<secret_id> in the called workflow.

Allowed expression contexts: github, needs, and secrets.

Filter pattern cheat sheet

You can use special characters in path, branch, and tag filters.

  • *: Matches zero or more characters, but does not match the / character. For example, Octo* matches Octocat.
  • **: Matches zero or more of any character.
  • ?: Matches zero or one of the preceding character.
  • +: Matches one or more of the preceding character.
  • [] Matches one character listed in the brackets or included in ranges. Ranges can only include a-z, A-Z, and 0-9. For example, the range[0-9a-z] matches any digit or lowercase letter. For example, [CB]at matches Cat or Bat and [1-2]00 matches 100 and 200.
  • !: At the start of a pattern makes it negate previous positive patterns. It has no special meaning if not the first character.

The characters *, [, and ! are special characters in YAML. If you start a pattern with *, [, or !, you must enclose the pattern in quotes. Also, if you use a flow sequence with a pattern containing [ and/or ], the pattern must be enclosed in quotes.

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

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

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

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

For more information about branch, tag, and path filter syntax, see "on.<push>.<branches|tags>", "on.<pull_request>.<branches|tags>", and "on.<push|pull_request>.paths."

Patterns to match branches and tags

PatternDescriptionExample matches
feature/*The * wildcard matches any character, but does not match slash (/).feature/my-branch

feature/your-branch
feature/**The ** wildcard matches any character including slash (/) in branch and tag names.feature/beta-a/my-branch

feature/your-branch

feature/mona/the/octocat
main

releases/mona-the-octocat
Matches the exact name of a branch or tag name.main

releases/mona-the-octocat
'*'Matches all branch and tag names that don't contain a slash (/). The * character is a special character in YAML. When you start a pattern with *, you must use quotes.main

releases
'**'Matches all branch and tag names. This is the default behavior when you don't use a branches or tags filter.all/the/branches

every/tag
'*feature'The * character is a special character in YAML. When you start a pattern with *, you must use quotes.mona-feature

feature

ver-10-feature
v2*Matches branch and tag names that start with v2.v2

v2.0

v2.9
v[12].[0-9]+.[0-9]+Matches all semantic versioning branches and tags with major version 1 or 2.v1.10.1

v2.0.0

Patterns to match file paths

Path patterns must match the whole path, and start from the repository's root.

PatternDescription of matchesExample matches
'*'The * wildcard matches any character, but does not match slash (/). The * character is a special character in YAML. When you start a pattern with *, you must use quotes.README.md

server.rb
'*.jsx?'The ? character matches zero or one of the preceding character.page.js

page.jsx
'**'The ** wildcard matches any character including slash (/). This is the default behavior when you don't use a path filter.all/the/files.md
'*.js'The * wildcard matches any character, but does not match slash (/). Matches all .js files at the root of the repository.app.js

index.js
'**.js'Matches all .js files in the repository.index.js

js/index.js

src/js/app.js
docs/*All files within the root of the docs directory, at the root of the repository.docs/README.md

docs/file.txt
docs/**Any files in the /docs directory at the root of the repository.docs/README.md

docs/mona/octocat.txt
docs/**/*.mdA file with a .md suffix anywhere in the docs directory.docs/README.md

docs/mona/hello-world.md

docs/a/markdown/file.md
'**/docs/**'Any files in a docs directory anywhere in the repository.docs/hello.md

dir/docs/my-file.txt

space/docs/plan/space.doc
'**/README.md'A README.md file anywhere in the repository.README.md

js/README.md
'**/*src/**'Any file in a folder with a src suffix anywhere in the repository.a/src/app.js

my-src/code/js/app.js
'**/*-post.md'A file with the suffix -post.md anywhere in the repository.my-post.md

path/their-post.md
'**/migrate-*.sql'A file with the prefix migrate- and suffix .sql anywhere in the repository.migrate-10909.sql

db/migrate-v1.0.sql

db/sept/migrate-v1.sql
*.md

!README.md
Using an exclamation mark (!) in front of a pattern negates it. When a file matches a pattern and also matches a negative pattern defined later in the file, the file will not be included.hello.md

Does not match

README.md

docs/hello.md
*.md

!README.md

README*
Patterns are checked sequentially. A pattern that negates a previous pattern will re-include file paths.hello.md

README.md

README.doc