Skip to main content
Publicamos atualizações frequentes em nossa documentação, e a tradução desta página ainda pode estar em andamento. Para obter as informações mais recentes, acesse a documentação em inglês. Se houver problemas com a tradução desta página, entre em contato conosco.

Sintaxe de fluxo de trabalho para o GitHub Actions

Neste artigo

Um fluxo de trabalho é um processo automatizado configurável constituído de um ou mais trabalhos. Você deve criar um arquivo YAML para definir a configuração do seu fluxo de trabalho.

Observação: Executores hospedados em GitHub não são atualmente compatíveis com GitHub Enterprise Server. Você pode ver mais informações sobre suporte futuro planejado no Itinerário público do GitHub.

Sobre sintaxe YAML para fluxos de trabalho

Arquivos de fluxo de trabalho usam sintaxe YAML e devem ter uma extensão de arquivo .yml ou .yaml. Se você é novo no YAML e deseja aprender mais, consulte "Aprenda YAML em Y minutes".

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

name

Nome do fluxo de trabalho. O GitHub exibe os nomes dos fluxos de trabalho na página de ações do repositório. Se você omitir o nome, o GitHub irá defini-lo como o caminho do arquivo do fluxo de trabalho relativo à raiz do repositório.

on

Para acionar automaticamente um fluxo de trabalho, use on para definir quais eventos podem fazer com que o fluxo de trabalho seja executado. Para obter uma lista de eventos disponíveis, consulte "Eventos que acionam 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. Estas opções são descritas nas seguintes seções.

Usando um evento único

Por exemplo, um fluxo de trabalho com o valor on a seguir será executado quando um push for feito para qualquer branch do 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 bifurcar o 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 do evento que acionará a execução de um fluxo de trabalho.

Por exemplo, o evento issue_comment tem os tipos de atividade criado, editado e excluído. Se o seu fluxo de trabalho for acionado no evento etiqueta, ele será executado sempre que uma etiqueta for criada, editada ou excluída. Se você especificar o tipo de atividade criado para o evento etiqueta, seu fluxo de trabalho será executado quando uma etiqueta for criada, mas não quando uma etiqueta for editada ou excluída.

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:
  issue:
    types:
      - opened
      - labeled

Para obter mais informações sobre cada evento e seus tipos de atividades, consulte "Eventos que acionam 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 de branches que faz com que o fluxo de trabalho seja executado apenas quando um push para um branch que corresponde ao filtro de branches ocorre, ao invés de quando qualquer push ocorre.

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 anexar dois pontos (:) a todos os eventos, incluindo eventos sem configuração.

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

  • Uma etiqueta foi criada
  • Um push é feito noo branch principal do 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 acionará a execução de um fluxo de trabalho. A maioria dos eventos GitHub são acionados por mais de um tipo de atividade. Por exemplo, a etiqueta é acionada quando uma etiqueta é criada, editada ou excluída. A palavra-chave types (tipos) permite que você limite a atividade que faz com que o fluxo de trabalho seja executado. Quando somente um tipo de atividade aciona um evento de webhook, a palavra-chave types (tipos) é desnecessária.

É possível usar um array de types (tipos) de evento. Para obter mais informações sobre cada evento e seus tipos de atividades, consulte "Eventos que acionam fluxos de trabalho".

on:
  label:
    types: [created, edited]

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

Ao usar os eventos de pull_request e pull_request_target, é possível configurar um fluxo de trabalho para que seja executado somente para pull requests que apontem para branches específicos.

Use o filtro branches quando você deseja incluir padrões de nomes de branches ou quando você deseja incluir e excluir padrões de nomes de branches. Use o filtro branches-ignore quando você deseja excluir apenas padrões de nome de branches. Você não pode usar ambos os filtros branches e branches-ignore para o mesmo evento em um fluxo de trabalho.

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

As palavras-chave branches e branches-ignore aceitam padrões do glob que usam caracteres como *, **, +, ?, ! e outros para combinar com mais de um nome de branch. Se um nome contiver qualquer um desses caracteres e você quiser uma correspondência literal, você deverá escapar de cada um desses caracteres especiais com \. Para obter mais informações sobre padrões de glob, consulte a "Folha de informações para filtrar padrões".

Exemplo: Incluindo branches

Os padrões definidos em branches são avaliados com base no nome do ref do Git. Por exemplo, o fluxo de trabalho a seguir seria executado sempre que houvesse um evento pull_request para um direcionamento de pull request:

  • Uma branch denominado principal (refs/heads/main)
  • Uma branch denominado 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 corresponde ao padrão branches-ignore, o fluxo de trabalho não será executado. Os padrões definidos em branches são avaliados com base no nome do ref do Git. Por exemplo, o fluxo de trabalho a seguir seria executado sempre que houver um evento pull_request, a menos que o pull request esteja apontando para:

  • Uma branch denominado mona/octocat (refs/heads/mona/octocat)
  • Uma branch cujo nome corresponda 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

Você não pode usar branches e branches-ignore para filtrar o mesmo evento em um único fluxo de trabalho. Se você deseja incluir e excluir padrões de branch para um único evento, use o filtro branches junto com o caractere ! para indicar quais branches devem ser excluídos.

