Skip to main content

Variáveis

GitHub define variáveis padrão para cada execução do fluxo de trabalho de GitHub Actions. Você também pode definir variáveis personalizadas no seu arquivo do fluxo de trabalho.

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

Sobre variáveis

Você pode usar variáveis para armazenar informações que deseja referenciar no seu fluxo de trabalho. Você faz referência a variáveis em uma etapa do fluxo de trabalho ou em uma ação, e as variáveis são interpoladas na máquina que executa seu fluxo de trabalho. Os comandos que são executados em ações ou etapas do fluxo de trabalho podem criar, ler e modificar variáveis.

Você pode definir variáveis personalizadas próprias, usar as variáveis padrão que o GitHub define automaticamente, ou ainda usar qualquer outra variável definida no ambiente de trabalho do executor. As variáveis diferenciam maiúsculas de minúsculas.

Definindo variáveis de ambiente

Ao definir uma variável de ambiente personalizada, é possível faze-lo usando a chave env do arquivo do fluxo de trabalho. O escopo de uma variável personalizada definida por este método fica limitado ao elemento em que ele está definido. Você pode definir variáveis cujos escopos são definidos como:

  • Todo o fluxo de trabalho, usando env no nível superior do arquivo de fluxo de trabalho.
  • O conteúdo de um trabalho em um fluxo de trabalho, usando jobs.<job_id>.env.
  • Uma etapa específica em um trabalho, usando jobs.<job_id>.steps[*].env.
name: Greeting on variable day

on:
  workflow_dispatch

env:
  DAY_OF_WEEK: Monday

jobs:
  greeting_job:
    runs-on: ubuntu-latest
    env:
      Greeting: Hello
    steps:
      - name: "Say Hello Mona it's Monday"
        run: echo "$Greeting $First_Name. Today is $DAY_OF_WEEK!"
        env:
          First_Name: Mona

Você pode acessar env valores de variáveis usando as variáveis de ambiente do executor ou usando contextos. O exemplo acima mostra três variáveis personalizadas sendo usadas como variáveis de ambiente em um comando echo: $DAY_OF_WEEK, $Greeting e $First_Name. Os valores e os escopos dessas variáveis são definidos no nível do fluxo de trabalho, do trabalho e da etapa, respectivamente. Para obter mais informações sobre como acessar valores de variáveis usando contextos, confira "Como usar contextos para acessar valores de variáveis".

Como a interpolação de variável de ambiente do executor é feita depois que um trabalho do fluxo de trabalho é enviado para uma máquina do executor, você deve usar a sintaxe apropriada para o shell usado no executor. Neste exemplo, o fluxo de trabalho especifica ubuntu-latest. Por padrão, os executores do Linux usam o shell do Bash. Portanto, você precisa usar a sintaxe $NAME. Se o fluxo de trabalho especificou um executor do Windows, use a sintaxe do PowerShell, $env:NAME. Para obter mais informações sobre os shells, confira "Sintaxe de fluxo de trabalho do GitHub Actions".

Convenções de nomenclatura para variáveis de ambiente

Ao definir uma variável de ambiente, você não pode usar nenhum dos nomes das variáveis de ambiente padrão. Para obter uma lista completa das variáveis de ambiente padrão, confira "Variáveis de ambiente padrão", abaixo. Se você tentar substituir o valor de uma dessas variáveis padrão, a atribuição será ignorada.

Qualquer nova variável que você definir e apontar para uma localização no sistema de arquivos deverá ter um sufixo _PATH. As variáveis padrão GITHUB_ENV e GITHUB_WORKSPACE são exceções a essa convenção.

Observação: você pode listar todo o conjunto de variáveis de ambiente disponíveis para uma etapa de fluxo de trabalho usando run: env em uma etapa e examinando a saída da etapa.

Como usar contextos para acessar valores de variáveis

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. Para obter mais informações, confira "Contextos". Há muitos outros contextos que você pode usar para uma série de finalidades nos seus fluxos de trabalho. Para obter detalhes sobre quando usar contextos específicos em um fluxo de trabalho, confira "Disponibilidade de contexto".

Você pode acessar valores de variáveis de ambiente usando o contexto env.

Como usar o contexto env para acessar valores de variáveis de ambiente

Além das variáveis de ambiente do executor, GitHub Actions permite que você defina e leia valores da chave env usando contextos. As variáveis e os contextos do ambiente são destinados a serem usados em diferentes pontos do fluxo de trabalho.

As variáveis de ambiente do executor são sempre interpoladas no computador do executor. No entanto, as partes de um fluxo de trabalho são processadas por GitHub Actions e não são enviadas para o executor. Não é possível usar variáveis de ambiente nessas partes de um arquivo de fluxo de trabalho. Em vez disso, pode-se utilizar contextos. Por exemplo, um condicional if, que determina se uma etapa ou um trabalho é enviado ao executor, sempre será processado pelo GitHub Actions. Você pode usar um contexto em uma instrução condicional if para acessar o valor de uma variável.

env:
  DAY_OF_WEEK: Monday

jobs:
  greeting_job:
    runs-on: ubuntu-latest
    env:
      Greeting: Hello
    steps:
      - name: "Say Hello Mona it's Monday"
        if: ${{ env.DAY_OF_WEEK == 'Monday' }}
        run: echo "$Greeting $First_Name. Today is $DAY_OF_WEEK!"
        env:
          First_Name: Mona

Nessa modificação do exemplo anterior, introduzimos um if condicional. A etapa de fluxo de trabalho agora só será executada se DAYS_OF_WEEK estiver definido como "Segunda-feira". Acessamos esse valor por meio da instrução condicional if usando o contexto env.

