Skip to main content

Acessar informações contextuais sobre execuções de fluxo de trabalho

Você pode acessar as informações de contexto nos fluxos de trabalho e nas ações.

Note

No momento, não há suporte para executores hospedados no GitHub no GitHub Enterprise Server. Você pode ver mais informações sobre o suporte futuro planejado no GitHub public roadmap.

Sobre os contextos

Os contextos são uma forma de acessar informações sobre execuções de fluxo de trabalho, variáveis, ambientes dos executores, trabalhos e etapas. Cada contexto é um objeto que contém propriedades, que podem ser cadeia de caracteres ou outros objetos.

Os contextos, objetos e propriedades variarão significativamente em diferentes condições de execução do fluxo de trabalho. Por exemplo, o contexto matrix só é preenchido para trabalhos em uma matriz.

Você pode acessar contextos usando a sintaxe da expressão. Para obter mais informações, confira "Avaliar expressões em fluxos de trabalho e ações".

${{ <context> }}

Warning

Ao criar fluxos de trabalho e ações, sempre considere se o código poderá executar entradas não confiáveis de possíveis invasores. Certos contextos devem ser tratados como entradas não confiáveis, uma vez que um invasor pode inserir seu próprio conteúdo malicioso. Para obter mais informações, confira "Fortalecimento de segurança para o GitHub Actions".

Nome do contextoTipoDescrição
githubobjectInformações sobre a execução do fluxo de trabalho. Para obter mais informações, confira Contexto github.
envobjectContém variáveis definidas em um fluxo de trabalho, um trabalho ou uma etapa. Para obter mais informações, confira Contexto env.
varsobjectContém variáveis definidas nos níveis de repositório, organização ou ambiente. Para obter mais informações, confira Contexto vars.
jobobjectInformações sobre o trabalho atualmente em execução. Para obter mais informações, confira Contexto job.
jobsobjectSomente para fluxos de trabalho reutilizáveis, contém saídas de trabalhos do fluxo de trabalho reutilizável. Para obter mais informações, confira Contexto jobs.
stepsobjectInformações sobre as etapas que foram executadas no trabalho atual. Para obter mais informações, confira Contexto steps.
runnerobjectInformações sobre o executor do trabalho atual. Para obter mais informações, confira Contexto runner.
secretsobjectContém os nomes e valores de segredos que estão disponíveis para a execução de um fluxo de trabalho. Para obter mais informações, confira Contexto secrets.
strategyobjectInformações sobre a estratégia de execução da matriz para o trabalho atual. Para obter mais informações, confira Contexto strategy.
matrixobjectContém as propriedades da matriz definidas no fluxo de trabalho que se aplicam ao trabalho atual. Para obter mais informações, confira Contexto matrix.
needsobjectContém as saídas de todos os trabalhos que são definidos como uma dependência do trabalho atual. Para obter mais informações, confira Contexto needs.
inputsobjectContém as entradas de um fluxo de trabalho reutilizável ou acionado manualmente. Para obter mais informações, confira Contexto inputs.

Como parte de uma expressão, você pode acessar informações de contexto usando uma das duas sintaxes.

  • Sintaxe de índice: github['sha']
  • Sintaxe de desreferência de propriedade: github.sha

Para usar a sintaxe de desreferência de propriedade, o nome da propriedade deve começar com uma letra _ ou e conter apenas caracteres alfanuméricos, - ou _.

Se você tentar desreferenciar uma propriedade inexistente, ela será avaliada como uma cadeia de caracteres vazia.

Determinar quando usar contextos

O GitHub Actions inclui uma coleção de variáveis chamadas contextos e outra coleção semelhante de variáveis chamadas variáveis padrão. Estas variáveis são destinadas a serem usadas em diferentes pontos do fluxo de trabalho:

  • Variáveis de ambiente padrão: essas variáveis de ambiente existem apenas no executor que está executando seu trabalho. Para obter mais informações, confira "Armazenar informações em variáveis".
  • Contextos: você pode usar a maioria dos contextos em qualquer ponto do fluxo de trabalho, inclusive quando as variáveis padrão não estão disponíveis. Por exemplo, você pode usar contextos com expressões para executar o processamento inicial antes que o trabalho seja encaminhado para um executor para execução. Isso permite que você use um contexto com a palavra-chave if condicional para determinar se uma etapa deve ser executada. Depois que o trabalho estiver em execução, você também poderá recuperar variáveis de contexto do executor que está executando o trabalho, como runner.os. Para ver detalhes do local em que você pode usar vários contextos em um fluxo de trabalho, confira "Disponibilidade de contexto".

O seguinte exemplo demonstra como esses diferentes tipos de variáveis podem ser usados juntos em um trabalho:

YAML
name: CI
on: push
jobs:
  prod-check:
    if: ${{ github.ref == 'refs/heads/main' }}
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying to production server on branch $GITHUB_REF"

Neste exemplo, a instrução if verifica o contexto github.ref para determinar o nome do branch atual. Se o nome for refs/heads/main, as etapas seguintes serão executadas. A verificação if é processada pelo GitHub Actions, e o trabalho só será enviado ao executor se o resultado for true. Depois que o trabalho é enviado para o executor, a etapa é executada e refere-se à variável $GITHUB_REF do executor.

Disponibilidade do contexto

Contextos diferentes estão disponíveis durante a execução de um fluxo de trabalho. Por exemplo, o contexto secrets só pode ser usado em alguns lugares de um trabalho.

Além disso, algumas funções só podem ser utilizadas em determinados lugares. Por exemplo, a função hashFiles não está disponível em todos os lugares.

A tabela a seguir lista as restrições nas quais cada contexto e função especial podem ser utilizados em um fluxo de trabalho. Os contextos listados estão disponíveis apenas para a chave de fluxo de trabalho fornecida e não podem ser usados em nenhum outro lugar. A menos que esteja listado abaixo, uma função pode ser usada em qualquer lugar.