Se você definir um branch com o caractere !, você deverá definir pelo menos um branch sem o caractere !. Se você deseja apenas excluir branches, use branches-ignore.

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

  • Um padrão negativo (precedido por !) depois de uma correspondência positiva excluirá o Git ref.
  • 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 pull requests que apontem para releases/10 ou releases/beta/mona, mas não para pull requests que apontam para releases/10-alpha ou releases/beta/3-alpha porque o padrão negativo !releases/**-alpha 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 branches ou tags específicos.

Use o filtro branches quando você deseja incluir padrões de nomes de branches ou quando você deseja incluir e excluir padrões de nomes de branches. Use o filtro branches-ignore quando você deseja excluir apenas padrões de nome de branches. Você não pode usar ambos os filtros branches e branches-ignore para o mesmo evento em um fluxo de trabalho.

Use o filtro tags quando você deseja incluir padrões de nomes de tags ou quando você deseja incluir e excluir padrões de nomes de tags. Use o filtro tags-ignore quando você deseja excluir apenas padrões de nome de tag. 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 o ref indefinido do Git. Se você não definir tags/tags-ignore ou branches/branches-ignore, o fluxo de trabalho será executado para eventos que afetam branches ou tags. Se você definir os branches/branches-ignore e caminhos, o fluxo de trabalho só será executado quando ambos os filtros forem satisfeitos.

As palavras-chave branches, branches-ignore, tags, and tags-ignore aceitam padrões do glob que usam caracteres como *, **, +, ?, ! e outros para corresponder a mais de um nome do branch ou tag. Se um nome contiver qualquer um desses caracteres e você quiser uma correspondência literal, você deverá escapar de cada um desses caracteres especiais com \. Para obter mais informações sobre padrões de glob, consulte a "Folha de informações para filtrar padrões".

Exemplo: Incluindo branches e tags

Os padrões definidos nos branches e tags são avaliados relativamente ao nome do Git ref. Por exemplo, o fluxo de trabalho seguinte seria executado sempre que houver um evento push para:

  • Uma branch denominado principal (refs/heads/main)
  • Uma branch denominado mona/octocat (refs/heads/mona/octocat)
  • Um branch cujo nome começa com releases/, como releases/10 (refs/heads/releases/10)
  • Uma tag denominada v2 (refs/tags/v2)
  • Uma tag 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 corresponde ao padrão de branches-ignore ou tags-ignore o fluxo de trabalho não será executado. Os padrões definidos nos branches e tags são avaliados relativamente ao nome do Git ref. Por exemplo, o fluxo de trabalho a seguir seria executado a cada evento de push, a menos que o evento push seja para:

  • Uma branch denominado mona/octocat (refs/heads/mona/octocat)
  • Uma branch cujo nome corresponde a releases/**-alpha, como beta/3-alpha (refs/releases/beta/3-alpha)
  • Uma tag denominada v2 (refs/tags/v2)
  • Uma tag 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

Você não pode usar branches e branches-ignore para filtrar o mesmo evento em um único fluxo de trabalho. Da mesma forma, você não pode usar tags e tags-ignore para filtrar o mesmo evento em um único fluxo de trabalho. Se você deseja incluir e excluir padrões de branches ou tags para um único evento, use o filtro branches ou tags junto com o caractere ! para indicar quais branches ou tags devem ser excluídos.

Se você definir um branch com o caractere !, você deverá definir pelo menos um branch sem o caractere !. Se você deseja apenas excluir branches, use branches-ignore. Da mesma forma, se você definir uma tag com o caractere !, você também deverá definir pelo menos uma tag sem o caractere !. Se você deseja apenas excluir tags, use tags-ignore.

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

  • Um padrão negativo (precedido por !) depois de uma correspondência positiva excluirá o Git ref.
  • 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, pois o padrão negativo !releases/**-alpha está na sequência do 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, é possível configurar um fluxo de trabalho para ser executado com base em quais caminhos de arquivo são alterados. Os filtros de caminho não são avaliados em pushes de tags.

Use filtro caminhos quando você quiser incluir padrões de caminho dos arquivos ou quando quiser que ambos incluam e excluam padrões de caminhos dos arquivos. Use o filtro paths-ignore quando você deseja excluir apenas padrões de caminho do arquivo. Você não pode usar os dois filtros caminhos e paths-ignore para o mesmo evento em um fluxo de trabalho.

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

As palavras-chave paths e paths-ignore aceitam padrões do glob que usam os caracteres curinga * e ** para coincidir com mais de um nome de caminho. Para obter mais informações, consulte a "Folha de consulta de filtro padrão".

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 seria executado sempre que você fizer push de um arquivo JavaScript (.js).

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

Observação: Se um fluxo de trabalho for ignorado devido à filtragem do caminho, a filtragem do caminho ou mensagem de commit as verificações associadas a esse fluxo de trabalho permanecerão em um estado "Pendente". Um pull request que requer que essas verificações sejam bem sucedidas será bloqueado do merge. Para obter mais informações, consulte "Manuseio ignorado, mas exigiu verificações".

Exemplo: Excluindo caminhos

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

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

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

Exemplo: Incluindo e excluindo caminhos

Você não pode usar caminhos e paths-ignore para filtrar o mesmo evento em um único fluxo de trabalho. Se você deseja incluir e excluir padrões de caminho para um único evento, use o filtro caminhos junto com o caractere ! para indicar quais caminhos devem ser excluídos.

Se você definir um caminho com o caractere !, você deverá definir pelo menos um caminho sem o caractere !. Se você deseja apenas excluir caminhos, use paths-ignore.

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

  • Um padrão negativo (precedido por !) depois de uma correspondência positiva excluirá o caminho.
  • 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 seus subdiretórios, a menos que o arquivo esteja no diretório sub-project/docs. Por exemplo, um push que alterou sub-project/index.js ou sub-project/src/index.js acionará uma execução de fluxo de trabalho, mas um push que altere somentesub-project/docs/readme.md não acionará.

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

Comparações Git diff

Observação: Se você fizer push de mais de 1.000 commits, ou se GitHub não gerar o diff 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 comparando-os à lista de 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:

  • Pull requests: diffs de três pontos são uma comparação entre a versão mais recente do branch de tópico e o commit onde o branch de tópico foi sincronizado pela última vez com o branch de base.
  • Pushes para branches existentes: um diff de dois pontos compara os SHAs head e base, um com o outro.
  • Pushes para novos branches: um diff de dois pontos compara o principal do ancestral do commit mais extenso que foi feito 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, consulte "Sobre comparação de branches em pull requests".

on.schedule

Você pode usar on.schedule para definir uma agenda para seus fluxos de trabalho. É possível programar um fluxo de trabalho para ser executado em horários de UTC específicos usando a sintaxe de 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 * * *'

A single workflow can be triggered by multiple schedule events. You can access the schedule event that triggered the workflow through the github.event.schedule context. This example triggers the workflow to run at 5:30 UTC every Monday-Thursday, but skips the Not on Monday or Wednesday step on Monday and Wednesday.

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, consulte "Eventos que acionam fluxos de trabalho".

on.workflow_call

Observação: Os fluxos de trabalho reutilizáveis estão atualmente na versão beta e sujeitos a alterações.

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

on.workflow_call.inputs

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

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

Se um parâmetro padrão não fordefinido, o valor padrão da entrada será falso para um booleano, 0 para um número e "" para uma string.

No fluxo de trabalho chamado, você pode usar o contexto entradas para referir-se a uma entrada.

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

Exemplo

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

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

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

Para obter mais informações, consulte "Reutilizando fluxos de trabalho".

on.workflow_call.inputs.<input_id>.type

Necessário se a entrada for definida para a palavra-chave on.workflow_call. O valor deste parâmetro é uma string que especifica o tipo de dados da entrada. Este deve ser um dos valores a seguir: booleano, número ou string.

on.workflow_call.outputs

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

No exemplo abaixo, dois valores de saída são definidos para este fluxo de trabalho reutilizável: workflow_output1 e workflow_output2. Eles são mapeados com as saídas chamadas job_output1 e job_output2, ambas de um trabalho chamado my_job.

Exemplo

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

Para obter informações sobre como fazer referência a uma saída de trabalho, consulte trabalhos.<job_id>.outputs. Para obter mais informações, consulte "Reutilizando fluxos de trabalho".

on.workflow_call.secrets

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

Dentro do fluxo de trabalho de chamada, você pode usar o contexto segredos para consultar um segredo.

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

Exemplo

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>

Um identificador de string para associar ao segredo.

on.workflow_call.secrets.<secret_id>.required

Um booleano que especifica se o segredo deve ser fornecido.

on.workflow_run.<branches|branches-ignore>

Ao usar o evento workflow_run, é possível especificar em quais branches o fluxo de trabalho de acionamento deve ser executado para acionar o seu fluxo de trabalho.

Os filtros branches e branches-ignore aceitam padrões do glob que usam caracteres como *, **, +, ?, ! e outros para combinar com mais de um nome de branch. Se um nome contiver qualquer um desses caracteres e você quiser uma correspondência literal, você deverá escapar de cada um desses caracteres especiais com \. Para obter mais informações sobre padrões de glob, consulte a "Folha de informações para filtrar padrões".

Por exemplo, um fluxo de trabalho com o acionamento a seguir só será executado quando o fluxo de trabalho denominado Build for executado em um branch cujo nome comece com releases/:

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

Um fluxo de trabalho com o acionamento a seguir só será executado quando o fluxo de trabalho denominado Build for executado em um branch que não seja denominado canary:

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

Você não pode usar ambos os filtros branches e branches-ignore para o mesmo evento em um fluxo de trabalho. Se você deseja incluir e excluir padrões de branch para um único evento, use o filtro branches junto com o caractere ! para indicar quais branches devem ser excluídos.

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

  • Um padrão negativo correspondente (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 acionamento a seguir será executado quando o fluxo de trabalho denominado Build for executado em um branch denominado releases/10 ou releases/beta/mona mas não será executado em releases/10-alpha, releases/beta/3-alpha ou principal.

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

on.workflow_dispatch.inputs

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

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

permissões

Você pode usar as permissões para modificar as permissões padrão concedidas ao GITHUB_TOKEN, adicionar ou remover o acesso conforme necessário, para que você permita apenas o acesso mínimo necessário. Para obter mais informações, consulte "Autenticação em um fluxo de trabalho".

Você pode usar as permissões de `como uma chave de nível superior, para aplicar a todos os trabalhos do fluxo de trabalho ou em trabalhos específicos. Ao adicionar a chave daspermissõesem um trabalho específico, todas as ações e comandos de execução dentro desse trabalho que usam oGITHUB_TOKEN ganham os direitos de acesso que você especificar. Para obter mais informações, consulte [jobs.<job_id>.permissions`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idpermissions).

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 qualquer um desses escopos, todos os que não são especificados são definidos como nenhum.

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

Você pode usar a chave de permissões para adicionar e remover permissões de leitura para repositórios bifurcados, mas, normalmente, você não pode conceder acesso de gravação. A exceção para esse comportamento é quando um usuário administrador selecionou a opção Enviar tokens para fluxos de trabalho de pull requests nas configurações do GitHub Actions. Para obter mais informações, consulte "Gerenciar configurações de GitHub Actions para um repositório".

Exemplo: Atribuindo permissões ao GITHUB_TOKEN

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

name: "My workflow"

on: [ push ]

permissions: read-all

jobs:
  ...

env

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

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

Quando mais de uma variável de ambiente é definida com o mesmo nome, GitHub usa a variável 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.

Exemplo

env:
  SERVER: production

padrões

Use padrões para criar um mapa das configurações padrão que serão aplicadas 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, consulte 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 o shell padrão e as opções de working-directory para todas as etapas de execução em um fluxo de trabalho. Você também pode definir as configurações-padrão para execução apenas disponíveis para um trabalho. Para obter mais informações, consulte 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

concorrência

Use concorrência para garantir que apenas um único trabalho ou fluxo de trabalho usando o mesmo grupo de concorrência seja executado de cada 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, consulte "Expressões".

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

Quando um trabalho simultâneo ou fluxo de trabalho é enfileirado, se outro trbalho ou fluxo de trabalho que usa o mesmo grupo de concorrência no repositório estiver em andamento o trabalho na fila ou o fluxo de trabalho ficará pendente. Qualquer trabalho ou fluxo de trabalho anterior pendente no grupo de concorrência será cancelado. Para cancelar também qualquer trabalho atualmente em execução ou fluxo de trabalho no mesmo grupo de concorrência, 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 está definido apenas em eventos pull_request. Se o seu fluxo de trabalho responder a outros eventos além dos eventos pull_request, você deverá fornecer uma segunda opção para evitar um erro de sintaxe. O grupo de concorrência a seguir cancela trabalhos em andamento ou executa somente em eventos pull_request; se github.head_ref não estiver definido, o grupo de concorrência voltará ao ID de execução e será garantido que ambos serão únicos e definidos 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 execuções no mesmo fluxo de trabalho, você pode usar a propriedade github.workflow para criar o grupo de concorrência:

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

jobs

A execução de um fluxo de trabalho é composta por uma 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 de 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, consulte "Limites de uso e cobrança" para executores hospedados em GitHub e "Sobre executores auto-hospedados" para limites de uso de executor auto-hospedado.

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, consulte "Trabalhos do fluxo de trabalho".

jobs.<job_id>

Use jobs.<job_id> para fornecer um identificador único ao seu trabalho. A chave job_id é uma string, e seu valor é um mapa dos dados de configuração do trabalho. Você deve substituir <job_id> por uma string exclusiva para o objeto jobs. <job_id> deve começar por uma letra ou _, além de conter somente caracteres alfanuméricos, - ou _.

Exemplo: Criando trabalhos

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

jobs:
  meu_primeiro_trabalho:
    name: meu primeiro trabalho
  meu_segundo_trabalho:
    name: meu segundo trabalho

jobs.<job_id>.name

Use jobs.<job_id>.name para definir um nome para o trabalho, que é exibido na interface do usuário de 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, adicionar ou remover o acesso conforme necessário, para que você apenas permita o acesso mínimo necessário. Para obter mais informações, consulte "Autenticação em um fluxo de trabalho".

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

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 qualquer um desses escopos, todos os que não são especificados são definidos como nenhum.

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

Você pode usar a chave de permissões para adicionar e remover permissões de leitura para repositórios bifurcados, mas, normalmente, você não pode conceder acesso de gravação. A exceção para esse comportamento é quando um usuário administrador selecionou a opção Enviar tokens para fluxos de trabalho de pull requests nas configurações do GitHub Actions. Para obter mais informações, consulte "Gerenciar configurações de GitHub Actions para um repositório".

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 só se aplicará ao trabalho denominado stale. O acesso de gravação é concedido para os escopos dos problemas e pull-requests. Todos os outros escopos não terão acesso.

jobs:
  stale:
    runs-on: ubuntu-latest

    permissions:
      issues: write
      pull-requests: write

    steps:
      - uses: actions/stale@v4

jobs.<job_id>.needs

Use as jobs.<job_id>.needs para identificar qualquer trabalho que deve ser concluído com sucesso antes deste trabalho ser 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 contém uma série de trabalhos que precisam um do outro, uma falha aplica-se a todos os trabalhos da cadeia de dependência desde o momento da falha.

Exemplo: Exigindo trabalhos dependentes com sucesso

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

Neste exemplo, job1 deve ser concluído com êxito antes do início de job2, e job3 aguarda a conclusão de job1 e 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 depois de job1 e job2 terem sido concluídos, independentemente de terem sido bem sucedidos. Para obter mais informações, consulte "Expressões".

jobs.<job_id>.if

Você pode usar a condicional jobs.<job_id>.if para evitar que um trabalho seja executado a não ser que determinada condição seja atendida. Você pode usar qualquer contexto e expressão compatível para criar uma condicional.

Quando você usa expressões em uma condicional if você pode omitir a sintaxe da expressão (${{ }}) porque GitHub calcula automaticamente a condição if como expressão. Para obter mais informações, consulte "Expressões".

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

Este exemplo usa se para controlar quando o trabalho production-deploy pode ser executado. Ele só será executado se o repositório for denominado octo-repo-prod e estiver dentro da 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@v2
      - uses: actions/setup-node@v2
        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 máquina para executar o trabalho. Você pode fornecer runs-on como uma única string ou como uma matriz de strings. Se você especificar uma matriz de strings, o seu fluxo de trabalho será executado em um executor auto-hospedado cujas etiquetas correspondam a todos os valores de runs-on, se disponível. Se você quiser executar seu fluxo de trabalho em várias máquinas, use jobs.<job_id>.strategy.

Observação: Executores hospedados em GitHub não são atualmente compatíveis com GitHub Enterprise Server. Você pode ver mais informações sobre suporte futuro planejado no Itinerário público do GitHub.

Escolhendo executores hospedados em GitHub

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

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

Ambiente virtual Etiqueta de fluxo de trabalho YAML Observações
Windows Server 2022 windows-latest ou windows-2022 O rótulo windows-latest usa atualmente a imagem do executor do Windows Server 2022.
Windows Server 2019 windows-2019
Ubuntu 22.04 ubuntu-22.04 O Ubuntu 22,04 está atualmente em beta público.
Ubuntu 20.04 ubuntu-latest ou ubuntu-20.04
Ubuntu 18.04 ubuntu-18.04
macOS Monterey 12 macos-12
macOS Big Sur 11 macos-latest or macos-11 A etiqueta macos-latest usa a imagem do executor macOS 11 atualmente.
macOS Catalina 10.15 macos-10.15

Observação: Os -últimos ambientes virtuais são as últimas imagens estáveis que GitHub fornece, e podem não ser a versão mais recente do sistema operacional disponível no fornecedor do sistema operacional.

Observação: Imagens Beta e Depreciadas são fornecidas "como se apresentam", "com todas as falhas" e "como disponível" e são excluídas da garantia e do contrato de nível de serviço. Imagens Beta podem não estar cobertas pelo suporte ao cliente.

Exemplo: Especificar um sistema operacional

runs-on: ubuntu-latest

Para obter mais informações, consulte "Ambientes virtuais para executores hospedados em GitHub".

Escolhendo executores auto-hospedados

Para especificar um executor auto-hospedado para o seu trabalho, configure runs-on no seu arquivo de fluxo de trabalho com etiquetas de executores auto-hospedados.

Todos os executores auto-hospedados têm a etiqueta auto-hospedado. O uso apenas esta etiqueta selecionará qualquer executor auto-hospedado. Para selecionar executores que atendem a certos critérios, como sistema operacional ou arquitetura, recomendamos fornecer uma matriz de etiquetas que começam com auto-hospedado (isso deve ser listado primeiro) e, em seguida, inclui etiquetas adicionais, conforme necessário. Ao especificar uma matriz de etiquetas, os trabalhos serão colocados na fila em executores que tenham todas as etiquetas especificadas.

Embora a etiqueta de auto-hospedado não seja obrigatória, recomendamos especificá-lo quando estiver usando executores auto-hospedados para garantir que seu trabalho não especifique nenhum executor atual ou futuro de GitHub.

Exemplo: Usando etiquetas para seleção do executor

runs-on: [self-hosted, linux]

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

jobs.<job_id>.environment

Use jobs.<job_id>.environment para definir o ambiente de referência do trabalho. 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, consulte "Usando ambientes para implantação".

Você pode fornecer o ambiente apenas como o nome do ambiente, ou como um objeto de ambiente com o nome e url. A URL é mapeada com environment_url na API de implantações. Para obter mais informações sobre a API de implantações, consulte "Implantações".

Exemplo: Usando um único nome de ambiente

ambiente: 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 para o contexto segredos. Para obter mais informações sobre expressões, consulte "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 concorrência é especificada no nível do trabalho, não se garante a ordem para trabalhos ou execuções que são enfileiradas em 5 minutos uma da outra.

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

Você também pode especificar concorrência no nível do fluxo de trabalho. Para obter mais informações, consulte concorrência.

Quando um trabalho simultâneo ou fluxo de trabalho é enfileirado, se outro trbalho ou fluxo de trabalho que usa o mesmo grupo de concorrência no repositório estiver em andamento o trabalho na fila ou o fluxo de trabalho ficará pendente. Qualquer trabalho ou fluxo de trabalho anterior pendente no grupo de concorrência será cancelado. Para cancelar também qualquer trabalho atualmente em execução ou fluxo de trabalho no mesmo grupo de concorrência, 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 está definido apenas em eventos pull_request. Se o seu fluxo de trabalho responder a outros eventos além dos eventos pull_request, você deverá fornecer uma segunda opção para evitar um erro de sintaxe. O grupo de concorrência a seguir cancela trabalhos em andamento ou executa somente em eventos pull_request; se github.head_ref não estiver definido, o grupo de concorrência voltará ao ID de execução e será garantido que ambos serão únicos e definidos 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 execuções no mesmo fluxo de trabalho, você pode usar a propriedade github.workflow para criar o grupo de concorrência:

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

jobs.<job_id>.outputs

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

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

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

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

Exemplo: Definindo saídas para um trabalho

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

jobs.<job_id>.env

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

Quando mais de uma variável de ambiente é definida com o mesmo nome, GitHub usa a variável 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.

Exemplo

jobs:
  job1:
    env:
      FIRST_NAME: Mona

jobs.<job_id>.defaults

Use jobs.<job_id>.defaults para criar um mapa 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, consulte padrão.

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 padrão e workdirectory para todas as etapas run no trabalho. Não são permitidos contexto e expressão nesta seção.

Você pode fornecer as opções-padrão de shell e working-directory para todas as etapas de execução de um trabalho. Você também pode definir as configurações-padrão para execução para todo o fluxo de trabalho. Para obter mais informações, consulte 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: Configuração padrão da etapa executar para um trabalho

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

jobs.<job_id>.steps

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

Você pode executar quantas etapas quiser, desde que esteja dentro dos limites de uso do fluxo de trabalho. Para obter mais informações, consulte "Limites de uso e cobrança" para executores hospedados em GitHub e "Sobre executores auto-hospedados" para limites de uso de executor auto-hospedado.

Exemplo

name: Greeting from Mona

on: push

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

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

Identificador exclusivo da etapa. Você pode usar id para fazer referência à etapa em contextos. Para obter mais informações, consulte "Contextos".

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

Você pode usar a condicional if (se) para evitar que uma etapa trabalho seja executada a não ser que determinada condição seja atendida. Você pode usar qualquer contexto e expressão compatível para criar uma condicional.

Quando você usa expressões em uma condicional if você pode omitir a sintaxe da expressão (${{ }}) porque GitHub calcula automaticamente a condição if como expressão. Para obter mais informações, consulte "Expressões".

Exemplo: Usando contextos

Essa etapa somente é executada quando o tipo de evento é uma pull_request e a ação do evento é unassigned (não atribuída).

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

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

A função my backup step (minha etapa de backup) somente é executada quando houver falha em uma etapa anterior do trabalho. Para obter mais informações, consulte "Expressões".

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

Exemplo: Usando segredos

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

Se um segredo não tiver sido definido, o valor de retorno de uma expressão referente ao segredo (como ${{ secrets.SuperSecret }} no exemplo) será uma string vazia.

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

Para obter mais informações, consulte "Disponibilidade de contexto" e "Segredos criptografados".

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

Nome da etapa no GitHub.

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

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

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

  • Usar o commit SHA de uma versão de ação lançada é a maneira mais garantida de obter estabilidade e segurança.
  • Usar a versão principal da ação permite receber correções importantes e patches de segurança sem perder a compatibilidade. Fazer isso também garante o funcionamento contínuo do fluxo de trabalho.
  • Usar o branch-padrão de uma ação pode ser conveniente, mas se alguém lançar uma nova versão principal com uma mudança significativa, seu fluxo de trabalho poderá ter problemas.

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

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

Exemplo: Usando ações de versão

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

Exemplo: Usando uma ação pública

{owner}/{repo}@{ref}

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

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

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

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

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

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

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

./path/to/dir

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

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

Exemplo: Usando uma ação do Docker Hub

docker://{image}:{tag}

Imagem Docker publicada no Docker Hub.

empregos:
  my_first_job:
    passos:
      - nome: Meu primeiro passo
        usa: docker://alpine:3.8

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

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

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

jobs:
  meu_primeiro_trabalho:
    steps:
      - name: minha primeira etapa
        uses: docker://gcr.io/cloud-builders/gradle

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

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

Substitua PERSONAL_ACCESS_TOKEN no exemplo pelo nome do seu segredo.

jobs:
  my_first_job:
    steps:
      - name: Check out repository
        uses: actions/checkout@v2
        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

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

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

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

  • Um comando de linha única:

    - name: Install Dependencies
      run: npm install
    
  • Um comando de várias linhas:

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

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

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

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

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

Plataforma compatívelParâmetro shellDescriçãoComando executado internamente
TodasbashO shell padrão em plataformas que não sejam Windows como uma alternativa para sh. Ao especificar um shell bash no Windows, é utilizado o shell bash incluído no Git para Windows.bash --noprofile --norc -eo pipefail {0}
TodaspwshPowershell Core. O GitHub anexa a extensão .ps1 ao nome do script.pwsh -command ". '{0}'"
TodaspythonExecuta o comando python.python {0}
Linux / macOSshComportamento alternativo para plataformas que não sejam Windows se nenhum shell for fornecido e o bash não for encontrado no caminho.sh -e {0}
WindowscmdO GitHub anexa a extensão .cmd ao nome do script e a substitui por {0}.%ComSpec% /D /E:ON /V:OFF /S /C "CALL "{0}"".
WindowspwshEssa é a shell padrão usada no Windows. Powershell Core. O GitHub anexa a extensão .ps1 ao nome do script. Se o seu executor do Windows auto-hospedado não tiver o PowerShell Core instalado, será usado o PowerShell Desktop.pwsh -command ". '{0}'".
WindowspowershellO PowerShell Desktop. O GitHub anexa a extensão .ps1 ao nome do script.powershell -command ". '{0}'".

Exemplo: Executando um script usando o bash

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

Exemplo: Executando um script usando cmd do Windows

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

Exemplo: Executando um script usando PowerShell Core

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

Exemplo: Usar o PowerShell Desktop para executar um script

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

Exemplo: Executando um script do Python

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

Shell personalizado

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

Por exemplo:

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

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

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

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

  • bash/sh:

    • Comportamento de falha rápido que usa set -eo pipefail: Padrão para bash e shell embutido. Também é o padrão quando você não der opção em plataformas que não sejam Windows.
    • Você pode cancelar o fail-fast e assumir o controle fornecendo uma string de modelo para as opções do shell. Por exemplo, bash {0}.
    • Shells do tipo sh saem com o código de saída do último comando executado em um script, que também é o comportamento padrão das ações. O executor relatará o status da etapa como falha/êxito com base nesse código de saída.
  • powershell/pwsh

    • Comportamento fail-fast quando possível. Para shell integrado pwsh e powershell, precederemos $ErrorActionPreference = 'stop' para conteúdos de script.
    • Vincularemos if ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE } a scripts powershell para que os status da ação reflitam o código de saída mais recente do script.
    • Os usuários podem sempre optar por não usar o shell integrado e fornecer uma opção personalizada, como: pwsh -File {0} ou powershell -Command "& '{0}'", dependendo da situação.
  • cmd

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

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

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

Exemplo

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

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

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

Uma string que define as entradas para um contêiner Docker. O GitHub entrega os args ao ENTRYPOINT do contêiner quando o contêiner inicia. Um array de strings não é compatível com esse parâmetro.

Exemplo

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.

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

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

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

Anula o ENTRYPOINT Docker no Dockerfile ou define-o caso ainda não tenha sido especificado. Diferentemente da instrução Docker ENTRYPOINT que tem um formulário shell e exec, a palavra-chave entrypoint aceita apena uma única string que define o executável.

Exemplo

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

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

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

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

Ações públicas podem especificar variáveis de ambiente esperadas no arquivo LEIAME. Se você está configurando um segredo em uma variável de ambiente, use o contexto secrets. Para obter mais informações, consulte "Usando variáveis de ambiente" e "Contextos".

Exemplo

steps:
 - name: minha primeira ação
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    FIRST_NAME: Mona
    LAST_NAME: Octocat

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

Impede a falha de um trabalho se uma etapa não funcionar. Defina true (verdadeiro) para permitir que um trabalho aconteça quando essa etapa falhar.

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

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

jobs.<job_id>.timeout-minutes

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

Se o tempo-limite exceder o tempo limite de execução do trabalho para o runner, o trabalho será cancelada quando o tempo limite de execução for atingido. Para obter mais informações sobre o limite de tempo de execução do trabalho, consulte "Limites de uso e cobrança" para executores hospedados em GitHub e "Sobre executores auto-hospedados" para limites de uso de executores auto-hospedados.

Observação: O GITHUB_TOKEN vence quando um trabalho for concluído ou após um máximo de 24 horas. para executores auto-hospedados, o token pode ser o fator de limitação se o tempo limite do trabalho for superior a 24 horas. Para obter mais informações sobre o GITHUB_TOKEN, consulte "Sobre segredo do GITHUB_TOKEN."

jobs.<job_id>.strategy

Use trabalhos.<job_id>.strategy para usar uma estratégia matriz para seus trabalhos. Uma estratégia de matriz permite usar variáveis em uma única definição de trabalho para criar automaticamente várias execuções de trabalho que são 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 uma linguagem ou em vários sistemas operacionais. Para obter mais informações, consulte "Usando uma matriz para seus trabalhos "".

jobs.<job_id>.strategy.matrix

Use jobs.<job_id>.strategy.matrix para definir uma matriz de diferentes configurações de trabalho. Dentro da sua matriz, defina uma ou mais variáveis seguidas por uma matriz de valores. Por exemplo, a seguinte matriz tem uma variável denominada versão com o valor [10, 12, 14] e uma variável denominada 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 das variáveis possível. Neste exemplo, o fluxo de trabalho irá executar seis trabalhos, um para cada combinação das variáveis os e versão.

Por padrã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 em que os trabalhos são criados. A primeira variável que você definir será o primeiro trabalho criado na execução do fluxo de trabalho. Por exemplo, a matriz acima irá 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 gerará no máximo 256 trabalhos por execução do fluxo de trabalho. Este limite aplica-se tanto a executores hospedados em GitHub Enterprise Server quanto a executores auto-hospedados.

As variáveis que você define tornam-se propriedades no contexto da matriz e você pode fazer referência à propriedade em outras áreas do seu arquivo de fluxo de trabalho. Neste exemplo, você pode usar a matriz.version e matrix.os para acessar o valor atual de versão e os que o trabalho está usando. Para obter mais informações, consulte "Contextos".

Exemplo: Usando uma matriz de dimensão única

Você pode especificar uma variável única para criar uma matriz de dimensão única.

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

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

Exemplo: Usando uma matriz de múltiplas dimensões

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

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 versão

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

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

Exemplo: Usando contextos para criar matrizes

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

Por exemplo, os seguintes gatilhos de fluxo de trabalho no evento repository_dispatch e usa informações da carga do evento para criar a matriz. Quando um evento de envio de repositório é criado com uma carga como a abaixo, a variável versão da matriz terá um valor de [12, 14, 16]. Para obter mais informações sobre o gatilho repository_dispatch, consulte "Eventos que acionam 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@v2
        with:
          node-version: ${{ matrix.version }}

jobs.<job_id>.strategy.matrix.include

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

Para cada objeto na lista incluir, os pares chave-valor no objeto serão adicionados a cada uma das combinações da matriz se nenhum dos pares chave-valor sobrescrever qualquer dos valores originais da matriz. Se o objeto não pode ser adicionado a qualquer das combinações matriz, será criada uma nova combinação matriz. Observe que os valores originais da matriz não serão substituídos, mas valores adicionados da matriz 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} é adicionado a todas as combinações de matrizes originais, porque pode ser adicionado sem substituir nenhuma parte das combinações originais.
  • {color: pink, animal: cat} adiciona color>pink apenas para as combinações originais da matriz que incluem animal: cat. Isto sobrescreve color: green que foi adicionada pela entrada incluir anterior.
  • {fruit: apple, shape: circle} adiciona shape: circle apenas às combinações da matriz original que incluem fruit: apple.
  • {fruit: banana} não pode ser adicionado a qualquer combinação da matriz original sem substituir um valor. Portanto, ele é adicionado como uma combinação da matriz adicional.
  • {fruit: banana, animal: cat} não pode ser adicionado a qualquer combinação da matriz original sem substituir um valor. Portanto, ele é adicionado como uma combinação da matriz adicional. Não se adiciona à combinação da matriz {fruit: banana} porque essa combinação não era uma das combinações originais da matriz.

Exemplo: Expandir configurações

Por exemplo, o fluxo de trabalho a seguir irá executar seis trabalhos, um para cada combinação de os e node. Quando o valor do trabalho para o os de windows-latest e o valor node de 16 for executado, 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@v2
        with:
          node-version: ${{ matrix.node }}
      - if: ${{ matrix.npm }}
        run: npm install -g npm@${{ matrix.npm }}
      - run: npm --version

Exemplo: Adicionar configurações

Por exemplo, esta matriz gerará 10 trabalhos, um para cada combinação de os e versão na matriz, mais um trabalho para o valor de os de windows-latest e o valor da versão 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 da matriz, todas as configurações em incluir serão executadas. Por exemplo, o seguinte fluxo de trabalho executaria dois trabalhos, um para cada entrada de incluir. Isso permite que você aproveite a estratégia da matriz sem ter uma matriz totalmente preenchida.

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 seja excluída. Por exemplo, o fluxo de trabalho a seguir irá executar nove trabalhos: um trabalho para cada uma das 12 configurações, menos a tarefa excluída que corresponde a {os: macos-latest, version: 12, environment: production}, e os dois trabalhos excluídos que correspondem a {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 incluir são processadas depois de excluir. Isso permite que você use incluir para voltar a adicionar combinações que foram excluídas anteriormente.

jobs.<job_id>.strategy.fail-fast

Você pode controlar como 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 à matriz inteira. Se jobs.<job_id>.strategy.fail-fast estiver definido como verdadeiro, GitHub Enterprise Server cancelará todos os trabalhos em andamento e agendados na matriz se algum trabalho na matriz falhar. Esta propriedade padrão é verdadeira.

jobs.<job_id>.continue-on-error aplica-se a um único trabalho. Se jobs.<job_id>.continue-on-error for true, os outros trabalhos na matriz continuarão sendo executados, ainda que o trabalho com jobs.<job_id>.continue-on-error: true falhe.

Você pode usar jobs.<job_id>.strategy.fail-fast e jobs.<job_id>.continue-on-error juntos. Por exemplo, o fluxo de trabalho a seguir dará início a quatro trabalhos. Para cada trabalho, continue-on-error é determinado pelo valor de matriz.experimental. Se algum dos jobs com continue-on-error: false falhar, todos os trabalhos em progresso ou na fila 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, 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 ao usar uma estratégia de trabalho de matriz, use jobs.<job_id>.strategy.max-parallel.

Por exemplo, o fluxo de trabalho seguinte será executado um máximo de duas tarefas por vez, mesmo que haja executores disponíveis para executar todos os seis trabalhos de uma só vez.

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

jobs.<job_id>.continue-on-error

Impede que ocorra falha na execução de um fluxo de trabalho quando ocorrer uma falha em um trabalho. Defina como verdadeiro para permitir que uma execução de um fluxo de trabalho passe quando este trabalho falhar.

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

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

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

jobs.<job_id>.container

Observação: se seus fluxos de trabalho usam ações do contêiner Docker, contêineres de trabalho ou contêineres de serviço, você deve 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 para criar um contêiner para executar todas as etapas de um trabalho que já não especificam um contêiner. Se você tiver etapas que usam ações de script e de contêiner, as ações de contêiner serão executadas como contêineres irmãos na mesma rede e com as mesmas montagens de volume.

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

Exemplo: Executar um trabalho dentro de um contêiner

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)

Ao especificar somente uma imagem de contêiner, você pode omitir a palavra-chave image.

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

jobs.<job_id>.container.image

Use jobs.<job_id>.container.image para definir a imagem do Docker para usar 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 extrair a imagem, você pode usar as funções de .<job_id>.container.credentials para definir um mapa do nome de usuário e senha. As credenciais são os mesmos valores que você forneceria para o comando login do docker.

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

Usar jobs.<job_id>.container.env para definir um mapa de variáveis de ambiente no contêiner.

jobs.<job_id>.container.ports

Use jobs.<job_id>.container.ports para definir uma matriz de portas para ser exposta no contêiner.

jobs.<job_id>.container.volumes

Use jobs.<job_id>.container.volumes para definir uma matriz de volumes para o contêiner usar. É 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 caminho absoluto na máquina 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, consulte "opções docker create".

Aviso: A opção --network não é compatível.

jobs.<job_id>.services

Observação: se seus fluxos de trabalho usam ações do contêiner Docker, contêineres de trabalho ou contêineres de serviço, você deve 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.

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

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

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

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

Exemplo: Usando host local

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

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

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

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

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

Se o registro de contêiner da imagem exigir autenticação para extrair a imagem, você pode usar as funções de .<job_id>.container.credentials para definir um mapa do nome de usuário e senha. As credenciais são os mesmos valores que você forneceria para o comando login do docker.

Exemplo

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

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

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

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

Define um array de portas para expor no contêiner de serviço.

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

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

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

<source>:<destinationPath>.

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

Exemplo

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

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

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

Aviso: A opção --network não é compatível.

jobs.<job_id>.uses

Observação: Os fluxos de trabalho reutilizáveis estão atualmente na versão beta e sujeitos a alterações.

O local e a versão de um arquivo de fluxo de trabalho reutilizável para ser executado como trabalho.

  • {owner}/{repo}/.github/fluxos de trabalho/{filename}@{ref}

{ref} pode ser um SHA, uma tag de de versão ou um nome de branch. Usar o commit SHA é o mais seguro para a estabilidade e segurança. Para obter mais informações, consulte "Enrijecimento de segurança para o GitHub Actions".

Exemplo

jobs:
  call-workflow-1-in-local-repo:
    uses: octo-org/this-repo/.github/workflows/workflow-1.yml@172239021f7ba04fe7327647b213799853a9eb89
  call-workflow-in-another-repo:
    uses: octo-org/another-repo/.github/workflows/workflow.yml@v1

Para obter mais informações, consulte "Reutilizando fluxos de trabalho".

jobs.<job_id>.with

Quando um trabalho é usado para chamar um fluxo de trabalho reutilizável, você pode usar com para fornecer um mapa de entradas que são passadas para o fluxo de trabalho de chamada.

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

Diferentemente de jobs.<job_id>.steps[*].with, as entradas que você passar com jobs.<job_id>.with não estão disponíveis como variáveis de ambiente no fluxo de trabalho de chamada. Ao invés disso, você pode fazer referência às entradas usando o contexto entrada.

Exemplo

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

jobs.<job_id>.with.<input_id>

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

Contextos de expressão permitidos: github e needs.

jobs.<job_id>.secrets

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

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

Exemplo

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>

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

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

Folha de consulta de filtro padrão

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

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

Os caracteres *, [ e ! são caracteres especiais em YAML. Se você iniciar um padrão com *, [ ou !, você deverá colocá-lo entre aspas.

# Válido
- '**/README.md'