Observação: os contextos geralmente são indicados pelo sinal de cifrão e chaves, como ${{ context.property }}. Em um condicional if, o ${{ e o }} são opcionais, mas se você usá-los, eles precisarão incluir toda a instrução de comparação, conforme mostrado acima.

Normalmente, você usará o contexto env ou github para acessar valores de variáveis em partes do fluxo de trabalho processadas antes que os trabalhos sejam enviados aos executores.

ContextoCaso de usoExemplo
envVariáveis personalizadas de referência definidas no fluxo de trabalho.${{ env.MY_VARIABLE }}
githubInformações de referência sobre a execução do fluxo de trabalho e o evento que acionou a execução.${{ github.repository }}

Variáveis de ambiente padrão

As variáveis de ambiente padrão que os conjuntos de GitHub estão disponíveis para cada etapa de um fluxo de trabalho.

É altamente recomendável que as ações usem variáveis para acessar o sistema do arquivo em vez de usar caminhos de arquivo embutidos no código. O GitHub define as variáveis para ações a serem usadas em todos os ambientes do executor.

VariávelDescrição
CISempre defina como true.
GITHUB_ACTIONO nome da ação atualmente em execução ou a id de uma etapa. Por exemplo, para uma ação, __repo-owner_name-of-action-repo.

O GitHub remove caracteres especiais ou usa o nome __run quando a etapa atual executa um script sem uma id. Se você usar o mesmo script ou ação mais de uma vez no mesmo trabalho, o nome incluirá um sufixo que consiste do número de sequência precedido por um sublinhado. 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_PATHO caminho onde uma ação está localizada. Esta propriedade só é compatível com ações compostas. Você pode usar este caminho para acessar arquivos localizados no mesmo repositório da ação. Por exemplo, /home/runner/work/_actions/repo-owner/name-of-action-repo/v1.
GITHUB_ACTION_REPOSITORYPara uma etpa que executa uma ação, este é o nome do proprietário e do repositório da ação. Por exemplo, actions/checkout.
GITHUB_ACTIONSDefina isso sempre como truequando o GitHub Actions estiver executando o fluxo de trabalho. Você pode usar esta variável para diferenciar quando os testes estão sendo executados localmente ou por GitHub Actions.
GITHUB_ACTORNome da pessoa ou aplicativo que iniciou o fluxo de trabalho. Por exemplo, octocat.
GITHUB_BASE_REFO nome de referência da base ou o branch de destino da solicitação de pull na execução de um fluxo de trabalho. Isso só é definido quando o evento que dispara uma execução de fluxo de trabalho é pull_request ou pull_request_target. Por exemplo, main.
GITHUB_HEAD_REFA referência principal ou o branch da fonte da solicitação de pull na execução de um fluxo de trabalho. Essa propriedade só é definida quando o evento que dispara uma execução de fluxo de trabalho é pull_request ou pull_request_target. Por exemplo, feature-branch-1.
GITHUB_SHAO 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.

Observação:

  • Caso precise usar uma URL de execução de fluxo de trabalho em um trabalho, combine estas variáveis: $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID
  • A maioria das variáveis padrão tem uma propriedade de contexto correspondente e nomeada de modo semelhante. Por exemplo, o valor da variável GITHUB_REF pode ser lido durante o processamento do fluxo de trabalho por meio da propriedade de contexto ${{ github.ref }}.

Detectando o sistema operacional

Você pode escrever um arquivo de fluxo de trabalho individual que pode ser usado para diferentes sistemas operacionais usando a variável de ambiente RUNNER_OS padrão e a propriedade de contexto correspondente ${{ runner.os }}. Por exemplo, o fluxo de trabalho a seguir poderá ser executado com sucesso se você alterar o sistema operacional de macos-latest para windows-latest sem precisar alterar a sintaxe das variáveis de ambiente, que varia conforme o shell que está sendo usado pelo executor.

jobs:
  if-Windows-else:
    runs-on: macos-latest
    steps:
      - name: condition 1
        if: runner.os == 'Windows'
        run: echo "The operating system on the runner is $env:RUNNER_OS."
      - name: condition 2
        if: runner.os != 'Windows'
        run: echo "The operating system on the runner is not Windows, it's $RUNNER_OS."

Neste exemplo, as duas instruções if verificam a propriedade os do contexto runner para determinar o sistema operacional do executor. Os condicionais if são processados pelo GitHub Actions, e somente as etapas em que a verificação resolve como true são enviadas ao executor. Aqui, uma das verificações sempre será true e a outra false. Portanto, apenas uma dessas etapas será enviada ao executor. Assim que o trabalho for enviado ao executor, a etapa será executada e a variável de ambiente no comando echo será interpolada com a sintaxe apropriada ($env:NAME para o PowerShell no Windows e $NAME para o Bash e o sh no Linux e no macOS). Neste exemplo, a instrução runs-on: macos-latest significa que a segunda etapa será executada.

Passando valores entre etapas e trabalhos em um fluxo de trabalho

Se você gerar um valor em uma etapa de um trabalho, poderá usar o valor em etapas posteriores do mesmo trabalho atribuindo o valor a uma variável de ambiente nova ou existente e gravando isso no arquivo de ambiente GITHUB_ENV. O arquivo de ambiente pode ser usado diretamente por uma ação ou em um comando do shell no arquivo de fluxo de trabalho usando a palavra-chave run. Para obter mais informações, confira "Comandos do fluxo de trabalho do GitHub Actions".

Se você deseja passar um valor de uma etapa de um trabalho em um fluxo de trabalho para uma etapa de outro trabalho no fluxo de trabalho, você poderá definir o valor como uma saída de trabalho. Em seguida, você poderá fazer referência a saída desse trabalho a partir de uma etapa em outro trabalho. Para obter mais informações, confira "Sintaxe de fluxo de trabalho do GitHub Actions".