Chave de fluxo de trabalhoContextoFunções especiais
run-namegithub, inputs, varsNenhum
concurrencygithub, inputs, varsNenhum
envgithub, secrets, inputs, varsNenhum
jobs.<job_id>.concurrencygithub, needs, strategy, matrix, inputs, varsNenhum
jobs.<job_id>.containergithub, needs, strategy, matrix, vars, inputsNenhum
jobs.<job_id>.container.credentialsgithub, needs, strategy, matrix, env, vars, secrets, inputsNenhum
jobs.<job_id>.container.env.<env_id>github, needs, strategy, matrix, job, runner, env, vars, secrets, inputsNenhum
jobs.<job_id>.container.imagegithub, needs, strategy, matrix, vars, inputsNenhum
jobs.<job_id>.continue-on-errorgithub, needs, strategy, vars, matrix, inputsNenhum
jobs.<job_id>.defaults.rungithub, needs, strategy, matrix, env, vars, inputsNenhum
jobs.<job_id>.envgithub, needs, strategy, matrix, vars, secrets, inputsNenhum
jobs.<job_id>.environmentgithub, needs, strategy, matrix, vars, inputsNenhum
jobs.<job_id>.environment.urlgithub, needs, strategy, matrix, job, runner, env, vars, steps, inputsNenhum
jobs.<job_id>.ifgithub, needs, vars, inputsalways, cancelled, success, failure
jobs.<job_id>.namegithub, needs, strategy, matrix, vars, inputsNenhum
jobs.<job_id>.outputs.<output_id>github, needs, strategy, matrix, job, runner, env, vars, secrets, steps, inputsNenhum
jobs.<job_id>.runs-ongithub, needs, strategy, matrix, vars, inputsNenhum
jobs.<job_id>.secrets.<secrets_id>github, needs, strategy, matrix, secrets, inputs, varsNenhum
jobs.<job_id>.servicesgithub, needs, strategy, matrix, vars, inputsNenhum
jobs.<job_id>.services.<service_id>.credentialsgithub, needs, strategy, matrix, env, vars, secrets, inputsNenhum
jobs.<job_id>.services.<service_id>.env.<env_id>github, needs, strategy, matrix, job, runner, env, vars, secrets, inputsNenhum
jobs.<job_id>.steps.continue-on-errorgithub, needs, strategy, matrix, job, runner, env, vars, secrets, steps, inputshashFiles
jobs.<job_id>.steps.envgithub, needs, strategy, matrix, job, runner, env, vars, secrets, steps, inputshashFiles
jobs.<job_id>.steps.ifgithub, needs, strategy, matrix, job, runner, env, vars, steps, inputsalways, cancelled, success, failure, hashFiles
jobs.<job_id>.steps.namegithub, needs, strategy, matrix, job, runner, env, vars, secrets, steps, inputshashFiles
jobs.<job_id>.steps.rungithub, needs, strategy, matrix, job, runner, env, vars, secrets, steps, inputshashFiles
jobs.<job_id>.steps.timeout-minutesgithub, needs, strategy, matrix, job, runner, env, vars, secrets, steps, inputshashFiles
jobs.<job_id>.steps.withgithub, needs, strategy, matrix, job, runner, env, vars, secrets, steps, inputshashFiles
jobs.<job_id>.steps.working-directorygithub, needs, strategy, matrix, job, runner, env, vars, secrets, steps, inputshashFiles
jobs.<job_id>.strategygithub, needs, vars, inputsNenhum
jobs.<job_id>.timeout-minutesgithub, needs, strategy, matrix, vars, inputsNenhum
jobs.<job_id>.with.<with_id>github, needs, strategy, matrix, inputs, varsNenhum
on.workflow_call.inputs.<inputs_id>.defaultgithub, inputs, varsNenhum
on.workflow_call.outputs.<output_id>.valuegithub, jobs, vars, inputsNenhum

Exemplo: imprimir informações de contexto no registro

Você pode imprimir o conteúdo de contextos no registro para depuração. A função toJSON é necessária para imprimir objetos JSON no log.

Warning

Ao usar todo o contexto github, lembre-se de que ele inclui informações confidenciais, como github.token. GitHub oculta segredos quando eles são impressos no console, mas você deve ter cuidado ao exportar ou imprimir o contexto.

YAML
name: Context testing
on: push

jobs:
  dump_contexts_to_log:
    runs-on: ubuntu-latest
    steps:
      - name: Dump GitHub context
        env:
          GITHUB_CONTEXT: ${{ toJson(github) }}
        run: echo "$GITHUB_CONTEXT"
      - name: Dump job context
        env:
          JOB_CONTEXT: ${{ toJson(job) }}
        run: echo "$JOB_CONTEXT"
      - name: Dump steps context
        env:
          STEPS_CONTEXT: ${{ toJson(steps) }}
        run: echo "$STEPS_CONTEXT"
      - name: Dump runner context
        env:
          RUNNER_CONTEXT: ${{ toJson(runner) }}
        run: echo "$RUNNER_CONTEXT"
      - name: Dump strategy context
        env:
          STRATEGY_CONTEXT: ${{ toJson(strategy) }}
        run: echo "$STRATEGY_CONTEXT"
      - name: Dump matrix context
        env:
          MATRIX_CONTEXT: ${{ toJson(matrix) }}
        run: echo "$MATRIX_CONTEXT"

Contexto github

O contexto github contém informações sobre a execução de fluxo de trabalho e sobre o evento que a disparou. Leia também a maioria dos dados de contexto github em variáveis de ambiente. Para obter mais informações sobre variáveis de ambiente, confira "Armazenar informações em variáveis".

Warning

Ao usar todo o contexto github, lembre-se de que ele inclui informações confidenciais, como github.token. GitHub oculta segredos quando eles são impressos no console, mas você deve ter cuidado ao exportar ou imprimir o contexto. Ao criar fluxos de trabalho e ações, sempre considere se o código poderá executar entradas não confiáveis de possíveis invasores. Certos contextos devem ser tratados como entradas não confiáveis, uma vez que um invasor pode inserir seu próprio conteúdo malicioso. Para obter mais informações, confira "Fortalecimento de segurança para o GitHub Actions".

