Comandos de fluxo de trabalho para o GitHub Actions

Sobre os comandos do fluxo de trabalho

As ações podem comunicar-se com a máquina do executor para definir as variáveis de ambiente, valores de saída usados por outras ações, adicionar mensagens de depuração aos registros de saída e outras tarefas.

A maioria dos comandos do fluxo de trabalho usa o comando echo em um formato específico, enquanto outros são chamados pela gravação em um arquivo. Para obter mais informações, confira Arquivos de ambiente.

Exemplo de um comando de fluxo de trabalho

echo "::workflow-command parameter1={data},parameter2={data}::{command value}"

Write-Output "::workflow-command parameter1={data},parameter2={data}::{command value}"

Usar comandos do fluxo de trabalho para acessar funções do kit de de ferramentas

O actions/toolkit inclui várias funções que podem ser executadas como comandos do fluxo de trabalho. Use a sintaxe :: para executar os comandos do fluxo de trabalho no arquivo YAML. Em seguida, esses comandos são enviados ao executor por meio do stdout. Por exemplo, em vez de usar o código para definir uma saída, como abaixo:

core.setOutput('SELECTED_COLOR', 'green');

Exemplo: definição de um valor

Use o comando set-output no fluxo de trabalho para definir o mesmo valor:

      - name: Set selected color
        run: echo '::set-output name=SELECTED_COLOR::green'
        id: random-color-generator
      - name: Get color

        run: echo "The selected color is ${{ steps.random-color-generator.outputs.SELECTED_COLOR }}"

      - name: Set selected color
        run: Write-Output "::set-output name=SELECTED_COLOR::green"
        id: random-color-generator
      - name: Get color

        run: Write-Output "The selected color is ${{ steps.random-color-generator.outputs.SELECTED_COLOR }}"

A tabela a seguir mostra quais funções do conjunto de ferramentas estão disponíveis dentro de um fluxo de trabalho:

Definir um parâmetro de saída

Configura um parâmetro de saída da ação.

::set-output name={name}::{value}

Opcionalmente, você também pode declarar os parâmetros de saída no arquivo de metadados de uma ação. Para obter mais informações, confira "Sintaxe de metadados para o GitHub Actions".

Você pode usar escape em cadeias de caracteres multilinha para definir um parâmetro de saída criando uma variável de ambiente a ser usada em um comando de fluxo de trabalho. Para obter mais informações, confira "Como configurar uma variável de ambiente".

Exemplo: definição de um parâmetro de saída

echo "::set-output name=action_fruit::strawberry"

Write-Output "::set-output name=action_fruit::strawberry"

Configurar uma mensagem de depuração

Imprime uma mensagem de erro no log. Você precisa criar um segredo chamado ACTIONS_STEP_DEBUG com o valor true para ver as mensagens de depuração definidas por esse comando no log. Para obter mais informações, confira "Habilitando o log de depuração".

::debug::{message}

Exemplo: definição de uma mensagem de depuração

echo "::debug::Set the Octocat variable"

Write-Output "::debug::Set the Octocat variable"

Configurando uma mensagem de aviso

Cria uma mensagem de aviso e a imprime no registro. Esta mensagem criará uma anotação, que pode associar a mensagem a um arquivo em particular no repositório. Opcionalmente, sua mensagem pode especificar uma posição dentro do arquivo.

::notice file={name},line={line},endLine={endLine},title={title}::{message}

Exemplo: definição de uma mensagem de aviso

echo "::notice file=app.js,line=1,col=5,endColumn=7::Missing semicolon"

Write-Output "::notice file=app.js,line=1,col=5,endColumn=7::Missing semicolon"

Configurar uma mensagem de aviso

Cria uma mensagem de aviso e a imprime no log. Esta mensagem criará uma anotação, que pode associar a mensagem a um arquivo em particular no repositório. Opcionalmente, sua mensagem pode especificar uma posição dentro do arquivo.

::warning file={name},line={line},endLine={endLine},title={title}::{message}

Exemplo: definição de uma mensagem de aviso

echo "::warning file=app.js,line=1,col=5,endColumn=7::Missing semicolon"

Write-Output "::warning file=app.js,line=1,col=5,endColumn=7::Missing semicolon"

