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

Sintaxe de expressão e contextos para o GitHub Actions

Você pode acessar informações de contexto e avaliar expressões em fluxos de trabalho e ações.

GitHub Actions is available with GitHub Free, GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub One. GitHub Actions is not available for private repositories owned by accounts using legacy per-repository plans. For more information, see "GitHub's products."

Neste artigo

Sobre contexto e expressões

Você pode usar expressões para configurar variáveis por programação em arquivos de fluxo de trabalho e acessar contextos. Uma expressão pode ser qualquer combinação de valores literais, referências a um contexto ou funções. É possível combinar literais, referências de contexto e funções usando operadores.

Expressões são comumente usadas com a condicional if palavra-chave em um arquivo de fluxo de trabalho para determinar se uma etapa deve ser executada. Quando uma condicional if for true, a etapa será executada.

É necessário usar uma sintaxe específica para avisar o GitHub para avaliar a expressão e não tratá-la como uma string.

${{ <expression> }}

When you use expressions in an if conditional, you do not need to use the expression syntax (${{ }}) because GitHub automatically evaluates the if conditional as an expression. For more information about if conditionals, see "Workflow syntax for GitHub Actions."

Exemplo de expressão em uma condicional if

etapas:
  - uses: actions/hello-world-javascript-action@master
    if: <expression>

Exemplo de configuração de variável de ambiente

env:
  my_env_var: ${{ <expression> }}

Contextos

Contexts are a way to access information about workflow runs, runner environments, jobs, and steps. Contextos usam a sintaxe de expressão.

${{ <context> }}

Nome do contexto Tipo Descrição
github objeto Informações sobre a execução do fluxo de trabalho. Para obter mais informações, consulte contexto github.
env objeto Contains environment variables set in a workflow, job, or step. For more information, see env context .
job objeto Tem informações sobre o trabalho em execução no momento. Para obter mais informações, consulte contexto trabalho.
steps objeto Informações sobre as etapas que foram executadas neste trabalho. Para obter mais informações, consulte contexto etapas.
runner objeto Informações sobre o executor do trabalho atual. Para obter mais informações, consulte runner context.
secrets objeto Habilita o acesso aos segredos definidos no repositório. For more information about secrets, see "Creating and using encrypted secrets."
strategy objeto Habilita 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.
matrix objeto Habilita 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.

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 _.

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. For more information about environment variables, see "Using environment variables."

Warning: When using the whole github context, be mindful that it includes sensitive information such as github.token. GitHub masks secrets when they are printed to the console, but you should be cautious when exporting or printing the context.

Nome da propriedade Tipo Descrição
github objeto Contexto de nível mais alto disponível em qualquer trabalho ou etapa de um fluxo de trabalho.
github.event objeto Carga de evento de webhook completa. Para obter mais informações, consulte "Eventos que acionam fluxos de trabalho".
github.event_path string The path to the full event webhook payload on the runner.
github.workflow string Nome 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.run_id string A unique number for each run within a repository. This number does not change if you re-run the workflow run.
github.run_number string A unique number for each run of a particular workflow in a repository. This number begins at 1 for the workflow's first run, and increments with each new run. This number does not change if you re-run the workflow run.
github.actor string Login do usuário que iniciou a execução do fluxo de trabalho.
github.repository string Nome do repositório e o proprietário. Por exemplo, Codertocat/Hello-World.
github.event_name string Nome do evento que acionou a execução do fluxo de trabalho.
github.sha string Commit SHA que acionou a execução do fluxo de trabalho.
github.ref string Branch ou ref tag que acionou a execução do fluxo de trabalho.
github.head_ref string head_ref ou branch de origem da pull request em uma execução de fluxo de trabalho. Essa propriedade só está disponível quando o evento que aciona a execução do fluxo de trabalho é uma pull_request.
github.base_ref string base_ref ou branch alvo da pull request em uma execução de fluxo de trabalho. Essa propriedade só está disponível quando o evento que aciona a execução do fluxo de trabalho é uma pull_request.
github.token string A token to authenticate on behalf of the GitHub App installed on your repository. This is functionally equivalent to the GITHUB_TOKEN secret. For more information, see "Authenticating with the GITHUB_TOKEN."
github.workspace string The default working directory for steps and the default location of your repository when using the checkout action.
github.action string The name of the action currently running. GitHub removes special characters or uses the name run when the current step runs a script. If you use the same action more than once in the same job, the name will include a suffix with the sequence number. For example, the first script you run will have the name run1, and the second script will be named run2. Similarly, the second invocation of actions/checkout will be actionscheckout2.