Nome da propriedadeTypeDescrição
githubobjectContexto de nível mais alto disponível em qualquer trabalho ou etapa de um fluxo de trabalho. Este objeto contém todas as propriedades listadas abaixo.
github.actionstringO nome da ação atualmente em execução ou a id de uma etapa. O GitHub remove caracteres especiais ou usa o nome __run quando a etapa atual executa um script sem uma id. Se você usar a mesma ação mais de uma vez no mesmo trabalho, o nome incluirá um sufixo com o número da sequência com o sublinhado antes dele. Por exemplo, o primeiro script que você executar terá o nome __run, e o segundo script será chamado __run_2. Da mesma forma, a segunda invocação de actions/checkout será actionscheckout2.
github.action_pathstringO caminho onde uma ação está localizada. Esta propriedade só é compatível com ações compostas. Você pode usar esse caminho para acessar arquivos localizados no mesmo repositório que a ação, por exemplo, alterando diretórios para o caminho: cd ${{ github.action_path }} .
github.action_refstringPara uma etapa executando uma ação, este é o ref da ação que está sendo executada. Por exemplo, v2.

Não use na palavra-chave run. Para que esse contexto funcione com ações compostas, referencie-o no contexto env da ação composta.
github.action_repositorystringPara uma etpa que executa uma ação, este é o nome do proprietário e do repositório da ação. Por exemplo, actions/checkout.

Não use na palavra-chave run. Para que esse contexto funcione com ações compostas, referencie-o no contexto env da ação composta.
github.action_statusstringPara uma ação composta, o resultado atual da ação composta.
github.actorstringO nome de usuário de quem acionou a execução do fluxo de trabalho inicial. Se a execução do fluxo de trabalho for executada novamente, esse valor poderá ser diferente de github.triggering_actor. Qualquer nova execução de fluxo de trabalho usará os privilégios de github.actor, mesmo que o ator que inicie a nova execução (github.triggering_actor) tenha privilégios diferentes.
github.actor_idstringA ID da conta da pessoa ou do aplicativo que disparou a execução inicial do fluxo de trabalho. Por exemplo, 1234567. Observe que isso é diferente do nome de usuário do ator.
github.api_urlstringA URL da API REST de GitHub.
github.base_refstringA base_ref ou o branch de destino da solicitação de pull em uma execução de fluxo de trabalho. Essa propriedade só fica disponível quando o evento que dispara a execução de fluxo de trabalho é pull_request ou pull_request_target.
github.envstringCaminho no executor para o arquivo que define variáveis de ambiente dos comandos do fluxo de trabalho. Este arquivo é único para a etapa atual e é um arquivo diferente para cada etapa de um trabalho. Para obter mais informações, confira "Comandos de fluxo de trabalho para o GitHub Actions".
github.eventobjectCarga de evento de webhook completa. Você pode acessar as propriedades individuais do evento usando este contexto. Este objeto é idêntico à carga do webhook do evento que acionou a execução do fluxo de trabalho e é diferente para cada evento. Os webhooks para cada evento do GitHub Actions estão vinculados no "Eventos que disparam fluxos de trabalho". Por exemplo, para uma execução de fluxo de trabalho disparada pelo evento push, esse objeto contém o conteúdo da carga do webhook por push.
github.event_namestringNome do evento que acionou a execução do fluxo de trabalho.
github.event_pathstringO caminho para o arquivo no executor que contém a carga completa do webhook do evento.
github.graphql_urlstringA URL da API do GraphQL de GitHub.
github.head_refstringA head_ref ou o branch de origem da solicitação de pull em uma execução de fluxo de trabalho. Essa propriedade só fica disponível quando o evento que dispara a execução de fluxo de trabalho é pull_request ou pull_request_target.
github.jobstringA job_id do trabalho atual.
Observação: essa propriedade de contexto é definida pelo executor de Ações e só está disponível na execução steps de um trabalho. Caso contrário, o valor dessa propriedade será null.
github.pathstringO caminho no executor para o arquivo que define as variáveis do sistema PATH por meio dos comandos do fluxo de trabalho. Este arquivo é único para a etapa atual e é um arquivo diferente para cada etapa de um trabalho. Para obter mais informações, confira "Comandos de fluxo de trabalho para o GitHub Actions".
github.refstringA ref totalmente formada do branch ou tag que acionou a execução do fluxo de trabalho. Para fluxos de trabalho disparados por push, esse é o branch ou a ref da tag que foi enviada por push. Para fluxos de trabalho disparados por pull_request, esse é o branch de mesclagem de solicitação de pull. Para fluxos de trabalho disparados por release, essa é a tag de versão criada. Para outros gatilhos, esse é o branch ou a ref de tag que disparou a execução do fluxo de trabalho. Essa variável só é definida quando há um branch ou uma tag disponível para o tipo de evento. A ref fornecida tem o formato completo, o que significa que, para branches, o formato é refs/heads/<branch_name>, para solicitações de pull é refs/pull/<pr_number>/merge e para tags é refs/tags/<tag_name>. Por exemplo, refs/heads/feature-branch-1.
github.ref_namestringO nome de ref curto do branch ou tag que acionou a execução do fluxo de trabalho. Esse valor corresponde ao nome do branch ou tag mostrado em GitHub. Por exemplo, feature-branch-1.