Configurar uma mensagem de erro

Cria uma mensagem de erro e a imprime no log. Esta mensagem criará uma anotação, que pode associar a mensagem a um arquivo em particular no repositório. Opcionalmente, sua mensagem pode especificar uma posição dentro do arquivo.

::error file={name},line={line},endLine={endLine},title={title}::{message}

Exemplo: definição de uma mensagem de erro

echo "::error file=app.js,line=1,col=5,endColumn=7::Missing semicolon"

Write-Output "::error file=app.js,line=1,col=5,endColumn=7::Missing semicolon"

Agrupar linhas dos registros

Cria um grupo expansível no registro. Para criar um grupo, use o comando group e especifique um title. Qualquer coisa que você imprimir no log entre os comandos group e endgroup estará aninhada dentro de uma entrada expansível no log.

::group::{title}
::endgroup::

Exemplo: agrupamento de linhas de log

jobs:
  bash-example:
    runs-on: ubuntu-latest
    steps:
      - name: Group of log lines
        run: |
            echo "::group::My title"
            echo "Inside group"
            echo "::endgroup::"

jobs:
  powershell-example:
    runs-on: windows-latest
    steps:
      - name: Group of log lines
        run: |
            Write-Output "::group::My title"
            Write-Output "Inside group"
            Write-Output "::endgroup::"

Como mascarar um valor em um registro

::add-mask::{value}

Mascarar um valor evita que uma string ou variável seja impressa no log. Cada palavra mascarada separada por um espaço em branco é substituída pelo caractere *. Use uma variável de ambiente ou uma cadeia de caracteres para o value da máscara. Quando você mascara um valor, ele é tratado como um segredo e será redigido no executor. Por exemplo, depois de mascarar um valor, você não poderá definir esse valor como uma saída.

Exemplo: mascaramento de uma cadeia de caracteres

Ao imprimir "Mona The Octocat" no log, você verá "***".

echo "::add-mask::Mona The Octocat"

Write-Output "::add-mask::Mona The Octocat"

Exemplo: mascaramento de uma variável de ambiente

Ao imprimir a variável MY_NAME ou o valor "Mona The Octocat" no log, você verá "***" em vez de "Mona The Octocat".

jobs:
  bash-example:
    runs-on: ubuntu-latest
    env:
      MY_NAME: "Mona The Octocat"
    steps:
      - name: bash-version
        run: echo "::add-mask::$MY_NAME"

jobs:
  powershell-example:
    runs-on: windows-latest
    env:
      MY_NAME: "Mona The Octocat"
    steps:
      - name: powershell-version
        run: Write-Output "::add-mask::$env:MY_NAME"

Exemplo: mascarar uma saída gerada em um único trabalho

Se você não precisar passar seu segredo de um trabalho para outro, poderá:

1. Gerar o segredo (sem transmiti-lo).

2. Mascarar com add-mask.

3. Usar set-output para disponibilizar o segredo para outras etapas dentro do trabalho.

on: push
jobs:
  generate-a-secret-output:
    runs-on: ubuntu-latest
    steps:
      - id: sets-a-secret
        name: Generate, mask, and output a secret
        run: |
          the_secret=$((RANDOM))
          echo "::add-mask::$the_secret"
          echo "::set-output name=secret-number::$the_secret"
      - name: Use that secret output (protected by a mask)
        run: |
          echo "the secret number is ${{ steps.sets-a-secret.outputs.secret-number }}"

on: push
jobs:
  generate-a-secret-output:
    runs-on: ubuntu-latest
    steps:
      - id: sets-a-secret
        name: Generate, mask, and output a secret
        shell: pwsh
        run: |
          Set-Variable -Name TheSecret -Value (Get-Random)
          Write-Output "::add-mask::$TheSecret"
          Write-Output "::set-output name=secret-number::$TheSecret"
      - name: Use that secret output (protected by a mask)
        shell: pwsh
        run: |
          Write-Output "the secret number is ${{ steps.sets-a-secret.outputs.secret-number }}"

Exemplo: mascarar e passar um segredo entre trabalhos ou fluxos de trabalho