# Inválido - Cria um erro de análise que
# impede que o seu fluxo de trabalho seja executado.
- **/README.md

Par aobte rmais informações sobre branch, tag e sintaxe de filtro do caminho, consulte "on.<push>.<branches|tags>", "on.<pull_request>.<branches|tags>" e "on.<push|pull_request>.paths."

Padrões para corresponder branches e tags

PadrãoDescriçãoExemplos de correspondências
feature/*O caractere curinga * corresponde a qualquer caractere, mas não à barra (/).feature/my-branch

feature/your-branch
feature/**** correspondem a qualquer caractere, incluindo a barra (/) em nomes de branches e tags.feature/beta-a/my-branch

feature/your-branch

feature/mona/the/octocat
main

releases/mona-the-octocat
Corresponde ao nome exato de um branch ou tag.main

releases/mona-the-octocat
'*'Corresponde a todos os nomes de branches e tags que não contêm uma barra (/). O caractere * é um caractere especial em YAML. Ao inciar um padrão com *, você deve usar aspas.main

releases
'**'Corresponde a todos os nomes de branches e tags. Esse é o comportamento padrão quando você não usa um filtro de branches ou tags.all/the/branches

every/tag
'*feature'O caractere * é um caractere especial em YAML. Ao inciar um padrão com *, você deve usar aspas.mona-feature

feature

ver-10-feature
v2*Corresponde aos nomes de branches e tags que iniciam com v2.v2

v2.0

v2.9
v[12].[0-9]+.[0-9]+Corresponde a todas as tags de versão de branch semântica com a versão principal 1 ou 2.v1.10.1

v2.0.0

Padrões para corresponder a caminhos de arquivos

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

PadrãoDescrição das correspondênciasExemplos de correspondências
'*'O caractere curinga * corresponde a qualquer caractere, mas não à barra (/). O caractere * é um caractere especial em YAML. Ao inciar um padrão com *, você deve usar aspas.README.md

server.rb
'*.jsx?'O caractere ? corresponde a zero ou a um dos caracteres anteriores.page.js

page.jsx
'**'** corresponde a qualquer caractere incluindo a barra (/). Esse é o comportamento padrão quando você não usa um filtro de path.all/the/files.md
'*.js'O caractere curinga * corresponde a qualquer caractere, mas não à barra (/). Corresponde a todos os arquivos .js na raiz do repositório.app.js

index.js
'**.js'Corresponde a todos os arquivos .js no repositório.index.js

js/index.js

src/js/app.js
docs/*Todos os arquivos dentro da raiz do diretório docs, na raiz do repositório.docs/README.md

docs/file.txt
docs/**Qualquer arquivo no diretório docs, na raiz do repositório.docs/README.md

docs/mona/octocat.txt
docs/**/*.mdUm arquivo com um sufixo .md em qualquer local do diretório docs.docs/README.md

docs/mona/hello-world.md

docs/a/markdown/file.md
'**/docs/**'Qualquer arquivo no diretório docs, em qualquer local do repositório.docs/hello.md

dir/docs/my-file.txt

space/docs/plan/space.doc
'**/README.md'Um arquivo README.md em qualquer local do repositório.README.md

js/README.md
'**/*src/**'Qualquer arquivo em uma pasta com o sufixo src em qualquer local do repositório.a/src/app.js

my-src/code/js/app.js
'**/*-post.md'Um arquivo com o sufixo -post.md em qualquer local do repositório.my-post.md

path/their-post.md
'**/migrate-*.sql'Um arquivo com o prefixo migrate- e sufixo .sql em qualquer local do repositório.migrate-10909.sql

db/migrate-v1.0.sql

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

!README.md
Usar um sinal de exclamação (!) na frente de um padrão o anula. Quando um arquivo corresponde a um padrão e também corresponde a um padrão negativo definido posteriormente no arquivo, o arquivo não será incluído.hello.md

Does not match

README.md

docs/hello.md
*.md

!README.md

README*
Os padrões são verificados sequencialmente. Um padrão que anula um padrão anterior irá incluir caminhos de arquivos novamente.hello.md

README.md

README.doc