Contextos

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

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 os contextos

Aviso: Ao criar fluxos de trabalho e ações, você sempre deve considerar se seu código pode 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, consulte "Entender o risco de injeções de scripts".

Os contextos são uma forma de acessar informações sobre execuções de fluxo de trabalho, ambientes dos executores, trabalhos e etapas. Contextos usam a sintaxe de expressão. Para obter mais informações, consulte "Expressões".

${{ <context> }}

Nome do contextoTipoDescrição
githubobjetoInformações sobre a execução do fluxo de trabalho. Para obter mais informações, consulte contexto github.
envobjetoContém variáveis de ambiente definidas em um fluxo de trabalho, trabalho ou etapa. Para obter mais informações, consulte o contexto env.
trabalhoobjetoTem informações sobre o trabalho em execução no momento. Para obter mais informações, consulte contexto trabalho.
stepsobjetoInformações sobre as etapas que foram executadas neste trabalho. Para obter mais informações, consulte contexto etapas.
runnerobjetoInformações sobre o executor do trabalho atual. Para obter mais informações, consulte runner context.
secretsobjetoHabilita o acesso a segredos. Para obter mais informações sobre segredos, consulte "Criar e usar segredos encriptados".
strategyobjetoHabilita acesso aos parâmetros de estratégia configurados e informações sobre o trabalho atual. Parâmetros de estratégia incluem fail-fast, job-index, job-total e max-parallel.
matrixobjetoHabilita acesso aos parâmetros de matriz configurados para o trabalho atual. Por exemplo, se você configurar uma criação de matriz com as versões os e node, o objeto de contexto matrix inclui as versões os e node do trabalho atual.
needsobjetoPermite o acesso às saídas de todos os trabalhos definidos como uma dependência do trabalho atual. Para obter mais informações, consulte o contexto needs.

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

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

Para usar a sintaxe de propriedade de desreferência, o nome da propriedade deve:

  • começar com a-Z ou _;
  • ser seguido por a-Z 0-9 - ou _.

Determinar quando usar contextos

GitHub Actions inclui uma coleção de variáveis denominadas contextos e uma coleção similar de variáveis denominadas variáveis de ambiente 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 existem apenas no executor que está executando seu trabalho. Para obter mais informações, consulte "Variáveis de ambiente padrão".
  • Contextos: Você pode usar a maioria dos contextos em qualquer ponto do seu fluxo de trabalho, incluindo quando as variáveis de ambiente padrão estariam indisponíveis. Por exemplo, você pode usar contextos com expressões para realizar 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 condicional if para determinar se uma etapa deve ser executada. Assim que o trabalho estiver em execução, você também poderá recuperar as variáveis de contexto do executor que está executando o trabalho, como runner.os. Para obter informações sobre onde você pode usar vários contextos dentro de um fluxo de trabalho, consulte "Disponibilidade de contexto".

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

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, o comando if verifica o github.ref para determinar o nome do branch atual. Se o nome for refs/heads/main, as etapas subsequentes serão executadas. A verificação if é processada por GitHub Actions, e o trabalho é enviado apenas para o executor se o resultado for verdadeiro. Assim que o trabalho é enviado para o executor, a etapa é executada e refere-se à variável de ambiente $GITHUB_REF do executor.

Contexto github

O contexto github context contém informações sobre a execução do fluxo de trabalho e sobre o evento que a acionou. Você pode ler a maioria dos dados de contexto github em variáveis de ambiente. Para obter mais informações sobre as variáveis de ambiente, consulte "Usando variáveis de ambiente".

Aviso: Ao usar todo o contexto do github, tenha em mente 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.

Aviso: Ao criar fluxos de trabalho e ações, você sempre deve considerar se seu código pode 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, consulte "Entender o risco de injeções de scripts".