Se você quiser passar um segredo mascarado entre trabalhos ou fluxos de trabalho, deverá armazená-lo em um repositório e recuperá-lo no trabalho ou fluxo de trabalho subsequente.

Instalação

1. Configure um repositório secreto para armazenar o segredo que você gerará durante o fluxo de trabalho. Por exemplo, um cofre.
2. Gere uma chave para leitura e gravação nesse repositório secreto. Armazene a chave como um segredo do repositório. No fluxo de trabalho no exemplo a seguir, o nome do segredo é SECRET_STORE_CREDENTIALS. Para obter mais informações, confira "Segredos criptografados".

Fluxo de trabalho

on: push

jobs:
  secret-generator:
    runs-on: ubuntu-latest
    steps:
    - uses: some/secret-store@v1
      with:
        credentials: ${{ secrets.SECRET_STORE_CREDENTIALS }}
        instance: ${{ secrets.SECRET_STORE_INSTANCE }}
    - name: generate secret
      shell: bash
      run: |
        GENERATED_SECRET=$((RANDOM))
        echo "::add-mask::$GENERATED_SECRET"
        SECRET_HANDLE=$(secret-store store-secret "$GENERATED_SECRET")
        echo "::set-output name=handle::$secret_handle"
  secret-consumer:
    runs-on: macos-latest
    needs: secret-generator
    steps:
    - uses: some/secret-store@v1
      with:
        credentials: ${{ secrets.SECRET_STORE_CREDENTIALS }}
        instance: ${{ secrets.SECRET_STORE_INSTANCE }}
    - name: use secret
      shell: bash
      run: |
        SECRET_HANDLE="${{ needs.secret-generator.outputs.handle }}"
        RETRIEVED_SECRET=$(secret-store retrieve-secret "$SECRET_HANDLE")
        echo "::add-mask::$RETRIEVED_SECRET"
        echo "We retrieved our masked secret: $RETRIEVED_SECRET"

on: push

jobs:
  secret-generator:
    runs-on: ubuntu-latest
    steps:
    - uses: some/secret-store@v1
      with:
        credentials: ${{ secrets.SECRET_STORE_CREDENTIALS }}
        instance: ${{ secrets.SECRET_STORE_INSTANCE }}
    - name: generate secret
      shell: pwsh
      run: |
        Set-Variable -Name Generated_Secret -Value (Get-Random)
        Write-Output "::add-mask::$Generated_Secret"
        Set-Variable -Name Secret_Handle -Value (Store-Secret "$Generated_Secret")
        Write-Output "::set-output name=handle::$Secret_Handle"
  secret-consumer:
    runs-on: macos-latest
    needs: secret-generator
    steps:
    - uses: some/secret-store@v1
      with:
        credentials: ${{ secrets.SECRET_STORE_CREDENTIALS }}
        instance: ${{ secrets.SECRET_STORE_INSTANCE }}
    - name: use secret
      shell: pwsh
      run: |
        Set-Variable -Name Secret_Handle -Value "${{ needs.secret-generator.outputs.handle }}"
        Set-Variable -Name Retrieved_Secret -Value (Retrieve-Secret "$Secret_Handle")
        echo "::add-mask::$Retrieved_Secret"
        echo "We retrieved our masked secret: $Retrieved_Secret"

Parar e iniciar os comandos no fluxo de trabalho

Para de processar quaisquer comandos de fluxo de trabalho. Esse comando especial permite fazer o registro do que você desejar sem executar um comando do fluxo de trabalho acidentalmente. Por exemplo, é possível parar o log para gerar um script inteiro que tenha comentários.

::stop-commands::{endtoken}

Para interromper o processamento de comandos do fluxo de trabalho, transmita um token único para stop-commands. Para retomar os comandos do fluxo de trabalho, passe o mesmo token que você usou para parar os comandos do fluxo de trabalho.

::{endtoken}::

Exemplo: interrupção e inicialização de comandos do fluxo de trabalho

jobs:
  workflow-command-job:
    runs-on: ubuntu-latest
    steps:
      - name: Disable workflow commands
        run: |
          echo '::warning:: This is a warning message, to demonstrate that commands are being processed.'
          stopMarker=$(uuidgen)
          echo "::stop-commands::$stopMarker"
          echo '::warning:: This will NOT be rendered as a warning, because stop-commands has been invoked.'
          echo "::$stopMarker::"
          echo '::warning:: This is a warning again, because stop-commands has been turned off.'