Para solicitações de pull, o formato é <pr_number>/merge.
github.ref_protectedbooleantrue se proteções de ramificação estiverem configurados para a referência que disparou a execução do fluxo de trabalho.
github.ref_typestringO tipo de ref que acionou a execução do fluxo de trabalho. Os valores válidos são branch ou tag.
github.repositorystringNome do repositório e o proprietário. Por exemplo, octocat/Hello-World.
github.repository_idstringA ID do repositório. Por exemplo, 123456789. Observe que isso é diferente do nome do repositório.
github.repository_ownerstringO nome de usuário do proprietário do repositório. Por exemplo, octocat.
github.repository_owner_idstringA ID da conta do proprietário do repositório. Por exemplo, 1234567. Observe que isso é diferente do nome do proprietário.
github.repositoryUrlstringA URL do Git para o repositório. Por exemplo, git://github.com/octocat/hello-world.git.
github.retention_daysstringO número de dias em que os logs e os artefatos da execução de fluxo de trabalho são mantidos.
github.run_idstringUm número exclusivo para cada fluxo de trabalho executado em um repositório. Este número não muda se você executar novamente o fluxo de trabalho.
github.run_numberstringUm número exclusivo para cada execução de um fluxo de trabalho específico em um repositório. Esse número começa em 1 para a primeira execução do fluxo de trabalho e é incrementado a cada nova operação. Este número não muda se você executar novamente o fluxo de trabalho.
github.run_attemptstringUm número exclusivo para cada tentativa de execução de um fluxo de trabalho específico em um repositório. Este número começa em 1 para a primeira tentativa de execução do fluxo de trabalho e aumenta a cada nova execução.
github.secret_sourcestringA origem de um segredo usado em um fluxo de trabalho. Os valores possíveis são None, Actions ou Dependabot.
github.server_urlstringA URL do servidor do GitHub. Por exemplo: https://github.com.
github.shastringO commit SHA que acionou o fluxo de trabalho. O valor do commit deste SHA depende do evento que acionou o fluxo de trabalho. Para obter mais informações, confira "Eventos que disparam fluxos de trabalho". Por exemplo, ffac537e6cbbf934b08745a378932722df287a53.
github.tokenstringUm token para autenticação em nome do aplicativo do GitHub instalado no seu repositório. Isso é funcionalmente equivalente ao segredo GITHUB_TOKEN. Para obter mais informações, confira "Autenticação automática de token".
Observação: essa propriedade de contexto é definida pelo executor de Ações e só está disponível na execução steps de um trabalho. Caso contrário, o valor dessa propriedade será null.
github.triggering_actorstringO nome de usuário de quem iniciou a execução do fluxo de trabalho. Se a execução do fluxo de trabalho for executada novamente, esse valor poderá ser diferente de github.actor. Qualquer nova execução de fluxo de trabalho usará os privilégios de github.actor, mesmo que o ator que inicie a nova execução (github.triggering_actor) tenha privilégios diferentes.
github.workflowstringNome do fluxo de trabalho. Se o arquivo de fluxo de trabalho não especificar um name, o valor dessa propriedade será o caminho completo do arquivo de fluxo de trabalho no repositório.
github.workflow_refstringO caminho de referência para o fluxo de trabalho. Por exemplo, octocat/hello-world/.github/workflows/my-workflow.yml@refs/heads/my_branch.
github.workflow_shastringO SHA de commit para o arquivo de fluxo de trabalho.
github.workspacestringO diretório de trabalho padrão no executor para etapas, e o localização padrão do repositório quando a ação checkout é usada.

Exemplo de conteúdo do contexto github

O contexto a seguir foi obtido de uma execução de fluxo de trabalho disparada pelo evento push. O objeto event deste exemplo foi truncado porque é idêntico ao conteúdo da carga do webhook push.

Note

Esse contexto é apenas um exemplo. O conteúdo de um contexto depende do fluxo de trabalho que você está executando. Os contextos, objetos e propriedades variarão significativamente em diferentes condições de execução do fluxo de trabalho.

{
  "token": "***",
  "job": "dump_contexts_to_log",
  "ref": "refs/heads/my_branch",
  "sha": "c27d339ee6075c1f744c5d4b200f7901aad2c369",
  "repository": "octocat/hello-world",
  "repository_owner": "octocat",
  "repositoryUrl": "git://github.com/octocat/hello-world.git",
  "run_id": "1536140711",
  "run_number": "314",
  "retention_days": "90",
  "run_attempt": "1",
  "actor": "octocat",
  "workflow": "Context testing",
  "head_ref": "",
  "base_ref": "",
  "event_name": "push",
  "event": {
    ...
  },
  "server_url": "https://github.com",
  "api_url": "https://api.github.com",
  "graphql_url": "https://api.github.com/graphql",
  "ref_name": "my_branch",
  "ref_protected": false,
  "ref_type": "branch",
  "secret_source": "Actions",
  "workspace": "/home/runner/work/hello-world/hello-world",
  "action": "github_step",
  "event_path": "/home/runner/work/_temp/_github_workflow/event.json",
  "action_repository": "",
  "action_ref": "",
  "path": "/home/runner/work/_temp/_runner_file_commands/add_path_b037e7b5-1c88-48e2-bf78-eaaab5e02602",
  "env": "/home/runner/work/_temp/_runner_file_commands/set_env_b037e7b5-1c88-48e2-bf78-eaaab5e02602"
}

Exemplo de uso do contexto github

Este exemplo de fluxo de trabalho usa o contexto github.event_name para executar um trabalho somente se a execução de fluxo de trabalho foi disparada pelo evento pull_request.

YAML
name: Run CI
on: [push, pull_request]

jobs:
  normal_ci:
    runs-on: ubuntu-latest
    steps:
      - name: Run normal CI
        run: echo "Running normal CI"

  pull_request_ci:
    runs-on: ubuntu-latest
    if: ${{ github.event_name == 'pull_request' }}
    steps:
      - name: Run PR CI
        run: echo "Running PR only CI"

Contexto env

O contexto env contém variáveis que foram definidas em um fluxo de trabalho, um trabalho ou uma etapa. Ele não contém variáveis herdadas pelo processo do executor. Para obter mais informações sobre como definir variáveis em seu fluxo de trabalho, confira "Sintaxe de fluxo de trabalho para o GitHub Actions".

Você pode recuperar os valores das variáveis armazenadas no contexto env e usá-los no arquivo do fluxo de trabalho. O contexto env pode ser usado em qualquer chave em uma etapa do fluxo de trabalho, exceto nas chaves id e uses. Para obter mais informações sobre a sintaxe da etapa, confira "Sintaxe de fluxo de trabalho para o GitHub Actions".

Se você deseja utilizar o valor de uma variável dentro de um executor, use o método normal do sistema operacional do executor para ler as variáveis de ambiente.

Nome da propriedadeTypeDescrição
envobjectEsse contexto altera cada etapa em um trabalho. Você pode acessar esse contexto em qualquer etapa de um trabalho. Este objeto contém as propriedades listadas abaixo.
env.<env_name>stringO valor de uma variável de ambiente específica.

Exemplo de conteúdo do contexto env

O conteúdo do contexto env é um mapeamento de nomes de variáveis para os respectivos valores. O conteúdo do contexto pode mudar dependendo de onde é usado na execução do fluxo de trabalho. Neste exemplo, o env contexto contém duas variáveis.

{
  "first_name": "Mona",
  "super_duper_var": "totally_awesome"
}