env context

The env context contains environment variables that have been set in a workflow, job, or step. For more information about setting environment variables in your workflow, see "Workflow syntax for GitHub Actions."

The env context syntax allows you to use the value of an environment variable in your workflow file. If you want to use the value of an environment variable inside a runner, use the runner operating system's normal method for reading environment variables.

You can only use the env context in the value of the with and name keys, or in a step's if conditional. For more information on the step syntax, see "Workflow syntax for GitHub Actions."

Nome da propriedade Tipo Descrição
env objeto Esse contexto altera cada etapa em um trabalho. Você pode acessar esse contexto em qualquer etapa de um trabalho.
env.<env name> string The value of a specific environment variable.

Contexto trabalho

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

Nome da propriedade Tipo Descrição
trabalho objeto Esse contexto altera cada trabalho em uma execução de fluxo de trabalho. Você pode acessar esse contexto em qualquer etapa de um trabalho.
job.status string Status atual do trabalho. Possíveis valores são success, failure ou cancelled.
job.container objeto Informaçõ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.network string Identificação da rede do contêiner. O executor cria a rede usada por todos os contêineres em um trabalho.
job.container.id string Identificação do contêiner.
job.services objeto Contê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.network string Identificaçã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>.id string Identificação do contêiner de serviço.
job.services.<service id>.ports objeto Portas expostas do contêiner.

Contexto etapas

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

Nome da propriedade Tipo Descrição
steps objeto Esse contexto altera cada etapa em um trabalho. Você pode acessar esse contexto em qualquer etapa de um trabalho.
steps.<step id>.outputs objeto Conjunto de saídas definidas para a etapa. Para obter mais informações, consulte "Sintaxe de metadados para o GitHub Actions".
steps.<step id>.outputs.<output name> string Valor de uma saída específica.

runner context

The runner context contains information about the runner that is executing the current job.

Nome da propriedade Tipo Descrição
os string The operating system of the runner executing the job. Possible values are Linux, Windows, or macOS.
temp string The path of the temporary directory for the runner. This directory is guaranteed to be empty at the start of each job, even on self-hosted runners.
tool_cache string The path of the directory containing some of the preinstalled tools for GitHub-hosted runners. For more information, see "Software installed on GitHub-hosted runners."

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.

Warning: When using the whole github context, be mindful that it includes sensitive information such as github.token. GitHub masks secrets when they are printed to the console, but you should be cautious when exporting or printing the context.

.github/workflows/main.yml

on: push

jobs:
  one:
    runs-on: ubuntu-16.04
    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"

Literais

Como parte da expressão, você pode usar os tipos de dados boolean, null, number ou string. Os literais boolianos não diferenciam maiúsculas de minúsculas, de modo que você pode usar true ou True.

Tipo de dados Valor do literal
boolean true ou false
null null
number Qualquer formato de número aceito por JSON.
string Você deve usar aspas simples. Aspas simples de literal devem ter aspas simples como escape.

Exemplo

env:
  myNull: ${{ null }}
  myBoolean: ${{ false }}
  myIntegerNumber: ${{ 711 }}
  myFloatNumber: ${{ -9.2 }}
  myHexNumber: ${{ 0xff }}
  myExponentialNumber: ${{ -2.99-e2 }}
  myString: ${{ 'Mona the Octocat' }}
  myEscapedString: ${{ 'It''s open source!' }}

Operadores

Operador Descrição
( ) Agrupamento lógico
[ ] Índice
. Desreferência de propriedade
! Não
< Menor que
<= Menor ou igual
> Maior que
>= Maior ou igual
== Igual
!= Não igual
&& E
|| Ou

O GitHub faz comparações livres de igualdade.

  • Se os tipos não correspondem, o GitHub força o tipo para um número. O GitHub converte tipos de dados em um número usando estes esquemas:

    Tipo Resultado
    Nulo 0
    Booleano true retorna 1
    false retorna 0
    string Analisado com base em qualquer formato de número JSON; do contrário, NaN.
    Observação: string vazia retorna 0.
    Array NaN
    Object NaN
  • Uma comparação de um NaN com outro NaN não resulta em true. Para obter mais informações, consulte os "docs NaN Mozilla."

  • O GitHub ignora as maiúsculas e minúsculas ao comparar strings.

  • Objetos e arrays só são considerados iguais quando forem a mesma instância.

Funções

O GitHub oferece um conjunto de funções integradas que podem ser usadas em expressões. Algumas funções convertem valores em uma string para realizar comparações. O GitHub converte tipos de dados em uma string usando estes esquemas:

Tipo Resultado
Nulo ''
Booleano 'true' ou 'false'
Número Formato decimal, exponencial para números altos
Array Arrays não são convertidos em uma string
Objeto Objetos não são convertidos em uma string

contains

contains( searchString, searchValue )

Retorna true se searchString contiver searchValue. Se searchString for um array, essa função retornará true se searchValue for um elemento no array. Essa função não diferencia maiúsculas de minúsculas. Lança valores em uma string.

Exemplo

contains('Hello world', 'llo') retorna true

startsWith

startsWith( searchString, searchValue )

Retorna true quando searchString começar com searchValue. Essa função não diferencia maiúsculas de minúsculas. Lança valores em uma string.

Exemplo

startsWith('Hello world', 'He') retorna true

endsWith

endsWith( searchString, searchValue )

Retorna true se searchString terminar com searchValue. Essa função não diferencia maiúsculas de minúsculas. Lança valores em uma string.

Exemplo

endsWith('Hello world', 'ld') retorna true

format

format( string, replaceValue0, replaceValue1, ..., replaceValueN)

Substitui valores na string pela variável replaceValueN. As variáveis na string são especificadas usando a sintaxe {N}, onde N é um inteiro. Você deve especificar pelo menos um replaceValue e string. Não há máximo para o número de variáveis (replaceValueN) que você pode usar. Use chaves duplas como escape das chaves.

Exemplo

Retorna 'Hello Mona the Octocat'

format('Hello {0} {1} {2}', 'Mona', 'the', 'Octocat')

Exemplo de escape de chaves

Retorna '{Hello Mona the Octocat}'

format('{{Hello {0} {1} {2}}}', 'Mona', 'the', 'Octocat')

join

join( element, optionalElem )

O valor de element pode ser um array ou uma string. Todos os valores em element são concatenados em uma string. Se você fornecer optionalElem, o valor será acrescentado ao fim de element. Lança valores em uma string.

Exemplo de uso de array

join(['Hello', 'Mona', 'the'], 'Octocat') retorna 'Hello Mona the Octocat'

Exemplo de uso de string

join('Hello', 'world!') retorna 'Hello world!'

toJson

toJSON(value)

Retorna uma bela representação JSON de value. Você pode usar essa função para depurar as informações fornecidas em contextos.

Example

toJSON(job) pode retornar { "status": "Success" }

hashFiles

hashFiles(path)

Returns a single hash for the set of files that matches the path pattern. The path is relative to the GITHUB_WORKSPACE directory and can only include files inside of the GITHUB_WORKSPACE. This function calculates an individual SHA-256 hash for each matched file, and then uses those hashes to calculate a final SHA-256 hash for the set of files. For more information about SHA-256, see "SHA-2."

You can use pattern matching characters to match file names. Pattern matching is case-insensitive on Windows. For more information about supported pattern matching characters, see "Workflow syntax for GitHub Actions."

Exemplo

Matches any package-lock.json file in the repository.

hashFiles('**/package-lock.json')

Funções de verificação de status de trabalho

Você pode usar as funções de verificação de status a seguir como expressões nas condicionais if. Se sua expressão if não contiver qualquer uma das funções de status, ela automaticamente resultará em success(). Para obter mais informações sobre condicionais if, consulte "Sintaxe de fluxo de trabalho para o GitHub Actions".

success

Retorna true quando a etapa anterior de um trabalho é bem-sucedida.

Example
etapas:
  - name: my first step
    if: success()

always

Força uma condicional a ser avaliada como true, mesmo quando cancelada. Um trabalho ou uma etapa não será executado(a) quando uma falha crítica impedir a tarefa de ser executada. Por exemplo, se houver falha ao obter as fontes.

Example
if: always()

cancelled

Retornará true se o fluxo de trabalho foi cancelado.

Exemplo
if: cancelled()

failure

Retorna true quando a etapa anterior de um trabalho falha.

Example
etapas:
  - name: my first step
    if: failure()

Filtros de objeto

Você pode usar a sintaxe * para aplicar um filtro e selecionar itens correspondentes em uma coleção.

Por exemplo, pense em um array de objetos de nome frutas.

[
  { "name": "maçã", "quantidade": 1 },
  { "name": "laranja", "quantidade": 2 },
  { "name": "pera", "quantidade": 1 }
]

O filtro frutas.*.name retorna o array [ "maçã", "laranja", "pera" ]

Pergunte a uma pessoa

Não consegue encontrar o que procura?

Entrar em contato