jobs:
  workflow-command-job:
    runs-on: windows-latest
    steps:
      - name: Disable workflow commands
        run: |
          Write-Output '::warning:: This is a warning message, to demonstrate that commands are being processed.'
          $stopMarker = New-Guid
          Write-Output "::stop-commands::$stopMarker"
          Write-Output '::warning:: This will NOT be rendered as a warning, because stop-commands has been invoked.'
          Write-Output "::$stopMarker::"
          Write-Output '::warning:: This is a warning again, because stop-commands has been turned off.'

Eco de saídas de comando

Habilita ou desabilita o eco de comandos de fluxo de trabalho. Por exemplo, se você usar o comando set-output em um fluxo de trabalho, ele definirá um parâmetro de saída, mas o log da execução de fluxo de trabalho não mostrará o comando em si. Se você habilitar o retorno de comando, o log mostrará o comando, como ::set-output name={name}::{value}.

::echo::on
::echo::off

O eco de comandos encontra-se desabilitado por padrão. No entanto, um comando de fluxo de trabalho será refletido se houver algum erro que processa o comando.

Os comandos add-mask, debug, warning e error não dão suporte ao retorno porque as saídas já foram retornadas ao log.

Você também pode habilitar o comando de retorno globalmente ativando o log de depuração da etapa usando o segredo ACTIONS_STEP_DEBUG. Para obter mais informações, confira "Habilitando o log de depuração". Por outro lado, o comando do fluxo de trabalho echo permite que você habilite o comando de retorno em um nível mais granular, em vez de habilitá-lo para cada fluxo de trabalho em um repositório.

Exemplo: alternância do comando de retorno

jobs:
  workflow-command-job:
    runs-on: ubuntu-latest
    steps:
      - name: toggle workflow command echoing
        run: |
          echo '::set-output name=action_echo::disabled'
          echo '::echo::on'
          echo '::set-output name=action_echo::enabled'
          echo '::echo::off'
          echo '::set-output name=action_echo::disabled'

jobs:
  workflow-command-job:
    runs-on: windows-latest
    steps:
      - name: toggle workflow command echoing
        run: |
          write-output "::set-output name=action_echo::disabled"
          write-output "::echo::on"
          write-output "::set-output name=action_echo::enabled"
          write-output "::echo::off"
          write-output "::set-output name=action_echo::disabled"

O exemplo acima imprime as seguintes linhas no log:

::set-output name=action_echo::enabled
::echo::off

Apenas os comandos do fluxo de trabalho set-output e echo são incluídos no log, porque o retorno de comando só estava habilitado quando eles foram executados. Mesmo que nem sempre ele esteja ecoado, o parâmetro de saída é definido em todos os casos.

Enviar valores para as ações anterior e posterior

Você pode usar o comando save-state para criar variáveis de ambiente a serem compartilhadas com as ações pre: ou post: do fluxo de trabalho. Por exemplo, você pode criar um arquivo com a ação pre:, transmitir a localização do arquivo para a ação main: e usar a ação post: para excluir o arquivo. Como alternativa, você pode criar um arquivo com a ação main:, transmitir a localização do arquivo para a ação post: e usar a ação post: para excluir o arquivo.

Se você tiver várias ações pre: ou post:, só poderá acessar o valor salvo na ação em que save-state ele foi usado. Para obter mais informações sobre a ação post:, confira "Sintaxe de metadados para o GitHub Actions".

O comando save-state só pode ser executado em uma ação e não está disponível para arquivos YAML. O valor salvo é armazenado como um valor de ambiente com o prefixo STATE_.

Este exemplo usa JavaScript para executar o comando save-state. A variável de ambiente resultante é chamada STATE_processID com o valor de 12345:

console.log('::save-state name=processID::12345')

Em seguida, a variável STATE_processID fica disponível exclusivamente para o script de limpeza em execução na ação main. Este exemplo é executado em main e usa o JavaScript para exibir o valor atribuído à variável de ambiente STATE_processID:

console.log("The running PID from the main action is: " +  process.env.STATE_processID);

Arquivos de ambiente

Durante a execução de um fluxo de trabalho, o executor gera arquivos temporários que podem ser usados para executar certas ações. O caminho para esses arquivos são expostos através de variáveis de ambiente. Você precisará usar a codificação UTF-8 ao escrever para esses arquivos para garantir o processamento adequado dos comandos. Vários comandos podem ser escritos no mesmo arquivo, separados por novas linhas.

A maioria dos comandos nos exemplos a seguir usa aspas duplas para ecoar cadeias de caracteres, que tentarão interpolar caracteres como $ para nomes de variáveis de shell. Para sempre usar valores literais em cadeias de caracteres entre aspas, você poderá usar aspas simples.

jobs:
  legacy-powershell-example:
    runs-on: windows-latest
    steps:
      - shell: powershell
        run: |
          "mypath" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append

jobs:
  powershell-core-example:
    runs-on: windows-latest
    steps:
      - shell: pwsh
        run: |
          "mypath" >> $env:GITHUB_PATH

Configurar uma variável de ambiente

echo "{environment_variable_name}={value}" >> "$GITHUB_ENV"

Disponibilize uma variável de ambiente para todas as etapas posteriores em um trabalho de fluxo de trabalho definindo ou atualizando a variável de ambiente e gravando isso no arquivo de ambiente GITHUB_ENV. A etapa que cria ou atualiza a variável de ambiente não tem acesso ao novo valor, mas todos os passos subsequentes em um trabalho terão acesso. Os nomes das variáveis de ambiente são diferenciam maiúsculas e minúsculas e você pode incluir a pontuação. Para obter mais informações, confira "Variáveis".

Exemplo de gravação de uma variável de ambiente em GITHUB_ENV

steps:
  - name: Set the value
    id: step_one
    run: |
      echo "action_state=yellow" >> "$GITHUB_ENV"
  - name: Use the value
    id: step_two
    run: |

      echo "${{ env.action_state }}" # This will output 'yellow'

steps:
  - name: Set the value
    id: step_one
    run: |
      "action_state=yellow" >> $env:GITHUB_ENV
  - name: Use the value
    id: step_two
    run: |

      Write-Output "${{ env.action_state }}" # This will output 'yellow'

Strings de linha múltipla

Para strings linha múltipla, você pode usar um delimitador com a seguinte sintaxe.

{name}<<{delimiter}
{value}
{delimiter}

Exemplo de uma cadeia de caracteres de várias linhas

Este exemplo seleciona um valor aleatório para $EOF como delimitador e define a variável de ambiente JSON_RESPONSE como o valor da resposta curl.

steps:
  - name: Set the value in bash
    id: step_one
    run: |
      EOF=$(dd if=/dev/urandom bs=15 count=1 status=none | base64)
      echo "JSON_RESPONSE<<$EOF" >> "$GITHUB_ENV"
      curl https://example.com >> "$GITHUB_ENV"
      echo "$EOF" >> "$GITHUB_ENV"

steps:
  - name: Set the value in pwsh
    id: step_one
    run: |
      -join (1..15 | ForEach {[char]((48..57)+(65..90)+(97..122) | Get-Random)}) | set EOF
      "JSON_RESPONSE<<$EOF" >> $env:GITHUB_ENV
      (Invoke-WebRequest -Uri "https://example.com").Content >> $env:GITHUB_ENV
      "$EOF" >> $env:GITHUB_ENV
    shell: pwsh

Adicionar um caminho do sistema

Insere um diretório antes da variável PATH do sistema e o disponibiliza automaticamente para todas as ações posteriores do trabalho atual. A ação atualmente em execução não pode acessar a variável de caminho atualizada. Para ver os caminhos atualmente definidos para seu trabalho, use echo "$PATH" em uma etapa ou uma ação.

echo "{path}" >> $GITHUB_PATH

"{path}" >> $env:GITHUB_PATH

Exemplo de adição de um caminho do sistema

echo "$HOME/.local/bin" >> $GITHUB_PATH

"$env:HOMEPATH/.local/bin" >> $env:GITHUB_PATH