Exemplo de uso do contexto env

Este exemplo de fluxo de trabalho mostra variáveis sendo definidas no contexto env nos níveis de fluxo de trabalho, trabalho e etapa. Em seguida, a sintaxe ${{ env.VARIABLE-NAME }} é usada para recuperar valores de variáveis em etapas individuais no fluxo de trabalho.

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

YAML
name: Hi Mascot
on: push
env:
  mascot: Mona
  super_duper_var: totally_awesome

jobs:
  windows_job:
    runs-on: windows-latest
    steps:
      - run: echo 'Hi ${{ env.mascot }}'  # Hi Mona
      - run: echo 'Hi ${{ env.mascot }}'  # Hi Octocat
        env:
          mascot: Octocat
  linux_job:
    runs-on: ubuntu-latest
    env:
      mascot: Tux
    steps:
      - run: echo 'Hi ${{ env.mascot }}'  # Hi Tux

Contexto vars

Note

As variáveis de configuração para GitHub Actions estão em beta e estão sujeitas a alterações.

O contexto vars contém variáveis de configuração personalizadas definidas nos níveis da organização, do repositório e do ambiente. Para obter mais informações sobre como definir variáveis de configuração para uso em vários fluxos de trabalho, confira "Armazenar informações em variáveis".

Exemplo de conteúdo do contexto vars

O conteúdo do contexto vars é um mapeamento de nomes de variáveis de configuração para os respectivos valores.

{
  "mascot": "Mona"
}

Exemplo de uso do contexto vars

Este exemplo de fluxo de trabalho mostra como as variáveis de configuração definidas nos níveis de repositório, ambiente ou organização estão automaticamente disponíveis usando o contexto vars.

Note

As variáveis de configuração no ambiente ficam automaticamente disponíveis depois que o ambiente é declarado pelo executor.

Se uma variável de configuração não tiver sido definida, o valor retornado de um contexto referenciando a variável será uma cadeia de caracteres vazia.

O exemplo a seguir mostra o uso de variáveis de configuração com o contexto vars em um fluxo de trabalho. Cada uma das variáveis de configuração a seguir foram definidas no nível do repositório, da organização ou do ambiente.

YAML
on:
  workflow_dispatch:
env:
  # Setting an environment variable with the value of a configuration variable
  env_var: ${{ vars.ENV_CONTEXT_VAR }}

jobs:
  display-variables:
    name: ${{ vars.JOB_NAME }}
    # You can use configuration variables with the `vars` context for dynamic jobs
    if: ${{ vars.USE_VARIABLES == 'true' }}
    runs-on: ${{ vars.RUNNER }}
    environment: ${{ vars.ENVIRONMENT_STAGE }}
    steps:
    - name: Use variables
      run: |
        echo "repository variable : $REPOSITORY_VAR"
        echo "organization variable : $ORGANIZATION_VAR"
        echo "overridden variable : $OVERRIDE_VAR"
        echo "variable from shell environment : $env_var"
      env:
        REPOSITORY_VAR: ${{ vars.REPOSITORY_VAR }}
        ORGANIZATION_VAR: ${{ vars.ORGANIZATION_VAR }}
        OVERRIDE_VAR: ${{ vars.OVERRIDE_VAR }}
        
    - name: ${{ vars.HELLO_WORLD_STEP }}
      if: ${{ vars.HELLO_WORLD_ENABLED == 'true' }}
      uses: actions/hello-world-javascript-action@main
      with:
        who-to-greet: ${{ vars.GREET_NAME }}

Contexto job

O contexto job contém informações sobre o trabalho atualmente em execução.

Nome da propriedadeTypeDescrição
jobobjectEsse contexto altera cada trabalho em uma execução de fluxo de trabalho. Você pode acessar esse contexto em qualquer etapa de um trabalho. Este objeto contém todas as propriedades listadas abaixo.
job.containerobjectInformações sobre o contêiner do trabalho. Para obter mais informações sobre contêineres, confira "Sintaxe de fluxo de trabalho para o GitHub Actions".
job.container.idstringO ID do contêiner.
job.container.networkstringO ID da rede do contêiner. O executor cria a rede usada por todos os contêineres em um trabalho.
job.servicesobjectContêineres de serviços criados para um trabalho. Para obter mais informações sobre contêineres de serviço, confira "Sintaxe de fluxo de trabalho para o GitHub Actions".
job.services.<service_id>.idstringO ID do contêiner de serviço.
job.services.<service_id>.networkstringO ID da rede de contêiner de serviço. O executor cria a rede usada por todos os contêineres em um trabalho.
job.services.<service_id>.portsobjectAs portas expostas do contêiner de serviço.
job.statusstringO estado atual do trabalho. Os valores possíveis são success, failure, ou cancelled.

Exemplo de conteúdo do contexto job

Este exemplo de contexto job usa um contêiner de serviço do PostgreSQL com as portas mapeadas. Se nenhum contêiner ou contêiner de serviço for usado em um trabalho, o contexto job só conterá a propriedade status.

{
  "status": "success",
  "container": {
    "network": "github_network_53269bd575974817b43f4733536b200c"
  },
  "services": {
    "postgres": {
      "id": "60972d9aa486605e66b0dad4abb638dc3d9116f566579e418166eedb8abb9105",
      "ports": {
        "5432": "49153"
      },
      "network": "github_network_53269bd575974817b43f4733536b200c"
    }
  }
}

Exemplo de uso do contexto job

Este exemplo de fluxo de trabalho configura um contêiner de serviço do PostgreSQL e mapeia automaticamente a porta 5432 do recipiente de serviço com uma porta disponível escolhida aleatoriamente no host. O contexto job é usado para acessar o número da porta atribuída no host.

YAML
name: PostgreSQL Service Example
on: push
jobs:
  postgres-job:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres
        env:
          POSTGRES_PASSWORD: postgres
        options: --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5
        ports:
          # Maps TCP port 5432 in the service container to a randomly chosen available port on the host.
          - 5432

    steps:
      - run: pg_isready -h localhost -p ${{ job.services.postgres.ports[5432] }}
      - run: echo "Run tests against Postgres"

Contexto jobs