Nome da propriedadeTipoDescrição
githubobjetoContexto de nível mais alto disponível em qualquer trabalho ou etapa de um fluxo de trabalho.
github.actionstringO nome da ação atualmente em execução. GitHub remove caracteres especiais ou usa o nome __run quando a etapa atual executa um script. 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á denominado __run_2. Da mesma forma, a segunda invocação de actions/checkout será actionscheckout2.
github.action_pathstringO caminho onde está localizada a sua ação. Você pode usar esse caminho para acessar facilmente os arquivos localizados no mesmo repositório que sua ação. Este atributo é compatível apenas em ações compostas.
github.actorstringLogin do usuário que iniciou a execução do fluxo de trabalho.
github.base_refstringbase_ref ou branch alvo da pull request em uma execução de fluxo de trabalho. Esta propriedade só está disponível quando o evento que aciona a execução de um fluxo de trabalho for pull_request ou pull_request_target.
github.eventobjetoCarga de evento de webhook completa. Para obter mais informações, consulte "Eventos que acionam fluxos de trabalho". Você pode acessar as propriedades individuais do evento usando este contexto.
github.event_namestringNome do evento que acionou a execução do fluxo de trabalho.
github.event_pathstringO caminho para a carga completa do evento do webhook no executor.
github.head_refstringhead_ref ou branch de origem da pull request em uma execução de fluxo de trabalho. Esta propriedade só está disponível quando o evento que aciona a execução de um fluxo de trabalho for pull_request ou pull_request_target.
github.jobstringO job_id do trabalho atual.
github.refstringBranch ou ref tag que acionou a execução do fluxo de trabalho. Para branches, este é o formato refs/heads/<branch_name> e, para tags, é refs/tags/<tag_name>.
github.repositorystringNome do repositório e o proprietário. Por exemplo, Codertocat/Hello-World.
github.repository_ownerstringO nome do proprietário do repositório. Por exemplo, Codertocat.
github.run_idstringUm número exclusivo para cada execução 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. Este número começa em 1 para a primeira execução do fluxo de trabalho, e incrementa a cada nova execuçã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.server_urlstringRetorna a URL do servidor GitHub. Por exemplo: https://github.com.
github.shastringCommit SHA que acionou a execução do fluxo de trabalho.
github.tokenstringUm token para fazer a autenticação em nome do aplicativo GitHub instalado no seu repositório. Isso é funcionalmente equivalente ao segredo GITHUB_TOKEN. Para obter mais informações, consulte "Permissões para o GITHUB_TOKEN".
github.workflowstringNome do fluxo de trabalho. Se o fluxo de trabalho não determina um name (nome), o valor desta propriedade é o caminho completo do arquivo do fluxo de trabalho no repositório.
github.workspacestringO diretório-padrão de trabalho para etapas e a localização-padrão do repositório ao usar a ação checkout-.

Contexto env

O contexto env contém variáveis de ambiente que foram definidas em um fluxo de trabalho, trabalho ou etapa. Para obter mais informações sobre como configurar variáveis de ambiente em seu fluxo de trabalho, consulte "Sintaxe do fluxo de trabalho para GitHub Actions".

A sintaxe de contexto env permite que você use o valor de uma variável de ambiente no seu arquivo de fluxo de trabalho. Você pode usar o contexto env no valor de qualquer chave em uma etapa, exceto para as chaves id e uses. Para obter mais informações sobre a sintaxe da etapa, consulte "Sintaxe do fluxo de trabalho para o GitHub Actions".

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

Nome da propriedadeTipoDescrição
envobjetoEsse contexto altera cada etapa em um trabalho. Você pode acessar esse contexto em qualquer etapa de um trabalho.
env.<env_name>stringO valor de uma variável de ambiente específica.

Contexto trabalho

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

Nome da propriedadeTipoDescrição
trabalhoobjetoEsse contexto altera cada trabalho em uma execução de fluxo de trabalho. Você pode acessar esse contexto em qualquer etapa de um trabalho.
job.containerobjetoInformações sobre o contêiner do trabalho. Para obter mais informações sobre contêineres, consulte "Sintaxe de fluxo de trabalho para o GitHub Actions".
job.container.idstringIdentificação do contêiner.
job.container.networkstringIdentificação da rede do contêiner. O executor cria a rede usada por todos os contêineres em um trabalho.
job.servicesobjetoContêineres de serviços criados para um trabalho. Para obter mais informações sobre contêineres de serviço, consulte "Sintaxe de fluxo de trabalho para o GitHub Actions".
job.services.<service id>.idstringIdentificação do contêiner de serviço.
job.services.<service id>.networkstringIdentificação da rede do contêiner de serviço. O executor cria a rede usada por todos os contêineres em um trabalho.
job.services.<service id>.portsobjetoAs portas expostas do contêiner de serviço.
job.statusstringStatus atual do trabalho. Possíveis valores são success, failure ou cancelled.

Contexto etapas

O contexto steps (etapas) contém informações sobre as etapas já executadas do trabalho atual.

Nome da propriedadeTipoDescrição
stepsobjetoEsse contexto altera cada etapa em um trabalho. Você pode acessar esse contexto em qualquer etapa de um trabalho.
steps.<step id>.outputsobjetoConjunto de saídas definidas para a etapa. Para obter mais informações, consulte "Sintaxe de metadados para o GitHub Actions".
steps.<step id>.conclusionstringO resultado de uma etapa concluída após continue-on-error ser aplicado. Os valores possíveis são: sucesso, falha, canceladoou ignorado. Quando ocorre uma falha na etapa de continue-on-error, o resultado será falha, mas a conclusão final será sucesso.
steps.<step id>.outcomestringO resultado de uma etapa concluída antes de continue-on-error ser aplicado. Os valores possíveis são: sucesso, falha, canceladoou ignorado. Quando ocorre uma falha na etapa de continue-on-error, o resultado será falha, mas a conclusão final será sucesso.
steps.<step id>.outputs.<output name>stringValor de uma saída específica.

