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 acionadores de fluxo de trabalho
Os acionadores de fluxo de trabalho são eventos que fazem com que um fluxo de trabalho seja executado. Esses eventos podem ser:
- Eventos que ocorrem no repositório do fluxo de trabalho
- Eventos que ocorrem fora de GitHub Enterprise Server e acionam um evento
repository_dispatch
em GitHub Enterprise Server - Horários agendados
- Manual
Por exemplo, você pode configurar o fluxo de trabalho para executar quando um push é feito no branch padrão do seu repositório, quando uma versão é criada, ou quando um problema é aberto.
Os gatilhos de fluxo de trabalho estão definidos com a chave on
. Para obter mais informações, consulte "Sintaxe de fluxo de trabalho para o GitHub Actions".
As etapas a seguir ocorrem para acionar a execução de um fluxo de trabalho:
-
Um evento ocorre no seu repositório. O evento tem um SHA de commit associado e um ref de Git.
-
GitHub Enterprise Server pesquisa no diretório
.github/workflows
no seu repositório para arquivos de fluxo de trabalho que estão presentes no commit SHA ou no ref do Git do evento. -
A execução de um fluxo de trabalho é acionada para todos fluxos de trabalho com valores
on:
que correspondem ao evento de acionamento. Alguns eventos também exigem que o arquivo do fluxo de trabalho esteja presente no branch padrão do repositório para ser executado.Cada execução de fluxo de trabalho usará a versão do fluxo de trabalho que está presente no SHA do commit ou na ref do Git do evento. Quando um fluxo de trabalho é executado, o GitHub Enterprise Server configura as variáveis de ambiente
GITHUB_SHA
(commit SHA) eGITHUB_REF
(Git ref) no ambiente do executor. Para obter mais informações, consulte "Usando variáveis de ambiente".
Acionando um fluxo de trabalho a partir de um fluxo de trabalho
When you use the repository's GITHUB_TOKEN
to perform tasks, events triggered by the GITHUB_TOKEN
will not create a new workflow run. Isso impede que você crie execuções de fluxo de trabalho recursivo. Por exemplo, se um fluxo de trabalho executar código pushes usando o GITHUB_TOKEN
, um novo fluxo de trabalho não será executado mesmo quando o repositório contém um fluxo de trabalho configurado para ser executado quando ocorrerem eventos push
. Para obter mais informações, consulte "Efetuando a autenticação com o GITHUB_TOKEN".
Se você deseja acionar um fluxo de trabalho de dentro de uma execução de fluxo de trabalho, você pode usar um token de acesso pessoal em vez de GITHUB_TOKEN
para acionar eventos que exigem um token. Você deverá criar um token de acesso pessoal e armazená-lo como um segredo. Para minimizar seus custos de uso GitHub Actions, certifique-se de que você não cria execução de fluxo de trabalho recursivo ou não intencional. Para obter mais informações sobre a criação de um token de acesso pessoal, consulteCriando um token de acesso pessoal." Para mais informações sobre como armazenar um token de acesso pessoal como segredo, consulte "Criar e armazenar segredos criptografados".
Por exemplo, o fluxo de trabalho a seguir usa um token de acesso pessoal (armazenado como um segredo chamado MY_TOKEN
) para adicionar uma etiqueta a um problema por meio de GitHub CLI. Todos os fluxos de trabalho que forem executados quando uma etiqueta é adicionada, serão executados assim que esta etapa for executada.
on:
issues:
types:
- opened
jobs:
label_issue:
runs-on: ubuntu-latest
steps:
- env:
GITHUB_TOKEN: ${{ secrets.MY_TOKEN }}
ISSUE_URL: ${{ github.event.issue.html_url }}
run: |
gh issue edit $ISSUE_URL --add-label "triage"
Inversamente, o fluxo de trabalho a seguir usa GITHUB_TOKEN
para adicionar uma etiqueta a um problema. Ele não acionará nenhum fluxo de trabalho executado quando uma etiqueta é adicionada.
on:
issues:
types:
- opened
jobs:
label_issue:
runs-on: ubuntu-latest
steps:
- env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
ISSUE_URL: ${{ github.event.issue.html_url }}
run: |
gh issue edit $ISSUE_URL --add-label "triage"
Usando eventos para acionar fluxos de trabalho
Use a chave on
para especificar quais eventos acionam o seu fluxo de trabalho. Para obter mais informações sobre eventos que você pode usar, consulte "Eventos que acionam fluxos de trabalho."
Using a single event
For example, a workflow with the following on
value will run when a push is made to any branch in the workflow's repository:
on: push
Using multiple events
You can specify a single event or multiple events. For example, a workflow with the following on
value will run when a push is made to any branch in the repository or when someone forks the repository:
on: [push, fork]
If you specify multiple events, only one of those events needs to occur to trigger your workflow. If multiple triggering events for your workflow occur at the same time, multiple workflow runs will be triggered.
Using activity types and filters with multiple events
É possível usar tipos de atividade e filtros para controlar ainda mais quando o fluxo de trabalho será executado. Para obter mais informações, consulte Usando tipos de atividade do evento e Usando filtros. If you specify activity types or filters for an event and your workflow triggers on multiple events, you must configure each event separately. Você deve anexar dois pontos (:
) a todos os eventos, incluindo eventos sem configuração.
For example, a workflow with the following on
value will run when:
- A label is created
- A push is made to the
main
branch in the repository - A push is made to a GitHub Pages-enabled branch
on:
label:
types:
- created
push:
branches:
- main
page_build:
Usando tipos de atividade do evento
Some events have activity types that give you more control over when your workflow should run. Use on.<event_name>.types
to define the type of event activity that will trigger a workflow run.
For example, the issue_comment
event has the created
, edited
, and deleted
activity types. If your workflow triggers on the label
event, it will run whenever a label is created, edited, or deleted. If you specify the created
activity type for the label
event, your workflow will run when a label is created but not when a label is edited or deleted.
on:
label:
types:
- created
If you specify multiple activity types, only one of those event activity types needs to occur to trigger your workflow. If multiple triggering event activity types for your workflow occur at the same time, multiple workflow runs will be triggered. For example, the following workflow triggers when an issue is opened or labeled. If an issue with two labels is opened, three workflow runs will start: one for the issue opened event and two for the two issue labeled events.
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".
Using filters
Some events have filters that give you more control over when your workflow should run.
For example, the push
event has a branches
filter that causes your workflow to run only when a push to a branch that matches the branches
filter occurs, instead of when any push occurs.
on:
push:
branches:
- main
- 'releases/**'
Usando filtros para direcionar branches específicos para eventos de pull request
When using the pull_request
and pull_request_target
events, you can configure a workflow to run only for pull requests that target specific branches.
Use the branches
filter when you want to include branch name patterns or when you want to both include and exclude branch names patterns. Use the branches-ignore
filter when you only want to exclude branch name patterns. You cannot use both the branches
and branches-ignore
filters for the same event in a workflow.
If you define both branches
/branches-ignore
and paths
, the workflow will only run when both filters are satisfied.
The branches
and branches-ignore
keywords accept glob patterns that use characters like *
, **
, +
, ?
, !
and others to match more than one branch name. If a name contains any of these characters and you want a literal match, you need to escape each of these special characters with \
. Para obter mais informações sobre padrões de glob, consulte a "Folha de informações para filtrar padrões".
Example: Including branches
The patterns defined in branches
are evaluated against the Git ref's name. For example, the following workflow would run whenever there is a pull_request
event for a pull request targeting:
- A branch named
main
(refs/heads/main
) - A branch named
mona/octocat
(refs/heads/mona/octocat
) - A branch whose name starts with
releases/
, likereleases/10
(refs/heads/releases/10
)
on:
pull_request:
# Sequence of patterns matched against refs/heads
branches:
- main
- 'mona/octocat'
- 'releases/**'
Example: Excluding branches
When a pattern matches the branches-ignore
pattern, the workflow will not run. The patterns defined in branches
are evaluated against the Git ref's name. For example, the following workflow would run whenever there is a pull_request
event unless the pull request is targeting:
- A branch named
mona/octocat
(refs/heads/mona/octocat
) - A branch whose name matches
releases/**-alpha
, likebeta/3-alpha
(refs/releases/beta/3-alpha
)
on:
pull_request:
# Sequence of patterns matched against refs/heads
branches-ignore:
- 'mona/octocat'
- 'releases/**-alpha'
Example: Including and excluding branches
You cannot use branches
and branches-ignore
to filter the same event in a single workflow. If you want to both include and exclude branch patterns for a single event, use the branches
filter along with the !
character to indicate which branches should be excluded.
If you define a branch with the !
character, you must also define at least one branch without the !
character. If you only want to exclude branches, use branches-ignore
instead.
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.
The following workflow will run on pull_request
events for pull requests that target releases/10
or releases/beta/mona
, but for pull requests that target releases/10-alpha
or releases/beta/3-alpha
because the negative pattern !releases/**-alpha
follows the positive pattern.
on:
pull_request:
branches:
- 'releases/**'
- '!releases/**-alpha'
Usando filtros para direcionar branches ou tags específicas para eventos de push
When using the push
event, you can configure a workflow to run on specific branches or tags.
Use the branches
filter when you want to include branch name patterns or when you want to both include and exclude branch names patterns. Use the branches-ignore
filter when you only want to exclude branch name patterns. You cannot use both the branches
and branches-ignore
filters for the same event in a workflow.
Use the tags
filter when you want to include tag name patterns or when you want to both include and exclude tag names patterns. Use the tags-ignore
filter when you only want to exclude tag name patterns. You cannot use both the tags
and tags-ignore
filters for the same event in a workflow.
If you define only tags
/tag-ignore
or only branches
/branches-ignore
, the workflow won't run for events affecting the undefined Git ref. If you define neither tags
/tag-ignore
or branches
/branches-ignore
, the workflow will run for events affecting either branches or tags. If you define both branches
/branches-ignore
and paths
, the workflow will only run when both filters are satisfied.
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. For example, the following workflow would run whenever there is a push
event to:
- A branch named
main
(refs/heads/main
) - A branch named
mona/octocat
(refs/heads/mona/octocat
) - A branch whose name starts with
releases/
, likereleases/10
(refs/heads/releases/10
) - A tag named
v2
(refs/tags/v2
) - A tag whose name starts with
v1.
, likev1.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.*
Example: Excluding branches and tags
When a pattern matches the branches-ignore
or tags-ignore
pattern, the workflow will not run. Os padrões definidos nos branches
e tags
são avaliados relativamente ao nome do Git ref. For example, the following workflow would run whenever there is a push
event, unless the push
event is to:
- A branch named
mona/octocat
(refs/heads/mona/octocat
) - A branch whose name matches
releases/**-alpha
, likebeta/3-alpha
(refs/releases/beta/3-alpha
) - A tag named
v2
(refs/tags/v2
) - A tag whose name starts with
v1.
, likev1.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.*
Example: Including and excluding branches and tags
You can't use branches
and branches-ignore
to filter the same event in a single workflow. Similarly, you can't use tags
and tags-ignore
to filter the same event in a single workflow. If you want to both include and exclude branch or tag patterns for a single event, use the branches
or tags
filter along with the !
character to indicate which branches or tags should be excluded.
If you define a branch with the !
character, you must also define at least one branch without the !
character. If you only want to exclude branches, use branches-ignore
instead. Similarly, if you define a tag with the !
character, you must also define at least one tag without the !
character. If you only want to exclude tags, use tags-ignore
instead.
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'
Usando filtros para direcionar caminhos específicos para pull requests uu eventos de push
When using the push
and pull_request
events, you can configure a workflow to run based on what file paths are changed. Path filters are not evaluated for pushes of tags.
Use the paths
filter when you want to include file path patterns or when you want to both include and exclude file path patterns. Use the paths-ignore
filter when you only want to exclude file path patterns. You cannot use both the paths
and paths-ignore
filters for the same event in a workflow.
If you define both branches
/branches-ignore
and paths
, the workflow will only run when both filters are satisfied.
The paths
and paths-ignore
keywords accept glob patterns that use the *
and **
wildcard characters to match more than one path name. 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. For example, the following workflow would run anytime you push a JavaScript file (.js
).
on:
push:
paths:
- '**.js'
Example: Excluding paths
Quando todos os caminhos de nome correspondem a padrões em paths-ignore
, o fluxo de trabalho não será executado. If any path names do not match patterns in paths-ignore
, even if some path names match the patterns, the workflow will run.
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/**'
Example: Including and excluding paths
You can not use paths
and paths-ignore
to filter the same event in a single workflow. If you want to both include and exclude path patterns for a single event, use the paths
filter along with the !
character to indicate which paths should be excluded.
If you define a path with the !
character, you must also define at least one path without the !
character. If you only want to exclude paths, use paths-ignore
instead.
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".
Usando filtros para direcionar branches específicos para eventos de execução de fluxo de trabalho
When using the workflow_run
event, you can specify what branches the triggering workflow must run on in order to trigger your workflow.
The branches
and branches-ignore
filters accept glob patterns that use characters like *
, **
, +
, ?
, !
and others to match more than one branch name. 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".
For example, a workflow with the following trigger will only run when the workflow named Build
runs on a branch whose name starts with releases/
:
on:
workflow_run:
workflows: ["Build"]
types: [requested]
branches:
- 'releases/**'
A workflow with the following trigger will only run when the workflow named Build
runs on a branch that is not named canary
:
on:
workflow_run:
workflows: ["Build"]
types: [requested]
branches-ignore:
- "canary"
You cannot use both the branches
and branches-ignore
filters for the same event in a workflow. If you want to both include and exclude branch patterns for a single event, use the branches
filter along with the !
character to indicate which branches should be excluded.
A ordem de definição dos padrões é importante.
- A matching negative pattern (prefixed with
!
) after a positive match will exclude the branch. - A matching positive pattern after a negative match will include the branch again.
For example, a workflow with the following trigger will run when the workflow named Build
runs on a branch that is named releases/10
or releases/beta/mona
but will not releases/10-alpha
, releases/beta/3-alpha
, or main
.
on:
workflow_run:
workflows: ["Build"]
types: [requested]
branches:
- 'releases/**'
- '!releases/**-alpha'
Definindo entradas para fluxos de trabalho acionados manualmente
Ao usar o evento workflow_dispatch
, você pode, opcionalmente, especificar as entradas que são passadas para o fluxo de trabalho.
O fluxo de trabalho acionado recebe as entradas no contexto github.event.inputs
. Para obter mais informações, consulte "Contextos".
on:
workflow_dispatch:
inputs:
logLevel:
description: 'Log level'
required: true
default: 'warning'
tags:
description: 'Test scenario tags'
required: false
jobs:
print-tag:
runs-on: ubuntu-latest
steps:
- name: Print the input tag to STDOUT
run: echo The tag is ${{ github.event.inputs.tag }}
Usando informações do evento
As informações sobre o evento que desencadeou uma execução de fluxo de trabalho estão disponíveis no contexto github.event
. As propriedades no contexto github.event
dependem do tipo de evento que acionou o fluxo de trabalho. Por exemplo, um fluxo de trabalho acionado quando um problema está etiquetado teria informações sobre o problema e a etiqueta.
Visualizando todas as propriedades de um evento
Referência � documentação de evento de webhook para propriedades comuns e cargas de exemplo. Para obter mais informações, consulte "Eventos e cargas de Webhook".
Você também pode imprimir o contexto inteiro de github.event
para ver quais propriedades estão disponíveis para o evento que acionou o seu fluxo de trabalho:
jobs:
print_context:
runs-on: ubuntu-latest
steps:
- env:
EVENT_CONTEXT: ${{ toJSON(github.event) }}
run: |
echo $EVENT_CONTEXT
Acessando e usando as propriedades do evento
Você pode usar o contexto github.event
no fluxo de trabalho. Por exemplo, o fluxo de trabalho a seguir é executado quando um pull request que muda package*.json
, .github/CODEOWNERS
ou .github/workflows/**
é aberto. Se o autor do pull request (github.event.pull_request.user.login
) não for octobot
ou dependabot[bot]
, o fluxo de trabalho usará o GitHub CLI para etiquetar e comentar no pull request (github.event.pull_request.number
).
on:
pull_request:
types:
- opened
paths:
- '.github/workflows/**'
- '.github/CODEOWNERS'
- 'package*.json'
jobs:
triage:
if: >-
github.event.pull_request.user.login != 'octobot' &&
github.event.pull_request.user.login != 'dependabot[bot]'
runs-on: ubuntu-latest
steps:
- name: "Comment about changes we can't accept"
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
PR: ${{ github.event.pull_request.html_url }}
run: |
gh pr edit $PR --add-label 'invalid'
gh pr comment $PR --body 'It looks like you edited `package*.json`, `.github/CODEOWNERS`, or `.github/workflows/**`. Nós não permitimos contribuições para esses arquivos. Consulte nossas [diretrizes de contribuição](https://github.com/octo-org/octo-repo/blob/main/CONTRIBUTING.md) para saber quais contribuições são aceitas.'
Para obter mais informações sobre os contextos, consulte "Contextos". Para obter mais informações sobre cargas de eventos, consulte "Eventos Webhook e cargas".
Controlando ainda mais como seu fluxo de trabalho será executado
Se você quiser mais controle granular do que os eventos, tipos de atividade do evento ou filtros de evento fornecem, você poderá usar condicionais para controlar se os trabalhos ou etapas individuais no seu fluxo de trabalho serão executados.
Usando condicionais
Você pode usar condicionais para controlar ainda mais se os trabalhos ou etapas no seu fluxo de trabalho serão executados. Se você quiser, por exemplo, que o fluxo de trabalho seja executado quando uma etiqueta específica for adicionada a um problema, você poderá acionar o tipo de atividade do evento issues labeled
e usar uma condicional para verificar qual etiqueta acionou o fluxo de trabalho. O fluxo de trabalho a seguir será executado quando qualquer etiqueta for adicionada a um problema no repositório do fluxo de trabalho, mas a o trabalho run_if_label_matches
só será executado se a etiqueta tiver o nome de bug
.
on:
issues:
types:
- labeled
jobs:
run_if_label_matches:
if: github.event.label.name == 'bug'
runs-on: ubuntu-latest
steps:
- run: echo 'The label was bug'
Para obter mais informações, consulte "Expressões".
Eventos disponíveis
Para obter uma lista completa de eventos disponíveis, consulte "Eventos que acionam fluxos de trabalho".