O contexto jobs só está disponível em fluxos de trabalho reutilizáveis e só pode ser usado para definir as saídas de um fluxo de trabalho reutilizável. Para obter mais informações, confira "Reutilizar fluxos de trabalho".

Nome da propriedadeTypeDescrição
jobsobjectIsso só está disponível em fluxos de trabalho reutilizáveis e só pode ser usado para definir as saídas de um fluxo de trabalho reutilizável. Este objeto contém todas as propriedades listadas abaixo.
jobs.<job_id>.resultstringO resultado de um trabalho no fluxo de trabalho reutilizável. Os valores possíveis são success, failure, cancelled ou skipped.
jobs.<job_id>.outputsobjectO conjunto de saídas de um trabalho em um fluxo de trabalho reutilizável.
jobs.<job_id>.outputs.<output_name>stringO valor de uma saída específica para um trabalho em um fluxo de trabalho reutilizável.

Exemplo de conteúdo do contexto jobs

O contexto jobs deste exemplo contém o resultado e as saídas de um trabalho de uma execução de fluxo de trabalho reutilizável.

{
  "example_job": {
    "result": "success",
    "outputs": {
      "output1": "hello",
      "output2": "world"
    }
  }
}

Exemplo de uso do contexto jobs

Este exemplo de fluxo de trabalho reutilizável usa o contexto jobs para definir saídas para o fluxo de trabalho reutilizável. Observe como as saídas fluem das etapas para o trabalho e, em seguida, para o gatilho workflow_call. Para obter mais informações, confira "Reutilizar fluxos de trabalho".

YAML
name: Reusable workflow

on:
  workflow_call:
    # Map the workflow outputs to job outputs
    outputs:
      firstword:
        description: "The first output string"
        value: ${{ jobs.example_job.outputs.output1 }}
      secondword:
        description: "The second output string"
        value: ${{ jobs.example_job.outputs.output2 }}

jobs:
  example_job:
    name: Generate output
    runs-on: ubuntu-latest
    # Map the job outputs to step outputs
    outputs:
      output1: ${{ steps.step1.outputs.firstword }}
      output2: ${{ steps.step2.outputs.secondword }}
    steps:
      - id: step1
        run: echo "firstword=hello" >> $GITHUB_OUTPUT
      - id: step2
        run: echo "secondword=world" >> $GITHUB_OUTPUT

Contexto steps

O contexto steps contém informações sobre as etapas do trabalho atual que têm uma id especificada e que já foram executadas.

Nome da propriedadeTypeDescrição
stepsobjectEsse contexto altera cada etapa em um trabalho. Você pode acessar esse contexto em qualquer etapa de um trabalho. Este objeto contém todas as propriedades listadas abaixo.
steps.<step_id>.outputsobjectConjunto de saídas definidas para a etapa. Para obter mais informações, confira "Sintaxe de metadados para o GitHub Actions".
steps.<step_id>.conclusionstringO resultado de uma etapa concluída após a aplicação de continue-on-error. Os valores possíveis são success, failure, cancelled ou skipped. Quando uma etapa continue-on-error falha, o outcome é failure, mas a conclusion final é success.
steps.<step_id>.outcomestringO resultado de uma etapa concluída antes da aplicação de continue-on-error. Os valores possíveis são success, failure, cancelled ou skipped. Quando uma etapa continue-on-error falha, o outcome é failure, mas a conclusion final é success.
steps.<step_id>.outputs.<output_name>stringValor de uma saída específica.

Exemplo de conteúdo do contexto steps

Este exemplo de contexto steps mostra duas etapas anteriores que tinham uma id especificada. A primeira etapa tinha a id chamada checkout, e a segunda, generate_number. A etapa generate_number tinha uma saída chamada random_number.

{
  "checkout": {
    "outputs": {},
    "outcome": "success",
    "conclusion": "success"
  },
  "generate_number": {
    "outputs": {
      "random_number": "1"
    },
    "outcome": "success",
    "conclusion": "success"
  }
}

Exemplo de uso do contexto steps

Este exemplo de fluxo de trabalho gera um número aleatório como saída em uma etapa, e uma etapa posterior usa o contexto steps para ler o valor dessa saída.

YAML
name: Generate random failure
on: push
jobs:
  randomly-failing-job:
    runs-on: ubuntu-latest
    steps:
      - name: Generate 0 or 1
        id: generate_number
        run: echo "random_number=$(($RANDOM % 2))" >> $GITHUB_OUTPUT
      - name: Pass or fail
        run: |
          if [[ ${{ steps.generate_number.outputs.random_number }} == 0 ]]; then exit 0; else exit 1; fi

Contexto runner

O contexto runner contém informações sobre o executor que está executando o trabalho atual.

Nome da propriedadeTypeDescrição
runnerobjectEsse contexto altera cada trabalho em uma execução de fluxo de trabalho. Este objeto contém todas as propriedades listadas abaixo.
runner.namestringO nome do executor que executa a tarefa. Esse nome pode não ser exclusivo em uma execução de fluxo de trabalho, pois os executores nos níveis de repositório e organização podem usar o mesmo nome.
runner.osstringO sistema operacional do executor que está executando o trabalho. Os valores possíveis são Linux, Windows, ou macOS.
runner.archstringA arquitetura do executor que está executando o trabalho. Os valores possíveis são X86, X64, ARM ou ARM64.
runner.tempstringO caminho para um diretório temporário no executor. Este diretório é esvaziado no início e no final de cada trabalho. Observe que os arquivos não serão removidos se a conta de usuário do executor não tiver permissão para excluí-los.
runner.tool_cachestringO caminho para o diretório que contém ferramentas pré-instaladas para executores hospedados em GitHub. Para obter mais informações, confira "Usar executores hospedados no GitHub".
runner.debugstringIsso será definido somente se o log de depuração estiver habilitado e sempre tiver o valor de 1. Pode ser útil como um indicador para habilitar a depuração adicional ou o log detalhado em suas etapas de trabalho.
runner.environmentstringO ambiente do executor que realiza a tarefa. Os valores possíveis são: github-hosted para executores hospedados no GitHub fornecidos pelo GitHub e self-hosted para executores auto-hospedados configurados pelo proprietário do repositório.

Exemplo de conteúdo do contexto runner