Contexto do executor

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

Nome da propriedadeTipoDescrição
runner.namestringThe name of the runner executing the job.
runner.osstringO sistema operacional do executor que está executando o trabalho. Os valores possíveis são: Linux, Windows ou macOS.
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, consulte "Especificações para executores hospedados no GitHub".

Contexto needs

O contexto needs contém saídas de todos os trabalhos definidos como uma dependência do trabalho atual. Para obter mais informações sobre a definição de dependências de tarefas, consulte "Sintaxe de fluxo de trabalho para o GitHub Actions".

Nome da propriedadeTipoDescrição
needs.<job id>objetoUm único trabalho do qual o trabalho atual depende.
needs.<job id>.outputsobjetoO 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: sucesso, falha, canceladoou ignorado.

Exemplo de impressão de informações de contexto no arquivo de log

Para inspecionar as informações acessíveis em cada contexto, você pode usar este exemplo de arquivo de fluxo de trabalho.

Aviso: Ao usar todo o contexto do github, tenha em mente 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.

.github/workflows/main.yml

on: push

jobs:
  one:
    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"

Disponibilidade do contexto

Contextos diferentes estão disponíveis durante a execução de um fluxo de trabalho. Por exemplo, o contexto de segredos só pode ser usado em certos lugares dentro 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 qualquer lugar.

A tabela a seguir indica onde cada contexto e função especial pode ser utilizado dentro de um fluxo de trabalho. A menos que esteja listado abaixo, uma função pode ser usada em qualquer lugar.

CaminhoContextoFunções especiais
concorrênciagithub
envgithub, secrets
jobs.<job_id>.concurrencygithub, needs, strategy, matrix
jobs.<job_id>.containergithub, needs, strategy, matrix
jobs.<job_id>.container.credentialsgithub, needs, strategy, matrix, env, secrets
jobs.<job_id>.container.env.<env_id>github, needs, strategy, matrix, job, runner, env, secrets
jobs.<job_id>.continue-on-errorgithub, needs, strategy, matrix
jobs.<job_id>.defaults.rungithub, needs, strategy, matrix, env
jobs.<job_id>.envgithub, needs, strategy, matrix, secrets
jobs.<job_id>.environmentgithub, needs, strategy, matrix
jobs.<job_id>.environment.urlgithub, needs, strategy, matrix, job, runner, env, steps
jobs.<job_id>.ifgithub, needsalways, cancelled, success, failure
jobs.<job_id>.namegithub, needs, strategy, matrix
jobs.<job_id>.outputs.<output_id>github, needs, strategy, matrix, job, runner, env, secrets, steps
jobs.<job_id>.runs-ongithub, needs, strategy, matrix
jobs.<job_id>.servicesgithub, needs, strategy, matrix
jobs.<job_id>.services.<service_id>.credentialsgithub, needs, strategy, matrix, env, secrets
jobs.<job_id>.services.<service_id>.env.<env_id>github, needs, strategy, matrix, job, runner, env, secrets
jobs.<job_id>.steps.continue-on-errorgithub, needs, strategy, matrix, job, runner, env, secrets, stepshashFiles
jobs.<job_id>.steps.envgithub, needs, strategy, matrix, job, runner, env, secrets, stepshashFiles
jobs.<job_id>.steps.ifgithub, needs, strategy, matrix, job, runner, env, stepsalways, cancelled, success, failure, hashFiles
jobs.<job_id>.steps.namegithub, needs, strategy, matrix, job, runner, env, secrets, stepshashFiles
jobs.<job_id>.steps.rungithub, needs, strategy, matrix, job, runner, env, secrets, stepshashFiles
jobs.<job_id>.steps.timeout-minutesgithub, needs, strategy, matrix, job, runner, env, secrets, stepshashFiles
jobs.<job_id>.steps.withgithub, needs, strategy, matrix, job, runner, env, secrets, stepshashFiles
jobs.<job_id>.steps.working-directorygithub, needs, strategy, matrix, job, runner, env, secrets, stepshashFiles
jobs.<job_id>.strategygithub, needs
jobs.<job_id>.timeout-minutesgithub, needs, strategy, matrix

Esse documento ajudou você?

Política de Privacidade

Ajude-nos a tornar esses documentos ótimos!

Todos os documentos do GitHub são de código aberto. Você percebeu que algo que está errado ou não está claro? Envie um pull request.

Faça uma contribuição

Ou, aprenda como contribuir.