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, and GitHub Enterprise Cloud. GitHub Actions is unavailable for per-repository plans, which are legacy billing 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.

Expressions are commonly used with the conditional if keyword in a workflow file to determine whether a step should run. 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

Os contextos são uma forma de acessar informações sobre execuções, ambientes virtuais, trabalhos e etapas dos fluxos de trabalho. 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 string A step, job, or workflow environment variable.
trabalho 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. For more information, see 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."

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

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.

.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
    Objeto 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
Object 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.

Exemplo

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.

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

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

Exemplo
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