O contexto de exemplo a seguir é de um executor do Linux hospedado em GitHub.

{
  "os": "Linux",
  "arch": "X64",
  "name": "GitHub Actions 2",
  "tool_cache": "/opt/hostedtoolcache",
  "temp": "/home/runner/work/_temp"
}

Exemplo de uso do contexto runner

Este exemplo de fluxo de trabalho usa o contexto runner para definir o caminho para o diretório temporário e gravar registros e se, o fluxo de trabalho falhar, ele carregará os logs como artefatos.

YAML
name: Build
on: push

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build with logs
        run: |
          mkdir ${{ runner.temp }}/build_logs
          echo "Logs from building" > ${{ runner.temp }}/build_logs/build.logs
          exit 1
      - name: Upload logs on fail
        if: ${{ failure() }}
        uses: actions/upload-artifact@v3
        with:
          name: Build failure logs
          path: ${{ runner.temp }}/build_logs

Contexto secrets

O contexto secrets contém nomes e os valores de segredos que estão disponíveis para a execução de um fluxo de trabalho. O contexto secrets não está disponível para ações compostas por motivos de segurança. Para aprovar um segredo para uma ação composta, é necessário fazê-lo explicitamente como uma entrada. Para obter mais informações sobre segredos, confira "Usar segredos em ações do GitHub".

GITHUB_TOKEN é um segredo que é criado automaticamente para cada execução de fluxo de trabalho e é sempre incluído no contexto secrets. Para obter mais informações, confira "Autenticação automática de token".

Warning

Se um segredo foi usado no trabalho, o GitHub edita automaticamente os segredos impressos no log. Você deve evitar imprimir segredos no log intencionalmente.

Nome da propriedadeTypeDescrição
secretsobjectEsse contexto é o mesmo para cada trabalho em uma execução do fluxo de trabalho. Você pode acessar esse contexto em qualquer etapa de um trabalho. Este objeto contém todas as propriedades listadas abaixo.
secrets.GITHUB_TOKENstringToken criado automaticamente para cada execução do fluxo de trabalho. Para obter mais informações, confira "Autenticação automática de token".
secrets.<secret_name>stringO valor de um segredo específico.

Exemplo de conteúdo do contexto secrets

O exemplo de conteúdo do contexto secrets mostra o GITHUB_TOKEN automático, assim como outros dois segredos disponíveis para a execução de fluxo de trabalho.

{
  "github_token": "***",
  "NPM_TOKEN": "***",
  "SUPERSECRET": "***"
}

Exemplo de uso do contexto secrets

Este exemplo de fluxo de trabalho usa a CLI do GitHub, que requer o GITHUB_TOKEN como o valor para o parâmetro de entrada GH_TOKEN:

YAML
name: Open new issue
on: workflow_dispatch

jobs:
  open-issue:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
    steps:
      - run: |
          gh issue --repo ${{ github.repository }} \
            create --title "Issue title" --body "Issue body"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Contexto strategy

Para fluxos de trabalho com uma matriz, o contexto strategy contém informações sobre a estratégia de execução da matriz para o trabalho atual.

Nome da propriedadeTypeDescrição
strategyobjectEsse contexto altera cada trabalho em uma execução de fluxo de trabalho. Você pode acessar este contexto a partir de qualquer trabalho ou etapa em um fluxo de trabalho. Este objeto contém todas as propriedades listadas abaixo.
strategy.fail-fastbooleanQuando isso é avaliado como true, todos os trabalhos em andamento são cancelados em caso de falha em qualquer trabalho em uma matriz. Para obter mais informações, confira "Sintaxe de fluxo de trabalho para o GitHub Actions".
strategy.job-indexnumberO índice do trabalho atual na matriz. Observação: esse número é um número baseado em zero. O primeiro índice do trabalho na matriz é 0.
strategy.job-totalnumberO número total de trabalhos na matriz. Observação: esse número não é um número baseado em zero. Por exemplo, para uma matriz com quatro trabalhos, o valor de job-total é 4.
strategy.max-parallelnumberO número máximo de trabalhos que podem ser executados simultaneamente quando uma estratégia de trabalho matrix é usada. Para obter mais informações, confira "Sintaxe de fluxo de trabalho para o GitHub Actions".

Exemplo de conteúdo do contexto strategy

O exemplo de conteúdo a seguir do contexto strategy é de uma matriz com quatro trabalhos e foi obtida do trabalho final. Observe a diferença entre o número job-index baseado em zero e job-total, que não é baseado em zero.

{
  "fail-fast": true,
  "job-index": 3,
  "job-total": 4,
  "max-parallel": 4
}

Exemplo de uso do contexto strategy

Este exemplo de fluxo de trabalho usa a propriedade strategy.job-index para definir um nome exclusivo para um arquivo de log para cada trabalho em uma matriz.

YAML
name: Test strategy
on: push

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        test-group: [1, 2]
        node: [14, 16]
    steps:
      - run: echo "Mock test logs" > test-job-${{ strategy.job-index }}.txt
      - name: Upload logs
        uses: actions/upload-artifact@v3
        with:
          name: Build log for job ${{ strategy.job-index }}
          path: test-job-${{ strategy.job-index }}.txt

Contexto matrix

Para fluxos de trabalho com uma matriz, o contexto matrix contém as propriedades definidas no arquivo de fluxo de trabalho que se aplicam ao trabalho atual. Por exemplo, se você configurar uma matriz com as chaves os e node, o objeto de contexto matrix incluirá as propriedades os e node com os valores que estão sendo usados para o trabalho atual.

Não há propriedades padrão no contexto matrix, apenas aquelas que são definidas no arquivo de fluxo de trabalho.

Nome da propriedadeTypeDescrição
matrixobjectEsse contexto só está disponível para trabalhos em uma matriz e em alterações para cada trabalho na execução de um fluxo de trabalho. Você pode acessar este contexto a partir de qualquer trabalho ou etapa em um fluxo de trabalho. Este objeto contém as propriedades listadas abaixo.
matrix.<property_name>stringO valor da propriedade de uma matriz.

Exemplo de conteúdo do contexto matrix

