Observação: no momento, não há suporte para os executores hospedados no GitHub no GitHub Enterprise Server. Você pode ver mais informações sobre o suporte futuro planejado no GitHub public roadmap.
About YAML syntax for workflows
Workflow files use YAML syntax, and must have either a .yml
or .yaml
file extension. Se você não estiver familiarizado com o YAML e quiser saber mais, confira "Aprenda a usar o YAML em Y minutos".
You must store workflow files in the .github/workflows
directory of your repository.
name
The name of your workflow. GitHub displays the names of your workflows on your repository's "Actions" tab. If you omit name
, GitHub sets it to the workflow file path relative to the root of the repository.
on
Para disparar automaticamente um fluxo de trabalho, use on
para definir os eventos que podem fazer com que o fluxo de trabalho seja executado. Para ver uma lista dos eventos disponíveis, confira "Eventos que disparam fluxos de trabalho".
Você pode definir um ou vários eventos que possam acionar um fluxo de trabalho ou definir um cronograma. Também é possível restringir a execução de um fluxo de trabalho para que ocorra apenas para altearções específicas para arquivos, tags ou alterações no branch. Essas opções são descritas nas seções a seguir.
Usando um evento único
Por exemplo, um fluxo de trabalho com o seguinte valor on
será executado quando um push for feito em qualquer branch no repositório do fluxo de trabalho:
on: push
Usando eventos múltiplos
É possível especificar um único evento ou vários eventos. Por exemplo, um fluxo de trabalho com o valor on
a seguir será executado quando um push for feito em qualquer branch no repositório ou quando alguém criar um fork do repositório:
on: [push, fork]
Se você especificar vários eventos, apenas um desses eventos deverá ocorrer para acionar seu fluxo de trabalho. Se vários eventos de acionamento para o seu fluxo de trabalho ocorrerem ao mesmo tempo, várias execuções de fluxo de trabalho serão acionadas.
Usando tipos de atividade
Alguns eventos têm tipos de atividade que oferecem mais controle sobre quando o fluxo de trabalho deve ser executado. Use on.<event_name>.types
para definir o tipo de atividade de evento que vai disparar uma execução de fluxo de trabalho.
Por exemplo, o evento issue_comment
tem os tipos de atividades created
, edited
e deleted
. Se o fluxo de trabalho for disparado no evento label
, ele será executado sempre que um rótulo for criado, editado ou excluído. Se você especificar o tipo de atividade created
para o evento label
, o fluxo de trabalho será executado quando um rótulo for criado, mas não quando um rótulo for editado ou excluído.
on:
label:
types:
- created
Se você especificar vários tipos de atividades, apenas um desses tipos de atividade deverá ocorrer para acionar o fluxo de trabalho. Se vários tipos de atividade do evento de acionamento ocorrer em seu fluxo de trabalho ao mesmo tempo, várias execuções de fluxo de trabalho serão acionadas. Por exemplo, os acionadores de fluxo de trabalho a seguir quando um problema é aberto ou identificado. Se um problema com duas etiquetas for aberta, serão iniciadas três execuções de fluxos de trabalho: uma para o problema aberto e duas para os dois problemas etiquetados.
on:
issues:
types:
- opened
- labeled
Para obter mais informações sobre cada evento e os respectivos tipos de atividades, confira "Eventos que disparam fluxos de trabalho".
Usando filtros
Alguns eventos têm filtros que dão mais controle sobre quando seu fluxo de trabalho deve ser executado.
Por exemplo, o evento push
tem um filtro branches
que faz com que seu fluxo de trabalho seja executado somente quando ocorrer um push para um branch que corresponde ao filtro branches
, em vez de quando ocorrer qualquer push.
on:
push:
branches:
- main
- 'releases/**'
Usando tipos de atividade e filtros com vários eventos
Se você especificar tipos de atividade ou filtros para um evento e seu fluxo de trabalho for acionado em vários eventos, você deverá configurar cada evento separadamente. Você deve acrescentar dois-pontos (:
) a todos os eventos, incluindo eventos sem configuração.
Por exemplo, um fluxo de trabalho com o seguinte valor on
será executado quando:
- Uma etiqueta foi criada
- Um push for feito para o branch
main
no repositório - Um push é feito para um branch habilitado para GitHub Pages
on:
label:
types:
- created
push:
branches:
- main
page_build:
on.<event_name>.types
Use on.<event_name>.types
para definir o tipo de atividade que vai disparar uma execução de fluxo de trabalho. A maioria dos eventos GitHub são acionados por mais de um tipo de atividade. Por exemplo, o label
é disparado quando um rótulo é created
, edited
ou deleted
. A palavra-chave types
permite restringir a atividade que faz com que o fluxo de trabalho seja executado. Quando apenas um tipo de atividade dispara um evento de webhook, a palavra-chave types
é desnecessária.
Você pode usar uma matriz de eventos types
. Para obter mais informações sobre cada evento e os respectivos tipos de atividades, confira "Eventos que disparam fluxos de trabalho".
on:
label:
types: [created, edited]
on.<pull_request|pull_request_target>.<branches|branches-ignore>
Ao usar os eventos pull_request
e pull_request_target
, você pode configurar um fluxo de trabalho para ser executado somente para solicitações de pull direcionadas a branches específicos.
Use o filtro branches
quando quiser incluir padrões de nomes de branches ou quando quiser incluir e excluir padrões de nomes de branches. Use o filtro branches-ignore
quando quiser excluir apenas padrões de nomes de branches. Não é possível usar os filtros branches
e branches-ignore
para o mesmo evento em um fluxo de trabalho.
Se você definir branches
/branches-ignore
e paths
, o fluxo de trabalho só será executado quando ambos os filtros forem atendidos.
As palavras-chave branches
e branches-ignore
aceitam padrões glob que usam caracteres como *
, **
, +
, ?
, !
e outros para corresponder a mais de um nome de branch. Se um nome contiver um desses caracteres e você quiser ter uma correspondência literal, faça escape de cada um desses caracteres especiais com \
. Para obter mais informações sobre padrões glob, confira a "Folha de referências de padrões de filtro".
Exemplo: Incluindo branches
Os padrões definidos em branches
são avaliados em relação ao nome da referência do Git. Por exemplo, o seguinte fluxo de trabalho será executado sempre que houver um evento pull_request
para uma solicitação de pull direcionada a:
- Um branch chamado
main
(refs/heads/main
) - Um branch chamado
mona/octocat
(refs/heads/mona/octocat
) - Um branch cujo nome começa com
releases/
, comoreleases/10
(refs/heads/releases/10
)
on:
pull_request:
# Sequence of patterns matched against refs/heads
branches:
- main
- 'mona/octocat'
- 'releases/**'
Exemplo: Excluir branches
Quando um padrão corresponder ao padrão branches-ignore
, o fluxo de trabalho não será executado. Os padrões definidos em branches
são avaliados em relação ao nome da referência do Git. Por exemplo, o seguinte fluxo de trabalho será executado sempre que houver um evento pull_request
, a menos que a solicitação de pull seja direcionada a:
- Um branch chamado
mona/octocat
(refs/heads/mona/octocat
) - Um branch cujo nome corresponde a
releases/**-alpha
, comoreleases/beta/3-alpha
(refs/heads/releases/beta/3-alpha
)
on:
pull_request:
# Sequence of patterns matched against refs/heads
branches-ignore:
- 'mona/octocat'
- 'releases/**-alpha'
Exemplo: Incluindo e excluindo branches
Não é possível usar branches
e branches-ignore
para filtrar o mesmo evento em um só fluxo de trabalho. Caso deseje incluir e excluir padrões de branch para um só evento, use o filtro branches
com o caractere !
para indicar os branches que devem ser excluídos.
Se você definir um branch com o caractere !
, também precisará definir, pelo menos, um branch sem o caractere !
. Caso deseje apenas excluir os branches, use branches-ignore
.
A ordem na qual você define os padrões é importante.
- Um padrão de correspondência negativa (precedido por
!
) após uma correspondência positiva excluirá a referência do Git. - Um padrão positivo correspondente após uma correspondência negativa incluirá a Git ref novamente.
O fluxo de trabalho a seguir será executado em eventos pull_request
para solicitações de pull direcionadas a releases/10
ou releases/beta/mona
, mas não para solicitações de pull direcionadas a releases/10-alpha
ou releases/beta/3-alpha
, porque o padrão !releases/**-alpha
negativo segue o padrão positivo.
on:
pull_request:
branches:
- 'releases/**'
- '!releases/**-alpha'
on.push.<branches|tags|branches-ignore|tags-ignore>
Ao usar o evento push
, você pode configurar um fluxo de trabalho para ser executado em marcas ou em branches específicos.
Use o filtro branches
quando quiser incluir padrões de nomes de branches ou quando quiser incluir e excluir padrões de nomes de branches. Use o filtro branches-ignore
quando quiser excluir apenas padrões de nomes de branches. Não é possível usar os filtros branches
e branches-ignore
para o mesmo evento em um fluxo de trabalho.
Use o filtro tags
quando quiser incluir padrões de nomes de marcas ou quando quiser incluir e excluir padrões de nomes de marcas. Use o filtro tags-ignore
quando quiser excluir apenas padrões de nomes de marcas. Não é possível usar os filtros tags
e tags-ignore
para o mesmo evento em um fluxo de trabalho.
Se você definir apenas tags
/tags-ignore
ou apenas branches
/branches-ignore
, o fluxo de trabalho não será executado para eventos que afetam a referência indefinida do Git. Se você não definir tags
/tags-ignore
nem branches
/branches-ignore
, o fluxo de trabalho será executado para eventos que afetam branches ou marcas. Se você definir branches
/branches-ignore
e paths
, o fluxo de trabalho só será executado quando ambos os filtros forem atendidos.
As palavras-chave branches
, branches-ignore
, tags
e tags-ignore
aceitam padrões glob que usam caracteres como *
, **
, +
, ?
, !
e outros para corresponder a mais de um nome de marca ou de branch. Se um nome contiver um desses caracteres e você quiser ter uma correspondência literal, faça escape de cada um desses caracteres especiais com \
. Para obter mais informações sobre padrões glob, confira a "Folha de referências de padrões de filtro".
Exemplo: Incluindo branches e tags
Os padrões definidos em branches
e tags
são avaliados em relação ao nome de referência do Git. Por exemplo, o seguinte fluxo de trabalho será executado sempre que houver um evento push
para:
- Um branch chamado
main
(refs/heads/main
) - Um branch chamado
mona/octocat
(refs/heads/mona/octocat
) - Um branch cujo nome começa com
releases/
, comoreleases/10
(refs/heads/releases/10
) - Uma marca chamada
v2
(refs/tags/v2
) - Uma marca cujo nome começa com
v1.
, comov1.9.1
(refs/tags/v1.9.1
)
on:
push:
# Sequence of patterns matched against refs/heads
branches:
- main
- 'mona/octocat'
- 'releases/**'
# Sequence of patterns matched against refs/tags
tags:
- v2
- v1.*
Exemplo: Excluindo branches e tags
Quando um padrão corresponder ao padrão branches-ignore
ou tags-ignore
, o fluxo de trabalho não será executado. Os padrões definidos em branches
e tags
são avaliados em relação ao nome de referência do Git. Por exemplo, o seguinte fluxo de trabalho será executado sempre que houver um evento push
, a menos que o evento push
seja para:
- Um branch chamado
mona/octocat
(refs/heads/mona/octocat
) - Um branch cujo nome corresponde a
releases/**-alpha
, comobeta/3-alpha
(refs/releases/beta/3-alpha
) - Uma marca chamada
v2
(refs/tags/v2
) - Uma marca cujo nome começa com
v1.
, comov1.9
(refs/tags/v1.9
)
on:
push:
# Sequence of patterns matched against refs/heads
branches-ignore:
- 'mona/octocat'
- 'releases/**-alpha'
# Sequence of patterns matched against refs/tags
tags-ignore:
- v2
- v1.*
Exemplo: Incluindo e excluindo branches e tags
Não é possível usar branches
e branches-ignore
para filtrar o mesmo evento em um fluxo de trabalho individual. Da mesma forma, não é possível usar tags
e tags-ignore
para filtrar o mesmo evento em um fluxo de trabalho individual. Caso deseje incluir e excluir padrões de branch para um evento individual, use o filtro branches
ou tags
com o caractere !
para indicar as marcas ou os branches que devem ser excluídos.
Se você definir um branch com o caractere !
, também precisará definir, pelo menos, um branch sem o caractere !
. Caso deseje apenas excluir os branches, use branches-ignore
. Da mesma forma, se você definir uma marca com o caractere !
, também precisará definir, pelo menos, uma marca sem o caractere !
. Caso deseje apenas excluir as marcas, use tags-ignore
.
A ordem na qual você define os padrões é importante.
- Um padrão de correspondência negativa (precedido por
!
) após uma correspondência positiva excluirá a referência do Git. - Um padrão positivo correspondente após uma correspondência negativa incluirá a Git ref novamente.
O fluxo de trabalho a seguir será executado em pushes para releases/10
ou releases/beta/mona
, mas não em releases/10-alpha
ou releases/beta/3-alpha
porque o padrão !releases/**-alpha
negativo vem após o padrão positivo.
on:
push:
branches:
- 'releases/**'
- '!releases/**-alpha'
on.<push|pull_request|pull_request_target>.<paths|paths-ignore>
Ao usar os eventos push
e pull_request
, você pode configurar um fluxo de trabalho para ser executado com base nos caminhos de arquivo alterados. Os filtros de caminho não são avaliados em pushes de tags.
Use o filtro paths
quando quiser incluir padrões de caminho de arquivo ou quando quiser incluir e excluir padrões de caminho de arquivo. Use o filtro paths-ignore
quando quiser apenas excluir padrões de caminho de arquivo. Não é possível usar os filtros paths
e paths-ignore
para o mesmo evento em um fluxo de trabalho.
Se você definir branches
/branches-ignore
e paths
, o fluxo de trabalho só será executado quando ambos os filtros forem atendidos.
As palavras-chave paths
e paths-ignore
aceitam padrões glob que usam os caracteres curinga *
e **
para fazer a correspondência com mais de um nome de caminho. Para obter mais informações, confira a "Folha de referências de padrões de filtro".
Exemplo: Incluindo caminhos
Se, pelo menos, um caminho corresponder a um padrão no filtro paths
, o fluxo de trabalho será executado. Por exemplo, o fluxo de trabalho a seguir será executado sempre que você efetuar push de um arquivo JavaScript (.js
).
on:
push:
paths:
- '**.js'
Observação: se um fluxo de trabalho for ignorado devido � filtragem de caminho, � filtragem de branch ou a uma mensagem de commit, as verificações associadas a esse fluxo de trabalho permanecerão em um estado "Pendente". Uma solicitação de pull que exige que essas verificações sejam bem-sucedidas não poderá ser mesclada. Para obter mais informações, confira "Como lidar com verificações ignoradas mas obrigatórias".
Exemplo: Excluindo caminhos
Quando todos os nomes de caminho corresponderem aos padrões de paths-ignore
, o fluxo de trabalho não será executado. Se qualquer nome de caminho não corresponder aos padrões de paths-ignore
, mesmo que alguns nomes de caminho correspondam aos padrões, o fluxo de trabalho será executado.
Um fluxo de trabalho com o filtro de caminho a seguir só será executado em eventos push
que incluem, pelo menos, um arquivo fora do diretório docs
na raiz do repositório.
on:
push:
paths-ignore:
- 'docs/**'
Exemplo: Incluindo e excluindo caminhos
Não é possível usar paths
e paths-ignore
para filtrar o mesmo evento em um fluxo de trabalho individual. Caso deseje incluir e excluir padrões de caminho para um evento individual, use o filtro paths
com o caractere !
para indicar os caminhos que devem ser excluídos.
Se você definir um caminho com o caractere !
, também precisará definir, pelo menos, um caminho sem o caractere !
. Caso você deseje apenas excluir os caminhos, use paths-ignore
.
A ordem de definição dos padrões é importante:
- Um padrão de correspondência negativa (precedido por
!
) após uma correspondência positiva excluirá o caminho do Git. - Um padrão positivo correspondente após uma correspondência negativa incluirá o caminho novamente.
Este exemplo é executado sempre que o evento push
inclui um arquivo no diretório sub-project
ou nos respectivos subdiretórios, a menos que o arquivo esteja no diretório sub-project/docs
. Por exemplo, um push que alterar sub-project/index.js
ou sub-project/src/index.js
vai disparar uma execução de fluxo de trabalho, mas um push que só altera sub-project/docs/readme.md
não.
on:
push:
paths:
- 'sub-project/**'
- '!sub-project/docs/**'
Comparações Git diff
Observação: se você efetuar push de mais de mil commits ou se o GitHub não gerar a comparação devido a um tempo limite, o fluxo de trabalho sempre será executado.
O filtro determina se um fluxo de trabalho deve ser executado avaliando os arquivos alterados e executando-os na lista paths-ignore
ou paths
. Se não houver arquivos alterados, o fluxo de trabalho não será executado.
O GitHub gera a lista de arquivos alterados usando diffs de dois pontos para pushes e diffs de três pontos para pull requests:
- Solicitações de pull: as comparações de três pontos são uma comparação entre a versão mais recente do branch do tópico e o commit em que o branch do tópico foi sincronizado pela última vez com o branch base.
- Pushes para branches existentes: uma comparação de dois pontos compara os SHAs principal e base diretamente um com o outro.
- Pushes para novos branches: uma comparação de dois pontos com o pai do ancestral do commit mais profundo enviado por push.
Os diffs limitam-se a 300 arquivos. Se houver arquivos alterados que não correspondam aos primeiros 300 arquivos retornados pelo filtro, o fluxo de trabalho não será executado. Talvez seja necessário criar filtros mais específicos para que o fluxo de trabalho seja executado automaticamente.
Para obter mais informações, confira "Sobre a comparação de branches em solicitações de pull".
on.schedule
Use on.schedule
para definir um agendamento de tempo para seus fluxos de trabalho. Você pode agendar um fluxo de trabalho para ser executado em horários UTC específicos usando a sintaxe cron POSIX. Fluxos de trabalho agendados executados no último commit no branch padrão ou branch de base. O intervalo mais curto que você pode executar fluxos de trabalho agendados é a cada 5 minutos.
Este exemplo aciona o fluxo de trabalho todos os dias � s 17:30 e 17:30 UTC:
on:
schedule:
# * is a special character in YAML so you have to quote this string
- cron: '30 5,17 * * *'
Um fluxo de trabalho individual pode ser disparado por vários eventos schedule
. Você pode acessar o evento de agendamento que disparou o fluxo de trabalho por meio do contexto github.event.schedule
. Este exemplo dispara o fluxo de trabalho a ser executado � s 5h30 UTC todas as segundas e quintas, mas ignora a etapa Not on Monday or Wednesday
� s segundas e quartas.
on:
schedule:
- cron: '30 5 * * 1,3'
- cron: '30 5 * * 2,4'
jobs:
test_schedule:
runs-on: ubuntu-latest
steps:
- name: Not on Monday or Wednesday
if: github.event.schedule != '30 5 * * 1,3'
run: echo "This step will be skipped on Monday and Wednesday"
- name: Every time
run: echo "This step will always run"
Para obter mais informações sobre a sintaxe cron, confira "Eventos que disparam fluxos de trabalho".
on.workflow_run.<branches|branches-ignore>
Ao usar o evento workflow_run
, você pode especificar os branches nos quais o fluxo de trabalho de gatilho precisa ser executado para disparar o fluxo de trabalho.
Os filtros branches
e branches-ignore
aceitam padrões glob que usam caracteres como *
, **
, +
, ?
, !
e outros para corresponder a mais de um nome de branch. Se um nome contiver um desses caracteres e você quiser ter uma correspondência literal, faça escape de cada um desses caracteres especiais com \
. Para obter mais informações sobre padrões glob, confira a "Folha de referências de padrões de filtro".
Por exemplo, um fluxo de trabalho com o seguinte gatilho só será executado quando o fluxo de trabalho chamado Build
for executado em um branch cujo nome começa com releases/
:
on:
workflow_run:
workflows: ["Build"]
types: [requested]
branches:
- 'releases/**'
Um fluxo de trabalho com o seguinte gatilho só será executado quando o fluxo de trabalho chamado Build
for executado em um branch que não seja chamado canary
:
on:
workflow_run:
workflows: ["Build"]
types: [requested]
branches-ignore:
- "canary"
Não é possível usar os filtros branches
e branches-ignore
para o mesmo evento em um fluxo de trabalho. Caso deseje incluir e excluir padrões de branch para um só evento, use o filtro branches
com o caractere !
para indicar os branches que devem ser excluídos.
A ordem na qual você define os padrões é importante.
- Um padrão de correspondência negativa (precedido por
!
) após uma correspondência positiva excluirá o branch. - Um padrão positivo correspondente após uma correspondência negativa incluirá o branch novamente.
Por exemplo, um fluxo de trabalho com o gatilho a seguir será executado quando o fluxo de trabalho chamado Build
for executado em um branch chamado releases/10
ou releases/beta/mona
que não será releases/10-alpha
, releases/beta/3-alpha
ou main
.
on:
workflow_run:
workflows: ["Build"]
types: [requested]
branches:
- 'releases/**'
- '!releases/**-alpha'
on.workflow_dispatch.inputs
When using the workflow_dispatch
event, you can optionally specify inputs that are passed to the workflow.
The triggered workflow receives the inputs in the github.event.inputs
context. For more information, see "Contexts."
on:
workflow_dispatch:
inputs:
logLevel:
description: 'Log level'
required: true
default: 'warning'
print_tags:
description: 'True to print to STDOUT'
required: true
tags:
description: 'Test scenario tags'
required: true
jobs:
print-tag:
runs-on: ubuntu-latest
if: ${{ github.event.inputs.print_tags == 'true' }}
steps:
- name: Print the input tag to STDOUT
run: echo The tags are ${{ github.event.inputs.tags }}
permissions
Use permissions
para modificar as permissões padrão concedidas ao GITHUB_TOKEN
, adicionando ou removendo o acesso conforme necessário, de modo que você só permita o acesso mínimo necessário. Para obter mais informações, confira "Autenticação em um fluxo de trabalho".
Use permissions
como uma chave de nível superior a ser aplicada a todos os trabalhos no fluxo de trabalho ou em trabalhos específicos. Quando você adiciona a chave permissions
a um trabalho específico, todas as ações e os comandos de execução nesse trabalho que usam o GITHUB_TOKEN
obtêm os direitos de acesso especificados. Para obter mais informações, confira jobs.<job_id>.permissions
.
Valores de acesso e escopos disponíveis:
permissions:
actions: read|write|none
checks: read|write|none
contents: read|write|none
deployments: read|write|none
issues: read|write|none
discussions: read|write|none
packages: read|write|none
pages: read|write|none
pull-requests: read|write|none
repository-projects: read|write|none
security-events: read|write|none
statuses: read|write|none
Se você especificar o acesso para um desses escopos, todos aqueles que não são especificados serão definidos como none
.
Você pode usar a sintaxe a seguir para definir o acesso de leitura ou gravação para todos os escopos disponíveis:
permissions: read-all|write-all
Você pode usar a seguinte sintaxe para desabilitar as permissões para todos os escopos disponíveis:
permissions: {}
``` Além disso, você pode usar a chave `permissions` para adicionar e remover permissões de leitura para repositórios com fork, mas normalmente não pode permitir acesso de gravação. A exceção desse comportamento é quando um usuário administrador selecionou a opção **Enviar tokens para fluxos de trabalho de solicitações de pull** nas configurações do GitHub Actions. Para obter mais informações, confira "[Como gerenciar as configurações do GitHub Actions de um repositório](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#enabling-workflows-for-private-repository-forks)".
### Exemplo: Atribuindo permissões ao GITHUB_TOKEN
Este exemplo mostra as permissões que estão sendo definidas para o `GITHUB_TOKEN` que se aplicará a todos os trabalhos no fluxo de trabalho. É concedido acesso de leitura a todas as permissões.
```yaml
name: "My workflow"
on: [ push ]
permissions: read-all
jobs:
...
env
A map
of environment variables that are available to the steps of all jobs in the workflow. You can also set environment variables that are only available to the steps of a single job or to a single step. For more information, see jobs.<job_id>.env
and jobs.<job_id>.steps[*].env
.
Variables in the env
map cannot be defined in terms of other variables in the map.
Quando mais de uma variável de ambiente é definida com o mesmo nome, GitHub usa a variável de ambiente mais específica. Por exemplo, uma variável de ambiente definida em uma etapa substituirá variáveis de trabalho e de fluxo de trabalho pelo mesmo nome enquanto a etapa é executada. Uma variável definida para um trabalho substituirá uma variável de fluxo de trabalho com o mesmo nome, enquanto o trabalho é executado.
Example
env:
SERVER: production
defaults
Use defaults
para criar um map
das configurações padrão que será aplicado a todos os trabalhos do fluxo de trabalho. Você também pode definir as configurações-padrão disponíveis para um trabalho. Para obter mais informações, confira jobs.<job_id>.defaults
.
Quando mais de uma configuração padrão é definida com o mesmo nome, GitHub usa a configuração padrão mais específica. Por exemplo, uma configuração padrão definida em uma tarefa irá substituir uma configuração padrão que tem o mesmo nome definido em um fluxo de trabalho.
defaults.run
Você pode usar defaults.run
para fornecer as opções shell
e working-directory
padrão para todas as etapas do run
em um fluxo de trabalho. Você também pode definir configurações padrão para run
as quais só estão disponíveis para um trabalho. Para obter mais informações, confira jobs.<job_id>.defaults.run
. Você não pode usar contextos ou expressões nesta palavra-chave.
Quando mais de uma configuração padrão é definida com o mesmo nome, GitHub usa a configuração padrão mais específica. Por exemplo, uma configuração padrão definida em uma tarefa irá substituir uma configuração padrão que tem o mesmo nome definido em um fluxo de trabalho.
Exemplo: Defina o shell padrão e o diretório de trabalho
defaults:
run:
shell: bash
working-directory: scripts
concurrency
Use concurrency
para garantir que apenas um trabalho ou um fluxo de trabalho que usa o mesmo grupo de simultaneidade seja executado por vez. Um grupo de concorrência pode ser qualquer string ou expressão. A expressão só pode usar o contexto github
. Para obter mais informações sobre expressões, confira "Expressões".
Você também pode especificar concurrency
no nível do trabalho. Para obter mais informações, confira jobs.<job_id>.concurrency
.
Quando um trabalho ou um fluxo de trabalho simultâneo é colocado na fila, se outro trabalho ou fluxo de trabalho que usa o mesmo grupo de simultaneidade no repositório estiver em andamento, o trabalho ou o fluxo de trabalho na fila ficará pending
. Qualquer trabalho ou fluxo de trabalho anterior pendente no grupo de concorrência será cancelado. Para também cancelar qualquer trabalho ou fluxo de trabalho em execução no mesmo grupo de simultaneidade, especifique cancel-in-progress: true
.
Exemplos: Como usar a concorrência e o comportamento padrão
concurrency: staging_environment
concurrency: ci-${{ github.ref }}
Exemplo: Usar a concorrência para cancelar qualquer trabalho em andamento ou em execução
concurrency:
group: ${{ github.ref }}
cancel-in-progress: true
Exemplo: Usando um valor para segunda opção
Se você construir o nome do grupo com uma propriedade que só é definida para eventos específicos, você pode usar um valor de segunda opção. Por exemplo, github.head_ref
só é definido em eventos pull_request
. Se o fluxo de trabalho responder a outros eventos além de eventos pull_request
, você precisará fornecer um fallback para evitar um erro de sintaxe. O grupo de simultaneidade a seguir cancela os trabalhos em andamento ou é executado somente em eventos pull_request
. Se github.head_ref
for indefinido, o grupo de simultaneidade fará fallback para a ID de execução, que tem a garantia de ser exclusiva e definida para a execução.
concurrency:
group: ${{ github.head_ref || github.run_id }}
cancel-in-progress: true
Exemplo: Cancele somente trabalhos em andamento ou execuções no fluxo de trabalho atual
Se você tiver vários fluxos de trabalho no mesmo repositório, os nomes dos grupos de concorrência devem ser únicos em todos os fluxos de trabalho para evitar o cancelamento de trabalhos em andamento ou de executores a partir de outros fluxos de trabalho. Caso contrário, qualquer trabalho em andamento ou pendente será cancelado, independentemente do fluxo de trabalho.
Para cancelar apenas as execuções em andamento do mesmo fluxo de trabalho, use a propriedade github.workflow
para criar o grupo de simultaneidade:
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs
Uma execução de fluxo de trabalho é composta por um ou mais jobs
, que são executados em paralelo por padrão. Para executar trabalhos sequencialmente, você pode definir dependências em outros trabalhos usando a palavra-chave jobs.<job_id>.needs
.
Cada trabalho é executado em um ambiente do executor especificado por runs-on
.
Você pode executar quantos trabalhos desejar, desde que esteja dentro dos limites de uso do fluxo de trabalho. Para obter mais informações, confira "Limites de uso e cobrança" para executores hospedados no GitHub e "Sobre os executores auto-hospedados" para saber os limites de uso dos executores auto-hospedados.
Se precisar encontrar o identificador exclusivo de uma tarefa em execução em um fluxo de trabalho, você poderá usar a API de GitHub Enterprise Server. Para obter mais informações, confira "Trabalhos de fluxo de trabalho".
jobs.<job_id>
Use jobs.<job_id>
para fornecer ao seu trabalho um identificador exclusivo. A chave job_id
é uma cadeia de caracteres, e o valor dela é um mapa dos dados de configuração do trabalho. Você precisa substituir <job_id>
por uma cadeia de caracteres exclusiva para o objeto jobs
. A <job_id>
precisa começar com uma letra ou _
e conter apenas caracteres alfanuméricos, -
ou _
.
Exemplo: Criando trabalhos
Neste exemplo, dois trabalhos foram criados, e os valores de job_id
são my_first_job
e my_second_job
.
jobs:
my_first_job:
name: My first job
my_second_job:
name: My second job
jobs.<job_id>.name
Use jobs.<job_id>.name
para definir um nome para o trabalho, que é exibido na interface do usuário do GitHub.
jobs.<job_id>.permissions
Para um trabalho específico, você pode usar jobs.<job_id>.permissions
para modificar as permissões padrão concedidas ao GITHUB_TOKEN
, adicionando ou removendo o acesso conforme necessário, para que você permita apenas o acesso mínimo necessário. Para obter mais informações, confira "Autenticação em um fluxo de trabalho".
Ao especificar a permissão em uma definição de trabalho, você pode configurar um conjunto diferente de permissões para o GITHUB_TOKEN
em cada trabalho, se necessário. Como alternativa, você pode especificar as permissões para todas as tarefas do fluxo de trabalho. Para obter informações sobre como definir permissões no nível do fluxo de trabalho, confira permissions
.
Valores de acesso e escopos disponíveis:
permissions:
actions: read|write|none
checks: read|write|none
contents: read|write|none
deployments: read|write|none
issues: read|write|none
discussions: read|write|none
packages: read|write|none
pages: read|write|none
pull-requests: read|write|none
repository-projects: read|write|none
security-events: read|write|none
statuses: read|write|none
Se você especificar o acesso para um desses escopos, todos aqueles que não são especificados serão definidos como none
.
Você pode usar a sintaxe a seguir para definir o acesso de leitura ou gravação para todos os escopos disponíveis:
permissions: read-all|write-all
Você pode usar a seguinte sintaxe para desabilitar as permissões para todos os escopos disponíveis:
permissions: {}
``` Além disso, você pode usar a chave `permissions` para adicionar e remover permissões de leitura para repositórios com fork, mas normalmente não pode permitir acesso de gravação. A exceção desse comportamento é quando um usuário administrador selecionou a opção **Enviar tokens para fluxos de trabalho de solicitações de pull** nas configurações do GitHub Actions. Para obter mais informações, confira "[Como gerenciar as configurações do GitHub Actions de um repositório](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#enabling-workflows-for-private-repository-forks)".
#### Exemplo: Configurar permissões para um trabalho específico
Este exemplo mostra as permissões que estão sendo definidas para o `GITHUB_TOKEN` que se aplicará somente ao trabalho chamado `stale`. O acesso de gravação é permitido para os escopos `issues` e `pull-requests`. Todos os outros escopos não terão acesso.
```yaml
jobs:
stale:
runs-on: ubuntu-latest
permissions:
issues: write
pull-requests: write
steps:
- uses: actions/stale@v4
jobs.<job_id>.needs
Use jobs.<job_id>.needs
para identificar todos os trabalhos que precisam ser concluídos com êxito antes que este trabalho seja executado. Esse código pode ser uma string ou array de strings. Se houver falha em um trabalho, todos os trabalhos que dependem dele serão ignorados, a menos que os trabalhos usem uma expressão condicional que faça o trabalho continuar. Se uma execução contiver uma série de trabalhos que precisem uns dos outros, uma falha se aplicará a todos os trabalhos na cadeia de dependência do ponto de falha em diante.
Exemplo: Exigindo trabalhos dependentes com sucesso
jobs:
job1:
job2:
needs: job1
job3:
needs: [job1, job2]
Neste exemplo, job1
precisa ser concluído com êxito antes que job2
seja iniciado, e job3
aguarda a conclusão de job1
e de job2
.
Os trabalhos neste exemplo são executados sequencialmente:
job1
job2
job3
Exemplo: Não exigindo trabalhos dependentes com sucesso
jobs:
job1:
job2:
needs: job1
job3:
if: ${{ always() }}
needs: [job1, job2]
Neste exemplo, job3
usa a expressão condicional always()
para que ela sempre seja executada após a conclusão de job1
e de job2
, independentemente de elas terem sido bem-sucedidas. Para obter mais informações, confira "Expressões".
jobs.<job_id>.if
Use o condicional jobs.<job_id>.if
para impedir que um trabalho seja executado, a não ser que uma condição seja atendida. Você pode usar qualquer contexto e expressão compatível para criar uma condicional.
Ao usar expressões em um condicional if
, você pode omitir a sintaxe de expressão (${{ }}
), porque o GitHub avalia automaticamente o condicional if
como uma expressão. Para obter mais informações, confira "Expressões".
Exemplo: Somente executar o trabalho para um repositório específico
Este exemplo usa if
para controlar quando o trabalho production-deploy
pode ser executado. Ele só será executado se o repositório for chamado octo-repo-prod
e estiver na organização octo-org
. Caso contrário, o trabalho será marcado como ignorado.
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 computador no qual o trabalho será executado. Você pode fornecer runs-on
como uma cadeia de caracteres individual ou como uma matriz de cadeias de caracteres. Se você especificar uma matriz de cadeias de caracteres, seu fluxo de trabalho será executado em um executor auto-hospedado cujos rótulos correspondem a todos os valores runs-on
especificados, se disponíveis. Se você quiser executar seu fluxo de trabalho em vários computadores, use jobs.<job_id>.strategy
.
Observação: no momento, não há suporte para os executores hospedados no GitHub no GitHub Enterprise Server. Você pode ver mais informações sobre o suporte futuro planejado no GitHub public roadmap.
Escolhendo executores hospedados em GitHub
Se você usar um executor hospedado no GitHub, cada trabalho será executado em uma nova instância de uma imagem do executor especificada por runs-on
.
Os tipos de executor disponíveis para GitHub são:
Imagem do executor | Rótulo de fluxo de trabalho YAML | Observações |
---|---|---|
Windows Server 2022 | windows-latest ou windows-2022 |
Atualmente, o rótulo windows-latest usa a imagem do executor do Windows Server 2022.
|
Windows Server 2019 | windows-2019 |
|
Ubuntu 22.04 | ubuntu-22.04 |
|
Ubuntu 20.04 | ubuntu-latest ou ubuntu-20.04 |
|
Ubuntu 18.04 [preterido] | ubuntu-18.04 |
Migre para ubuntu-20.04 ou ubuntu-22.04 . Para saber mais, confira esta postagem no blog do GitHub.
|
macOS Monterey 12 | macos-12 |
|
macOS Big Sur 11 | macos-latest ou macos-11 |
Atualmente, o rótulo macos-latest usa a imagem do executor do macOS 11.
|
macOS Catalina 10.15 [preterido] | macos-10.15 |
Migre para macOS-11 ou macOS-12 . Para saber mais, confira esta postagem no blog do GitHub.
|
Observação: as imagens do executor -latest
são as imagens estáveis mais recentes fornecidas pelo GitHub e talvez não seja a versão mais recente do sistema operacional disponível do fornecedor do sistema operacional.
Observação: as imagens beta e preteridas são fornecidas "no estado em que se encontram", "com todas as falhas" e "conforme disponível" e são excluídas do contrato de nível de serviço e da garantia. As imagens beta podem não ser cobertas pelo atendimento ao cliente.
Exemplo: Especificar um sistema operacional
runs-on: ubuntu-latest
Para obter mais informações, confira "Sobre os executores hospedados no GitHub".
Escolhendo executores auto-hospedados
Para especificar um executor auto-hospedado para seu trabalho, configure runs-on
no arquivo de fluxo de trabalho com rótulos do executor auto-hospedado.
Todos os executores auto-hospedados têm o rótulo self-hosted
. Se você só usar esse rótulo, isso selecionará qualquer executor auto-hospedado. Para selecionar os executores que atendem a determinados critérios, como sistema operacional ou arquitetura, recomendamos fornecer uma matriz de rótulos que começa com self-hosted
(isso precisa ser listado primeiro) e, em seguida, inclui rótulos adicionais, conforme necessário. Quando você especificar uma matriz de rótulos, os trabalhos serão colocados na fila nos executores que têm todos os rótulos especificados.
Embora o rótulo self-hosted
não seja necessário, recomendamos fortemente especificá-lo ao usar executores auto-hospedados para garantir que o seu trabalho não especifique acidentalmente nenhum executor atual ou futuro hospedado no GitHub.
Exemplo: Usando etiquetas para seleção do executor
runs-on: [self-hosted, linux]
Para obter mais informações, confira "Sobre executores auto-hospedados" e "Como usar executores auto-hospedados em um fluxo de trabalho".
jobs.<job_id>.environment
Use jobs.<job_id>.environment
para definir o ambiente que o trabalho referencia. Todas as regras de proteção do ambiente têm de ser aprovadas para que um trabalho que faça referência ao ambiente seja enviado a um executor. Para obter mais informações, confira "Como usar ambientes para implantação".
Você pode fornecer o ambiente como apenas o ambiente name
ou como um objeto de ambiente com o name
e a url
. A URL é mapeada para environment_url
na a API de implantações. Para obter mais informações sobre a API de implantações, confira "Implantações".
Exemplo: Usando um único nome de ambiente
environment: staging_environment
Exemplo: Usando o nome de ambiente e URL
environment:
name: production_environment
url: https://github.com
A URL pode ser uma expressão e pode usar qualquer contexto, exceto o contexto secrets
. Para obter mais informações sobre expressões, confira "Expressões".
Exemplo: Usando a saída como URL
environment:
name: production_environment
url: ${{ steps.step_id.outputs.url_output }}
jobs.<job_id>.concurrency
Observação: quando a simultaneidade é especificada no nível do trabalho, a ordem não é garantida para execuções ou trabalhos que são colocados na fila em intervalos de cinco minutos com relação um ao outro.
Você pode usar jobs.<job_id>.concurrency
para garantir que apenas um trabalho ou fluxo de trabalho que usa o mesmo grupo de simultaneidade seja executado por vez. Um grupo de concorrência pode ser qualquer string ou expressão. A expressão pode usar qualquer contexto, exceto o contexto secrets
. Para obter mais informações sobre expressões, confira "Expressões".
Especifique também concurrency
no nível do fluxo de trabalho. Para obter mais informações, confira concurrency
.
Quando um trabalho ou um fluxo de trabalho simultâneo é colocado na fila, se outro trabalho ou fluxo de trabalho que usa o mesmo grupo de simultaneidade no repositório estiver em andamento, o trabalho ou o fluxo de trabalho na fila ficará pending
. Qualquer trabalho ou fluxo de trabalho anterior pendente no grupo de concorrência será cancelado. Para também cancelar qualquer trabalho ou fluxo de trabalho em execução no mesmo grupo de simultaneidade, especifique cancel-in-progress: true
.
Exemplos: Como usar a concorrência e o comportamento padrão
concurrency: staging_environment
concurrency: ci-${{ github.ref }}
Exemplo: Usar a concorrência para cancelar qualquer trabalho em andamento ou em execução
concurrency:
group: ${{ github.ref }}
cancel-in-progress: true
Exemplo: Usando um valor para segunda opção
Se você construir o nome do grupo com uma propriedade que só é definida para eventos específicos, você pode usar um valor de segunda opção. Por exemplo, github.head_ref
só é definido em eventos pull_request
. Se o fluxo de trabalho responder a outros eventos além de eventos pull_request
, você precisará fornecer um fallback para evitar um erro de sintaxe. O grupo de simultaneidade a seguir cancela os trabalhos em andamento ou é executado somente em eventos pull_request
. Se github.head_ref
for indefinido, o grupo de simultaneidade fará fallback para a ID de execução, que tem a garantia de ser exclusiva e definida para a execução.
concurrency:
group: ${{ github.head_ref || github.run_id }}
cancel-in-progress: true
Exemplo: Cancele somente trabalhos em andamento ou execuções no fluxo de trabalho atual
Se você tiver vários fluxos de trabalho no mesmo repositório, os nomes dos grupos de concorrência devem ser únicos em todos os fluxos de trabalho para evitar o cancelamento de trabalhos em andamento ou de executores a partir de outros fluxos de trabalho. Caso contrário, qualquer trabalho em andamento ou pendente será cancelado, independentemente do fluxo de trabalho.
Para cancelar apenas as execuções em andamento do mesmo fluxo de trabalho, use a propriedade github.workflow
para criar o grupo de simultaneidade:
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs.<job_id>.outputs
You can use jobs.<job_id>.outputs
to create a map
of outputs for a job. Job outputs are available to all downstream jobs that depend on this job. For more information on defining job dependencies, see jobs.<job_id>.needs
.
As saídas são cadeias de caracteres Unicode e podem ter no máximo 1 MB. O total de todas as saídas em uma execução de fluxo de trabalho pode ter no máximo 50 MB.
Job outputs containing expressions are evaluated on the runner at the end of each job. Outputs containing secrets are redacted on the runner and not sent to GitHub Actions.
To use job outputs in a dependent job, you can use the needs
context. For more information, see "Contexts."
Example: Defining outputs for a job
jobs:
job1:
runs-on: ubuntu-latest
# Map a step output to a job output
outputs:
output1: ${{ steps.step1.outputs.test }}
output2: ${{ steps.step2.outputs.test }}
steps:
- id: step1
run: echo "::set-output name=test::hello"
- id: step2
run: echo "::set-output name=test::world"
job2:
runs-on: ubuntu-latest
needs: job1
steps:
- run: echo ${{needs.job1.outputs.output1}} ${{needs.job1.outputs.output2}}
jobs.<job_id>.env
A map
of environment variables that are available to all steps in the job. You can also set environment variables for the entire workflow or an individual step. For more information, see env
and jobs.<job_id>.steps[*].env
.
Quando mais de uma variável de ambiente é definida com o mesmo nome, GitHub usa a variável de ambiente mais específica. Por exemplo, uma variável de ambiente definida em uma etapa substituirá variáveis de trabalho e de fluxo de trabalho pelo mesmo nome enquanto a etapa é executada. Uma variável definida para um trabalho substituirá uma variável de fluxo de trabalho com o mesmo nome, enquanto o trabalho é executado.
Example
jobs:
job1:
env:
FIRST_NAME: Mona
jobs.<job_id>.defaults
Use jobs.<job_id>.defaults
para criar um map
das configurações padrão que será aplicado a todas as etapas do trabalho. Você também pode definir as configurações-padrão para todo o fluxo de trabalho. Para obter mais informações, confira defaults
.
Quando mais de uma configuração padrão é definida com o mesmo nome, GitHub usa a configuração padrão mais específica. Por exemplo, uma configuração padrão definida em uma tarefa irá substituir uma configuração padrão que tem o mesmo nome definido em um fluxo de trabalho.
jobs.<job_id>.defaults.run
Use jobs.<job_id>.defaults.run
para fornecer o shell
e o working-directory
padrão para todas as etapas run
do trabalho. Não são permitidos contexto e expressão nesta seção.
Você pode fornecer as opções shell
e working-directory
padrão para todas as etapas run
de um trabalho. Também pode definir as configurações padrão para run
em todo o fluxo de trabalho. Para obter mais informações, confira jobs.defaults.run
. Você não pode usar contextos ou expressões nesta palavra-chave.
Quando mais de uma configuração padrão é definida com o mesmo nome, GitHub usa a configuração padrão mais específica. Por exemplo, uma configuração padrão definida em uma tarefa irá substituir uma configuração padrão que tem o mesmo nome definido em um fluxo de trabalho.
Exemplo: definição das opções da etapa run
padrão para um trabalho
jobs:
job1:
runs-on: ubuntu-latest
defaults:
run:
shell: bash
working-directory: scripts
jobs.<job_id>.steps
A job contains a sequence of tasks called steps
. Steps can run commands, run setup tasks, or run an action in your repository, a public repository, or an action published in a Docker registry. Not all steps run actions, but all actions run as a step. Each step runs in its own process in the runner environment and has access to the workspace and filesystem. Because steps run in their own process, changes to environment variables are not preserved between steps. GitHub provides built-in steps to set up and complete a job.
You can run an unlimited number of steps as long as you are within the workflow usage limits. For more information, see "Usage limits and billing" for GitHub-hosted runners and "About self-hosted runners" for self-hosted runner usage limits.
Example
name: Greeting from Mona
on: push
jobs:
my-job:
name: My Job
runs-on: ubuntu-latest
steps:
- name: Print a greeting
env:
MY_VAR: Hi there! My name is
FIRST_NAME: Mona
MIDDLE_NAME: The
LAST_NAME: Octocat
run: |
echo $MY_VAR $FIRST_NAME $MIDDLE_NAME $LAST_NAME.
jobs.<job_id>.steps[*].id
A unique identifier for the step. You can use the id
to reference the step in contexts. For more information, see "Contexts."
jobs.<job_id>.steps[*].if
You can use the if
conditional to prevent a step from running unless a condition is met. You can use any supported context and expression to create a conditional.
Ao usar expressões em um condicional if
, você pode omitir a sintaxe de expressão (${{ }}
), porque o GitHub avalia automaticamente o condicional if
como uma expressão. For more information, see "Expressions."
Example: Using contexts
This step only runs when the event type is a pull_request
and the event action is unassigned
.
steps:
- name: My first step
if: ${{ github.event_name == 'pull_request' && github.event.action == 'unassigned' }}
run: echo This event is a pull request that had an assignee removed.
Example: Using status check functions
The my backup step
only runs when the previous step of a job fails. For more information, see "Expressions."
steps:
- name: My first step
uses: octo-org/action-name@main
- name: My backup step
if: ${{ failure() }}
uses: actions/heroku@1.0.0
Example: Using secrets
Secrets cannot be directly referenced in if:
conditionals. Instead, consider setting secrets as job-level environment variables, then referencing the environment variables to conditionally run steps in the job.
If a secret has not been set, the return value of an expression referencing the secret (such as ${{ secrets.SuperSecret }}
in the example) will be an empty string.
name: Run a step if a secret has been set
on: push
jobs:
my-jobname:
runs-on: ubuntu-latest
env:
super_secret: ${{ secrets.SuperSecret }}
steps:
- if: ${{ env.super_secret != '' }}
run: echo 'This step will only run if the secret has a value set.'
- if: ${{ env.super_secret == '' }}
run: echo 'This step will only run if the secret does not have a value set.'
For more information, see "Context availability" and "Encrypted secrets."
jobs.<job_id>.steps[*].name
A name for your step to display on GitHub.
jobs.<job_id>.steps[*].uses
Selects an action to run as part of a step in your job. An action is a reusable unit of code. You can use an action defined in the same repository as the workflow, a public repository, or in a published Docker container image.
We strongly recommend that you include the version of the action you are using by specifying a Git ref, SHA, or Docker tag. If you don't specify a version, it could break your workflows or cause unexpected behavior when the action owner publishes an update.
- Using the commit SHA of a released action version is the safest for stability and security.
- If the action publishes major version tags, you should expect to receive critical fixes and security patches while still retaining compatibility. Note that this behavior is at the discretion of the action's author.
- Using the default branch of an action may be convenient, but if someone releases a new major version with a breaking change, your workflow could break.
Some actions require inputs that you must set using the with
keyword. Review the action's README file to determine the inputs required.
Actions are either JavaScript files or Docker containers. If the action you're using is a Docker container you must run the job in a Linux environment. For more details, see runs-on
.
Example: Using versioned actions
steps:
# Reference a specific commit
- uses: actions/checkout@a81bbbf8298c0fa03ea29cdc473d45769f953675
# Reference the major version of a release
- uses: actions/checkout@v2
# Reference a specific version
- uses: actions/checkout@v2.2.0
# Reference a branch
- uses: actions/checkout@main
Example: Using a public action
{owner}/{repo}@{ref}
You can specify a branch, ref, or SHA in a public GitHub repository.
jobs:
my_first_job:
steps:
- name: My first step
# Uses the default branch of a public repository
uses: actions/heroku@main
- name: My second step
# Uses a specific version tag of a public repository
uses: actions/aws@v2.0.1
Example: Using a public action in a subdirectory
{owner}/{repo}/{path}@{ref}
A subdirectory in a public GitHub repository at a specific branch, ref, or SHA.
jobs:
my_first_job:
steps:
- name: My first step
uses: actions/aws/ec2@main
Example: Using an action in the same repository as the workflow
./path/to/dir
The path to the directory that contains the action in your workflow's repository. You must check out your repository before using the action.
jobs:
my_first_job:
steps:
- name: Check out repository
uses: actions/checkout@v2
- name: Use local my-action
uses: ./.github/actions/my-action
Example: Using a Docker Hub action
docker://{image}:{tag}
A Docker image published on Docker Hub.
jobs:
my_first_job:
steps:
- name: My first step
uses: docker://alpine:3.8
Example: Using a Docker public registry action
docker://{host}/{image}:{tag}
A Docker image in a public registry. This example uses the Google Container Registry at gcr.io
.
jobs:
my_first_job:
steps:
- name: My first step
uses: docker://gcr.io/cloud-builders/gradle
Example: Using an action inside a different private repository than the workflow
Your workflow must checkout the private repository and reference the action locally. Generate a personal access token and add the token as an encrypted secret. For more information, see "Creating a personal access token" and "Encrypted secrets."
Replace PERSONAL_ACCESS_TOKEN
in the example with the name of your secret.
jobs:
my_first_job:
steps:
- name: Check out repository
uses: actions/checkout@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
Runs command-line programs using the operating system's shell. If you do not provide a name
, the step name will default to the text specified in the run
command.
Commands run using non-login shells by default. You can choose a different shell and customize the shell used to run commands. For more information, see jobs.<job_id>.steps[*].shell
.
Each run
keyword represents a new process and shell in the runner environment. When you provide multi-line commands, each line runs in the same shell. For example:
-
A single-line command:
- name: Install Dependencies run: npm install
-
A multi-line command:
- name: Clean install dependencies and build run: | npm ci npm run build
Using the working-directory
keyword, you can specify the working directory of where to run the command.
- name: Clean temp directory
run: rm -rf *
working-directory: ./temp
jobs.<job_id>.steps[*].shell
You can override the default shell settings in the runner's operating system using the shell
keyword. You can use built-in shell
keywords, or you can define a custom set of shell options. The shell command that is run internally executes a temporary file that contains the commands specified in the run
keyword.
Supported platform | shell parameter | Description | Command run internally |
---|---|---|---|
Linux / macOS | unspecified | The default shell on non-Windows platforms. Note that this runs a different command to when bash is specified explicitly. If bash is not found in the path, this is treated as sh . | bash -e {0} |
All | bash | The default shell on non-Windows platforms with a fallback to sh . When specifying a bash shell on Windows, the bash shell included with Git for Windows is used. | bash --noprofile --norc -eo pipefail {0} |
All | pwsh | The PowerShell Core. GitHub appends the extension .ps1 to your script name. | pwsh -command ". '{0}'" |
All | python | Executes the python command. | python {0} |
Linux / macOS | sh | The fallback behavior for non-Windows platforms if no shell is provided and bash is not found in the path. | sh -e {0} |
Windows | cmd | GitHub appends the extension .cmd to your script name and substitutes for {0} . | %ComSpec% /D /E:ON /V:OFF /S /C "CALL "{0}"" . |
Windows | pwsh | This is the default shell used on Windows. The PowerShell Core. GitHub appends the extension .ps1 to your script name. If your self-hosted Windows runner does not have PowerShell Core installed, then PowerShell Desktop is used instead. | pwsh -command ". '{0}'" . |
Windows | powershell | The PowerShell Desktop. GitHub appends the extension .ps1 to your script name. | powershell -command ". '{0}'" . |
Example: Running a script using bash
steps:
- name: Display the path
run: echo $PATH
shell: bash
Example: Running a script using Windows cmd
steps:
- name: Display the path
run: echo %PATH%
shell: cmd
Example: Running a script using PowerShell Core
steps:
- name: Display the path
run: echo ${env:PATH}
shell: pwsh
Example: Using PowerShell Desktop to run a script
steps:
- name: Display the path
run: echo ${env:PATH}
shell: powershell
Example: Running a python script
steps:
- name: Display the path
run: |
import os
print(os.environ['PATH'])
shell: python
Custom shell
You can set the shell
value to a template string using command […options] {0} [..more_options]
. GitHub interprets the first whitespace-delimited word of the string as the command, and inserts the file name for the temporary script at {0}
.
For example:
steps:
- name: Display the environment variables and their values
run: |
print %ENV
shell: perl {0}
The command used, perl
in this example, must be installed on the runner.
Exit codes and error action preference
For built-in shell keywords, we provide the following defaults that are executed by GitHub-hosted runners. You should use these guidelines when running shell scripts.
-
bash
/sh
:- Fail-fast behavior using
set -eo pipefail
: This option is set whenshell: bash
is explicitly specified. It is not applied by default. - You can take full control over shell parameters by providing a template string to the shell options. For example,
bash {0}
. - sh-like shells exit with the exit code of the last command executed in a script, which is also the default behavior for actions. The runner will report the status of the step as fail/succeed based on this exit code.
- Fail-fast behavior using
-
powershell
/pwsh
- Fail-fast behavior when possible. For
pwsh
andpowershell
built-in shell, we will prepend$ErrorActionPreference = 'stop'
to script contents. - We append
if ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE }
to powershell scripts so action statuses reflect the script's last exit code. - Users can always opt out by not using the built-in shell, and providing a custom shell option like:
pwsh -File {0}
, orpowershell -Command "& '{0}'"
, depending on need.
- Fail-fast behavior when possible. For
-
cmd
- There doesn't seem to be a way to fully opt into fail-fast behavior other than writing your script to check each error code and respond accordingly. Because we can't actually provide that behavior by default, you need to write this behavior into your script.
cmd.exe
will exit with the error level of the last program it executed, and it will return the error code to the runner. This behavior is internally consistent with the previoussh
andpwsh
default behavior and is thecmd.exe
default, so this behavior remains intact.
jobs.<job_id>.steps[*].with
A map
of the input parameters defined by the action. Each input parameter is a key/value pair. Input parameters are set as environment variables. The variable is prefixed with INPUT_
and converted to upper case.
Example
Defines the three input parameters (first_name
, middle_name
, and last_name
) defined by the hello_world
action. These input variables will be accessible to the hello-world
action as INPUT_FIRST_NAME
, INPUT_MIDDLE_NAME
, and INPUT_LAST_NAME
environment variables.
jobs:
my_first_job:
steps:
- name: My first step
uses: actions/hello_world@main
with:
first_name: Mona
middle_name: The
last_name: Octocat
jobs.<job_id>.steps[*].with.args
A string
that defines the inputs for a Docker container. GitHub passes the args
to the container's ENTRYPOINT
when the container starts up. An array of strings
is not supported by this parameter.
Example
steps:
- name: Explain why this job ran
uses: octo-org/action-name@main
with:
entrypoint: /bin/echo
args: The ${{ github.event_name }} event triggered this step.
The args
are used in place of the CMD
instruction in a Dockerfile
. If you use CMD
in your Dockerfile
, use the guidelines ordered by preference:
- Document required arguments in the action's README and omit them from the
CMD
instruction. - Use defaults that allow using the action without specifying any
args
. - If the action exposes a
--help
flag, or something similar, use that as the default to make your action self-documenting.
jobs.<job_id>.steps[*].with.entrypoint
Overrides the Docker ENTRYPOINT
in the Dockerfile
, or sets it if one wasn't already specified. Unlike the Docker ENTRYPOINT
instruction which has a shell and exec form, entrypoint
keyword accepts only a single string defining the executable to be run.
Example
steps:
- name: Run a custom command
uses: octo-org/action-name@main
with:
entrypoint: /a/different/executable
The entrypoint
keyword is meant to be used with Docker container actions, but you can also use it with JavaScript actions that don't define any inputs.
jobs.<job_id>.steps[*].env
Sets environment variables for steps to use in the runner environment. You can also set environment variables for the entire workflow or a job. For more information, see env
and jobs.<job_id>.env
.
Quando mais de uma variável de ambiente é definida com o mesmo nome, GitHub usa a variável de ambiente mais específica. Por exemplo, uma variável de ambiente definida em uma etapa substituirá variáveis de trabalho e de fluxo de trabalho pelo mesmo nome enquanto a etapa é executada. Uma variável definida para um trabalho substituirá uma variável de fluxo de trabalho com o mesmo nome, enquanto o trabalho é executado.
Public actions may specify expected environment variables in the README file. If you are setting a secret in an environment variable, you must set secrets using the secrets
context. For more information, see "Using environment variables" and "Contexts."
Example
steps:
- name: My first action
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
FIRST_NAME: Mona
LAST_NAME: Octocat
jobs.<job_id>.steps[*].continue-on-error
Prevents a job from failing when a step fails. Set to true
to allow a job to pass when this step fails.
jobs.<job_id>.steps[*].timeout-minutes
The maximum number of minutes to run the step before killing the process.
jobs.<job_id>.timeout-minutes
The maximum number of minutes to let a job run before GitHub automatically cancels it. Default: 360
If the timeout exceeds the job execution time limit for the runner, the job will be canceled when the execution time limit is met instead. For more information about job execution time limits, see "Usage limits and billing" for GitHub-hosted runners and "About self-hosted runners" for self-hosted runner usage limits.
Note: O GITHUB_TOKEN
expira quando um trabalho é concluído ou após, no máximo, 24 horas. For self-hosted runners, the token may be the limiting factor if the job timeout is greater than 24 hours. For more information on the GITHUB_TOKEN
, see "About the GITHUB_TOKEN
secret."
jobs.<job_id>.strategy
Use jobs.<job_id>.strategy
to use a matrix strategy for your jobs. Uma estratégia de matriz permite que você use variáveis em uma única definição de trabalho para criar automaticamente várias execuções de trabalho baseadas nas combinações das variáveis. Por exemplo, você pode usar uma estratégia de matriz para testar seu código em várias versões de um idioma ou em vários sistemas operacionais. For more information, see "Using a matrix for your jobs."
jobs.<job_id>.strategy.matrix
Use jobs.<job_id>.strategy.matrix
para definir uma matriz de diferentes configurações de trabalho. Dentro de sua matriz, defina uma ou mais variáveis seguidas por uma matriz de valores. Por exemplo, a matriz a seguir tem uma variável chamada version
com o valor [10, 12, 14]
e uma variável chamada os
com o valor [ubuntu-latest, windows-latest]
:
jobs:
example_matrix:
strategy:
matrix:
version: [10, 12, 14]
os: [ubuntu-latest, windows-latest]
Um trabalho será executado para cada combinação possível das variáveis. Neste exemplo, o fluxo de trabalho executará seis trabalhos, um para cada combinação das variáveis os
e version
.
Por padrão, o GitHub Enterprise Server maximizará o número de trabalhos executados em paralelo, dependendo da disponibilidade do executor. A ordem das variáveis na matriz determina a ordem na qual os trabalhos são criados. A primeira variável definida será o primeiro trabalho criado na execução do fluxo de trabalho. Por exemplo, a matriz acima criará os trabalhos na seguinte ordem:
{version: 10, os: ubuntu-latest}
{version: 10, os: windows-latest}
{version: 12, os: ubuntu-latest}
{version: 12, os: windows-latest}
{version: 14, os: ubuntu-latest}
{version: 14, os: windows-latest}
Uma matriz pode gerar 256 tarefas no máximo por execução do fluxo de trabalho. Esse limite se aplica a executores hospedados pelo GitHub Enterprise Servere auto-hospedados.
As variáveis que você define se tornam propriedades no contexto matrix
, e você pode referenciar a propriedade em outras áreas do arquivo de fluxo de trabalho. Neste exemplo, você pode usar matrix.version
e matrix.os
para acessar o valor atual de version
e os
que o trabalho está usando. Para obter mais informações, confira "Contextos".
Example: Using a single-dimension matrix
Você pode especificar uma única variável para criar uma matriz unidimensional.
Por exemplo, o fluxo de trabalho a seguir define a variável version
com os valores [10, 12, 14]
. O fluxo de trabalho executará três trabalhos, um para cada valor na variável. Cada trabalho acessará o valor version
por meio do contexto matrix.version
e passará o valor como node-version
� ação actions/setup-node
.
jobs:
example_matrix:
strategy:
matrix:
version: [10, 12, 14]
steps:
- uses: actions/setup-node@v2
with:
node-version: ${{ matrix.version }}
Example: Using a multi-dimension matrix
Você pode especificar diversas variáveis para criar uma matriz multidimensional. Um trabalho será executado para cada combinação possível das variáveis.
Por exemplo, o fluxo de trabalho a seguir especifica duas variáveis:
- Dois sistemas operacionais especificados na variável
os
- Três versões do Node.js especificadas na variável
version
O fluxo de trabalho executará seis trabalhos, um para cada combinação entre as variáveis os
e version
. Cada trabalho definirá o valor runs-on
como o valor atual os
e passará o valor atual version
para a ação actions/setup-node
.
jobs:
example_matrix:
strategy:
matrix:
os: [ubuntu-22.04, ubuntu-20.04]
version: [10, 12, 14]
runs-on: ${{ matrix.os }}
steps:
- uses: actions/setup-node@v2
with:
node-version: ${{ matrix.version }}
Example: Using contexts to create matrices
Você pode usar contextos para criar matrizes. Para obter mais informações sobre contextos, confira "Contextos".
Por exemplo, o fluxo de trabalho a seguir dispara no evento repository_dispatch
e usa informações do conteúdo do evento para criar a matriz. Quando um evento de expedição de repositório é criado com um conteúdo como o abaixo, a variável da matriz version
terá um valor de [12, 14, 16]
. Para obter mais informações sobre o gatilho repository_dispatch
, confira "Eventos que disparam fluxos de trabalho".
{
"event_type": "test",
"client_payload": {
"versions": [12, 14, 16]
}
}
on:
repository_dispatch:
types:
- test
jobs:
example_matrix:
runs-on: ubuntu-latest
strategy:
matrix:
version: ${{ github.event.client_payload.versions }}
steps:
- uses: actions/setup-node@v2
with:
node-version: ${{ matrix.version }}
jobs.<job_id>.strategy.matrix.include
Use jobs.<job_id>.strategy.matrix.include
para expandir as configurações de matriz existentes ou para adicionar novas configurações. O valor de include
é uma lista de objetos.
Para cada objeto na lista include
, os pares key:value no objeto serão adicionados a cada uma das combinações de matriz se nenhum dos pares key:value substituir qualquer um dos valores de matriz originais. Se o objeto não puder ser adicionado a nenhuma das combinações de matriz, uma nova combinação de matriz será criada. Observe que os valores de matriz originais não serão substituídos, mas os valores de matriz adicionados podem ser substituídos.
Por exemplo, esta matriz:
strategy:
matrix:
fruit: [apple, pear]
animal: [cat, dog]
include:
- color: green
- color: pink
animal: cat
- fruit: apple
shape: circle
- fruit: banana
- fruit: banana
animal: cat
resultará em seis trabalhos com as seguintes combinações de matriz:
{fruit: apple, animal: cat, color: pink, shape: circle}
{fruit: apple, animal: dog, color: green, shape: circle}
{fruit: pear, animal: cat, color: pink}
{fruit: pear, animal: dog, color: green}
{fruit: banana}
{fruit: banana, animal: cat}
seguindo esta lógica:
{color: green}
será adicionado a todas as combinações de matriz originais porque ele pode ser adicionado sem substituir nenhuma parte das combinações originais.{color: pink, animal: cat}
adicionacolor:pink
apenas � s combinações de matriz originais que incluemanimal: cat
. Isso substitui ocolor: green
que foi adicionado pela entrada anteriorinclude
.- O
{fruit: apple, shape: circle}
adicionashape: circle
apenas � s combinações de matriz originais que incluemfruit: apple
. - O
{fruit: banana}
não pode ser adicionado a nenhuma combinação de matriz original sem substituir um valor, portanto, ele é adicionado como uma combinação de matriz adicional. - O
{fruit: banana, animal: cat}
não pode ser adicionado a nenhuma combinação de matriz original sem substituir um valor, portanto, ele é adicionado como uma combinação de matriz adicional. Ele não adiciona � combinação de matriz{fruit: banana}
porque essa combinação não era uma das combinações de matriz originais.
Example: Expanding configurations
Por exemplo, o fluxo de trabalho a seguir executará seis trabalhos, um para cada combinação de os
e node
. Quando o trabalho para o valor os
de windows-latest
e valor node
as execuções 16
, uma variável adicional chamada npm
com o valor de 6
será incluída no trabalho.
jobs:
example_matrix:
strategy:
matrix:
os: [windows-latest, ubuntu-latest]
node: [12, 14, 16]
include:
- os: windows-latest
node: 16
npm: 6
runs-on: ${{ matrix.os }}
steps:
- uses: actions/setup-node@v2
with:
node-version: ${{ matrix.node }}
- if: ${{ matrix.npm }}
run: npm install -g npm@${{ matrix.npm }}
- run: npm --version
Example: Adding configurations
Por exemplo, essa matriz executará dez trabalhos, um para cada combinação de os
e version
na matriz, além de um trabalho para o valor os
de windows-latest
e o valor version
de 17
.
jobs:
example_matrix:
strategy:
matrix:
os: [macos-latest, windows-latest, ubuntu-latest]
version: [12, 14, 16]
include:
- os: windows-latest
version: 17
Se você não especificar nenhuma variável de matriz, todas as configurações abaixo de include
serão executadas. Por exemplo, o fluxo de trabalho a seguir executaria dois trabalhos, um para cada entrada include
. Isso permite que você aproveite a estratégia de matriz sem ter uma matriz totalmente populada.
jobs:
includes_only:
runs-on: ubuntu-latest
strategy:
matrix:
include:
- site: "production"
datacenter: "site-a"
- site: "staging"
datacenter: "site-b"
jobs.<job_id>.strategy.matrix.exclude
Para remover configurações específicas definidas na matriz, use jobs.<job_id>.strategy.matrix.exclude
. Uma configuração excluída só precisa ser uma correspondência parcial para que ela seja excluída. Por exemplo, o fluxo de trabalho a seguir executará nove trabalhos: um trabalho para cada uma das 12 configurações, menos o trabalho excluído correspondente {os: macos-latest, version: 12, environment: production}
e os dois trabalhos excluídos correspondentes {os: windows-latest, version: 16}
.
strategy:
matrix:
os: [macos-latest, windows-latest]
version: [12, 14, 16]
environment: [staging, production]
exclude:
- os: macos-latest
version: 12
environment: production
- os: windows-latest
version: 16
runs-on: ${{ matrix.os }}
Observação: todas as combinações de include
são processadas após exclude
. Isso permite que você use include
para adicionar combinações anteriores que já foram excluídas.
jobs.<job_id>.strategy.fail-fast
Você pode controlar como as falhas de trabalho são tratadas com jobs.<job_id>.strategy.fail-fast
e jobs.<job_id>.continue-on-error
.
jobs.<job_id>.strategy.fail-fast
aplica-se a toda a matriz. Se jobs.<job_id>.strategy.fail-fast
estiver definido como true
, GitHub Enterprise Server cancelará todos os trabalhos em andamento e enfileirados na matriz se algum trabalho na matriz falhar. Essa propriedade tem como padrão true
.
jobs.<job_id>.continue-on-error
aplica-se a um único trabalho. Se jobs.<job_id>.continue-on-error
for true
, outros trabalhos na matriz continuarão em execução mesmo que o trabalho com jobs.<job_id>.continue-on-error: true
falhe.
Você não pode usar jobs.<job_id>.strategy.fail-fast
e jobs.<job_id>.continue-on-error
juntos. Por exemplo, o fluxo de trabalho a seguir iniciará quatro trabalhos. Para cada trabalho, continue-on-error
é determinado pelo valor de matrix.experimental
. Se algum dos trabalhos com continue-on-error: false
falhar, todos os trabalhos em andamento ou enfileirados serão cancelados. Se o trabalho com continue-on-error: true
falhar, os outros trabalhos não serão afetados.
jobs:
test:
runs-on: ubuntu-latest
continue-on-error: ${{ matrix.experimental }}
strategy:
fail-fast: true
matrix:
version: [6, 7, 8]
experimental: [false]
include:
- version: 9
experimental: true
jobs.<job_id>.strategy.max-parallel
Por padrão, o GitHub Enterprise Server maximizará o número de trabalhos executados em paralelo, dependendo da disponibilidade do executor. Para definir o número máximo de trabalhos que podem ser executados simultaneamente com uma estratégia de trabalho matrix
, use jobs.<job_id>.strategy.max-parallel
.
Por exemplo, o fluxo de trabalho a seguir executará no máximo dois trabalhos por vez, mesmo que haja executores disponíveis para executar todos os seis trabalhos ao mesmo tempo.
jobs:
example_matrix:
strategy:
max-parallel: 2
matrix:
version: [10, 12, 14]
os: [ubuntu-latest, windows-latest]
jobs.<job_id>.continue-on-error
Prevents a workflow run from failing when a job fails. Set to true
to allow a workflow run to pass when this job fails.
Example: Preventing a specific failing matrix job from failing a workflow run
You can allow specific jobs in a job matrix to fail without failing the workflow run. For example, if you wanted to only allow an experimental job with node
set to 15
to fail without failing the workflow run.
runs-on: ${{ matrix.os }}
continue-on-error: ${{ matrix.experimental }}
strategy:
fail-fast: false
matrix:
node: [13, 14]
os: [macos-latest, ubuntu-latest]
experimental: [false]
include:
- node: 15
os: ubuntu-latest
experimental: true
jobs.<job_id>.container
Observação: se os fluxos de trabalho usarem ações de contêiner do Docker, contêineres de trabalho ou contêineres de serviço, você precisará usar um executor do Linux:
- Se você estiver usando executores hospedados em GitHub, você deverá usar um executor do Ubuntu.
- Se você estiver usando executores auto-hospedados, você deve usar uma máquina Linux, pois seu executor e o Docker precisam ser instalados.
Use jobs.<job_id>.container
to create a container to run any steps in a job that don't already specify a container. If you have steps that use both script and container actions, the container actions will run as sibling containers on the same network with the same volume mounts.
If you do not set a container
, all steps will run directly on the host specified by runs-on
unless a step refers to an action configured to run in a container.
Note: The default shell for run
steps inside a container is sh
instead of bash
. This can be overridden with jobs.<job_id>.defaults.run
or jobs.<job_id>.steps[*].shell
.
Example: Running a job within a container
name: CI
on:
push:
branches: [ main ]
jobs:
container-test-job:
runs-on: ubuntu-latest
container:
image: node:14.16
env:
NODE_ENV: development
ports:
- 80
volumes:
- my_docker_volume:/volume_mount
options: --cpus 1
steps:
- name: Check for dockerenv file
run: (ls /.dockerenv && echo Found dockerenv) || (echo No dockerenv)
When you only specify a container image, you can omit the image
keyword.
jobs:
container-test-job:
runs-on: ubuntu-latest
container: node:14.16
jobs.<job_id>.container.image
Use jobs.<job_id>.container.image
para definir a imagem do Docker a ser usada como o contêiner para executar a ação. O valor pode ser o nome da imagem do Docker Hub ou um nome de registro.
jobs.<job_id>.container.credentials
Se o registro de contêiner da imagem exigir autenticação para efetuar pull da imagem, use jobs.<job_id>.container.credentials
para definir um map
do username
e da password
. As credenciais são os mesmos valores que você fornecerá ao comando docker login
.
Exemplo: Definindo credenciais para o registro de um contêiner
container:
image: ghcr.io/owner/image
credentials:
username: ${{ github.actor }}
password: ${{ secrets.github_token }}
jobs.<job_id>.container.env
Use jobs.<job_id>.container.env
para definir um map
das variáveis de ambiente no contêiner.
jobs.<job_id>.container.ports
Use jobs.<job_id>.container.ports
para definir uma array
das portas a serem expostas no contêiner.
jobs.<job_id>.container.volumes
Use jobs.<job_id>.container.volumes
para definir uma array
de volumes para uso do contêiner. É possível usar volumes para compartilhar dados entre serviços ou outras etapas em um trabalho. Você pode especificar volumes de nome Docker, volumes Docker anônimos ou vincular montagens no host.
Para especificar um volume, especifique o caminho de origem e destino:
<source>:<destinationPath>
.
<source>
é um nome de volume ou um caminho absoluto no computador host, e <destinationPath>
é um caminho absoluto no contêiner.
Exemplo: Montando volumes em um contêiner
volumes:
- my_docker_volume:/volume_mount
- /data/my_data
- /source/directory:/destination/directory
jobs.<job_id>.container.options
Use jobs.<job_id>.container.options
para configurar opções adicionais de recurso de contêiner do Docker. Para obter uma lista de opções, confira "Opções de docker create
".
Aviso: não há suporte para a opção --network
.
jobs.<job_id>.services
Observação: se os fluxos de trabalho usarem ações de contêiner do Docker, contêineres de trabalho ou contêineres de serviço, você precisará usar um executor do Linux:
- Se você estiver usando executores hospedados em GitHub, você deverá usar um executor do Ubuntu.
- Se você estiver usando executores auto-hospedados, você deve usar uma máquina Linux, pois seu executor e o Docker precisam ser instalados.
Used to host service containers for a job in a workflow. Service containers are useful for creating databases or cache services like Redis. The runner automatically creates a Docker network and manages the life cycle of the service containers.
If you configure your job to run in a container, or your step uses container actions, you don't need to map ports to access the service or action. Docker automatically exposes all ports between containers on the same Docker user-defined bridge network. You can directly reference the service container by its hostname. The hostname is automatically mapped to the label name you configure for the service in the workflow.
If you configure the job to run directly on the runner machine and your step doesn't use a container action, you must map any required Docker service container ports to the Docker host (the runner machine). You can access the service container using localhost and the mapped port.
For more information about the differences between networking service containers, see "About service containers."
Example: Using localhost
This example creates two services: nginx and redis. When you specify the Docker host port but not the container port, the container port is randomly assigned to a free port. GitHub sets the assigned container port in the ${{job.services.<service_name>.ports}}
context. In this example, you can access the service container ports using the ${{ job.services.nginx.ports['8080'] }}
and ${{ job.services.redis.ports['6379'] }}
contexts.
services:
nginx:
image: nginx
# Map port 8080 on the Docker host to port 80 on the nginx container
ports:
- 8080:80
redis:
image: redis
# Map TCP port 6379 on Docker host to a random free port on the Redis container
ports:
- 6379/tcp
jobs.<job_id>.services.<service_id>.image
The Docker image to use as the service container to run the action. The value can be the Docker Hub image name or a registry name.
jobs.<job_id>.services.<service_id>.credentials
Se o registro de contêiner da imagem exigir autenticação para efetuar pull da imagem, use jobs.<job_id>.container.credentials
para definir um map
do username
e da password
. As credenciais são os mesmos valores que você fornecerá ao comando docker login
.
Example
services:
myservice1:
image: ghcr.io/owner/myservice1
credentials:
username: ${{ github.actor }}
password: ${{ secrets.github_token }}
myservice2:
image: dockerhub_org/myservice2
credentials:
username: ${{ secrets.DOCKER_USER }}
password: ${{ secrets.DOCKER_PASSWORD }}
jobs.<job_id>.services.<service_id>.env
Sets a map
of environment variables in the service container.
jobs.<job_id>.services.<service_id>.ports
Sets an array
of ports to expose on the service container.
jobs.<job_id>.services.<service_id>.volumes
Sets an array
of volumes for the service container to use. You can use volumes to share data between services or other steps in a job. You can specify named Docker volumes, anonymous Docker volumes, or bind mounts on the host.
To specify a volume, you specify the source and destination path:
<source>:<destinationPath>
.
The <source>
is a volume name or an absolute path on the host machine, and <destinationPath>
is an absolute path in the container.
Example
volumes:
- my_docker_volume:/volume_mount
- /data/my_data
- /source/directory:/destination/directory
jobs.<job_id>.services.<service_id>.options
Additional Docker container resource options. For a list of options, see "docker create
options."
Warning: The --network
option is not supported.
Filter pattern cheat sheet
You can use special characters in path, branch, and tag filters.
*
: Matches zero or more characters, but does not match the/
character. For example,Octo*
matchesOctocat
.**
: Matches zero or more of any character.?
: Matches zero or one of the preceding character.+
: Matches one or more of the preceding character.[]
Matches one character listed in the brackets or included in ranges. Ranges can only includea-z
,A-Z
, and0-9
. For example, the range[0-9a-z]
matches any digit or lowercase letter. For example,[CB]at
matchesCat
orBat
and[1-2]00
matches100
and200
.!
: At the start of a pattern makes it negate previous positive patterns. It has no special meaning if not the first character.
The characters *
, [
, and !
are special characters in YAML. If you start a pattern with *
, [
, or !
, you must enclose the pattern in quotes. Also, if you use a flow sequence with a pattern containing [
and/or ]
, the pattern must be enclosed in quotes.
# Valid
branches:
- '**/README.md'
# Invalid - creates a parse error that
# prevents your workflow from running.
branches:
- **/README.md
# Valid
branches: [ main, 'release/v[0-9].[0-9]' ]
# Invalid - creates a parse error
branches: [ main, release/v[0-9].[0-9] ]
For more information about branch, tag, and path filter syntax, see "on.<push>.<branches|tags>
", "on.<pull_request>.<branches|tags>
", and "on.<push|pull_request>.paths
."
Patterns to match branches and tags
Pattern | Description | Example matches |
---|---|---|
feature/* | The * wildcard matches any character, but does not match slash (/ ). | feature/my-branch feature/your-branch |
feature/** | The ** wildcard matches any character including slash (/ ) in branch and tag names. | feature/beta-a/my-branch feature/your-branch feature/mona/the/octocat |
main releases/mona-the-octocat | Matches the exact name of a branch or tag name. | main releases/mona-the-octocat |
'*' | Matches all branch and tag names that don't contain a slash (/ ). The * character is a special character in YAML. When you start a pattern with * , you must use quotes. | main releases |
'**' | Matches all branch and tag names. This is the default behavior when you don't use a branches or tags filter. | all/the/branches every/tag |
'*feature' | The * character is a special character in YAML. When you start a pattern with * , you must use quotes. | mona-feature feature ver-10-feature |
v2* | Matches branch and tag names that start with v2 . | v2 v2.0 v2.9 |
v[12].[0-9]+.[0-9]+ | Matches all semantic versioning branches and tags with major version 1 or 2. | v1.10.1 v2.0.0 |
Patterns to match file paths
Path patterns must match the whole path, and start from the repository's root.
Pattern | Description of matches | Example matches |
---|---|---|
'*' | The * wildcard matches any character, but does not match slash (/ ). The * character is a special character in YAML. When you start a pattern with * , you must use quotes. | README.md server.rb |
'*.jsx?' | The ? character matches zero or one of the preceding character. | page.js page.jsx |
'**' | The ** wildcard matches any character including slash (/ ). This is the default behavior when you don't use a path filter. | all/the/files.md |
'*.js' | The * wildcard matches any character, but does not match slash (/ ). Matches all .js files at the root of the repository. | app.js index.js |
'**.js' | Matches all .js files in the repository. | index.js js/index.js src/js/app.js |
docs/* | All files within the root of the docs directory, at the root of the repository. | docs/README.md docs/file.txt |
docs/** | Any files in the /docs directory at the root of the repository. | docs/README.md docs/mona/octocat.txt |
docs/**/*.md | A file with a .md suffix anywhere in the docs directory. | docs/README.md docs/mona/hello-world.md docs/a/markdown/file.md |
'**/docs/**' | Any files in a docs directory anywhere in the repository. | docs/hello.md dir/docs/my-file.txt space/docs/plan/space.doc |
'**/README.md' | A README.md file anywhere in the repository. | README.md js/README.md |
'**/*src/**' | Any file in a folder with a src suffix anywhere in the repository. | a/src/app.js my-src/code/js/app.js |
'**/*-post.md' | A file with the suffix -post.md anywhere in the repository. | my-post.md path/their-post.md |
'**/migrate-*.sql' | A file with the prefix migrate- and suffix .sql anywhere in the repository. | migrate-10909.sql db/migrate-v1.0.sql db/sept/migrate-v1.sql |
*.md !README.md | Using an exclamation mark (! ) in front of a pattern negates it. When a file matches a pattern and also matches a negative pattern defined later in the file, the file will not be included. | hello.md Does not match README.md docs/hello.md |
*.md !README.md README* | Patterns are checked sequentially. A pattern that negates a previous pattern will re-include file paths. | hello.md README.md README.doc |