O exemplo a seguir do contexto matrix é de um trabalho em uma matriz que tem as propriedades de matriz os e node definidas no fluxo de trabalho. O trabalho executa a combinação de matriz de um sistema operacional ubuntu-latest e o Node.js versão 16.

{
  "os": "ubuntu-latest",
  "node": 16
}

Exemplo de uso do contexto matrix

Este exemplo de fluxo de trabalho cria uma matriz com as chaves os e node. Ele usa a propriedade matrix.os para definir o tipo de executor de cada trabalho e a propriedade matrix.node para definir a versão do Node.js de cada trabalho.

YAML
name: Test matrix
on: push

jobs:
  build:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]
        node: [14, 16]
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
      - name: Output node version
        run: node --version

Contexto needs

O contexto needs contém as saídas de todos os trabalhos definidos como uma dependência direta do trabalho atual. Observe que isso não inclui trabalhos implicitamente dependentes (por exemplo, trabalhos dependentes de outro dependente). Para obter mais informações sobre como definir as dependências do trabalho, confira "Sintaxe de fluxo de trabalho para o GitHub Actions".

Nome da propriedadeTypeDescrição
needsobjectEsse contexto só é preenchido para execuções de fluxo de trabalho com funções dependentes e as alterações para cada trabalho em uma execução de fluxo de trabalho. Você pode acessar este contexto a partir de qualquer trabalho ou etapa em um fluxo de trabalho. Este objeto contém todas as propriedades listadas abaixo.
needs.<job_id>objectUm único trabalho do qual o trabalho atual depende.
needs.<job_id>.outputsobjectO conjunto de saídas de um trabalho do qual o trabalho atual depende.
needs.<job_id>.outputs.<output name>stringO valor de uma saída específica para um trabalho do qual o trabalho atual depende.
needs.<job_id>.resultstringO resultado de um trabalho do qual depende o trabalho atual. Os valores possíveis são success, failure, cancelled ou skipped.

Exemplo de conteúdo do contexto needs

O exemplo de conteúdo a seguir do contexto needs mostra informações de dois trabalhos dos quais o trabalho atual depende.

{
  "build": {
    "result": "success",
    "outputs": {
      "build_id": "123456"
    }
  },
  "deploy": {
    "result": "failure",
    "outputs": {}
  }
}

Exemplo de uso do contexto needs

Este exemplo de fluxo de trabalho tem três trabalhos: um trabalho build que faz um build, um trabalho deploy que exige o trabalho build e um trabalho debug que exige os trabalhos build e deploy e que será executado somente se houver uma falha no fluxo de trabalho. O trabalho deploy também usa o contexto needs para acessar uma saída do trabalho build.

YAML
name: Build and deploy
on: push

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      build_id: ${{ steps.build_step.outputs.build_id }}
    steps:
      - name: Build
        id: build_step
        run: echo "build_id=$RANDOM" >> $GITHUB_OUTPUT
  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying build ${{ needs.build.outputs.build_id }}"
  debug:
    needs: [build, deploy]
    runs-on: ubuntu-latest
    if: ${{ failure() }}
    steps:
      - run: echo "Failed to build and deploy"

Contexto inputs

O contexto inputs contém propriedades de entrada passadas para uma ação, para um fluxo de trabalho reutilizável ou para um fluxo de trabalho disparado manualmente. Para fluxos de trabalho reutilizáveis, os nomes e os tipos de entrada são definidos na configuração de evento workflow_call de um fluxo de trabalho reutilizável, e os valores de entrada são transmitidos de jobs.<job_id>.with em um fluxo trabalho externo que chama o fluxo de trabalho reutilizável. Para fluxos de trabalho disparados manualmente, as entradas são definidas na configuração de evento de workflow_dispatch de um fluxo de trabalho.

As propriedades no contexto inputs são definidas no arquivo de fluxo de trabalho. Eles estão disponíveis apenas em um fluxo de trabalho reutilizável ou em um fluxo de trabalho acionado pelo workflow_dispatch evento

Nome da propriedadeTypeDescrição
inputsobjectEsse contexto só está disponível em um fluxo de trabalho reutilizável ou em um fluxo de trabalho acionado pelo workflow_dispatch evento. Você pode acessar este contexto a partir de qualquer trabalho ou etapa em um fluxo de trabalho. Este objeto contém as propriedades listadas abaixo.
inputs.<name>string ou number ou boolean ou choiceCada valor de entrada é passado de um fluxo de trabalho externo.

Exemplo de conteúdo do contexto inputs

O conteúdo de exemplo a seguir do contexto inputs é de um fluxo de trabalho que definiu as entradas build_id, deploy_target e perform_deploy.

{
  "build_id": 123456768,
  "deploy_target": "deployment_sys_1a",
  "perform_deploy": true
}

Exemplo de uso do contexto inputs em um fluxo de trabalho reutilizável

Este exemplo de fluxo de trabalho reutilizável usa o contexto inputs para obter os valores e as entradas build_id, deploy_target e perform_deploy que foram transmitidas para o fluxo de trabalho reutilizável do fluxo de trabalho chamador.

YAML
name: Reusable deploy workflow
on:
  workflow_call:
    inputs:
      build_id:
        required: true
        type: number
      deploy_target:
        required: true
        type: string
      perform_deploy:
        required: true
        type: boolean

jobs:
  deploy:
    runs-on: ubuntu-latest
    if: ${{ inputs.perform_deploy }}
    steps:
      - name: Deploy build to target
        run: echo "Deploying build:${{ inputs.build_id }} to target:${{ inputs.deploy_target }}"

Exemplo de uso do contexto inputs em um fluxo de trabalho acionado manualmente

Este exemplo de fluxo de trabalho disparado por um evento de workflow_dispatch usa o contexto inputs para obter os valores de entrada de build_id, deploy_target e perform_deploy que foram passadas para o fluxo de trabalho.

YAML
on:
  workflow_dispatch:
    inputs:
      build_id:
        required: true
        type: string
      deploy_target:
        required: true
        type: string
      perform_deploy:
        required: true
        type: boolean

jobs:
  deploy:
    runs-on: ubuntu-latest
    if: ${{ inputs.perform_deploy }}
    steps:
      - name: Deploy build to target
        run: echo "Deploying build:${{ inputs.build_id }} to target:${{ inputs.deploy_target }}"