Como manipular outputs no GitHub Actions

Neste artigo vamos nos aprofundar em como usar variáveis de outputs com workflows no Github Actions, explicando como criar e manipular outputs.

Vamos começar com o que são outputs. Em seguida, vamos ver como podem ser úteis dentro dos nossos workflows no Github Actions.

Mas o que são outputs?

Outputs são variáveis criadas e manipuladas em tempo de execução de um workflow. Esses parâmetros são determinados de acordo com o contexto do job onde são gerados.

Exemplo: Se você tiver uma ação ou um step  que realiza a adição de duas entradas (x + y = z), você pode criar uma variável do tipo output da soma (z) para outros steps ou job usarem ela como entrada.

Outputs são particularmente úteis quando queremos compartilhar resultados de uma ação com outras etapas de nosso fluxo.

Como criar outputs?

Para criar um output, é preciso seguir uma nomenclatura bem específica, usando a nomenclatura ::set-output

manipular outputs gha

Exemplo de step para configurar um output hardcoded:

- name: Set Sum
  id: abc
  run: echo "::set-output name=SUM::20"

Aqui, o valor do output SUM “20” é hardcoded, mas seria possível usar o resultado de uma ação anterior para configurar o output, por exemplo:

Exemplo de step para configurar um output dinâmico:

- name: Set IP Address
  id: xyz
  run: echo "::set-output name=ip-address::$(curl -s ifconfig.me)"

Aqui, o valor do output ip-address é determinado na hora da execução do comando curl -s ifconfig.me

Como manipular um output

Conforme comentamos, usamos outputs para compartilhar resultados de uma ação com outras etapas de nosso fluxo. Pode ser em um outro step de nosso job ou em outro job.

1 – Em um step do mesmo job

Caso precisar usar um output em um step posterior ao step onde foi configurado, no mesmo job, basta seguir a nomenclatura de busca do valor de um output:

run: echo "${{ steps.{id-step}.outputs.{output-name} }}"

Usando novamente o exemplo do parágrafo anterior, daria algo assim:

steps:
 - name: Set IP Address
    id: xyz
   run: echo "::set-output name=ip-address::$(curl -s ifconfig.me)"
- name: Get IP Address
   run: echo "${{ steps.xyz.outputs.ip-address }}"

2 – Em um outro job

Caso precisar usar um output em um outro job, a nomenclatura será semelhante, com a adição de mais duas configurações:

• Uma ao nível do job que cria o output.
• Uma ao nível do job que vai querer usar o output.

Para a primeira configuração, é preciso adicionar um campo outputs ao nível do job:

outputs:
output-name: ${{ steps.{id-step}.outputs.{output-name} }}

Exemplo de como configurar um output em um job para compartilhar no outro job

job1:

runs-on: ubuntu-latest
outputs:
ip: ${{ steps.xyz.outputs.ip-address }}
 steps:
- name: Set IP Address
  id: xyz
  run: echo "::set-output name=ip-address::$(curl -s ifconfig.me)"

Para a segunda configuração (no outro job) é preciso adicionar a relação de dependência com o primeiro job. A nomenclatura de busca do valor do output muda um pouco devido a isso.

Para a dependência entre os jobs, usar: 

needs: {job-id}

Para a nomenclatura de busca no segundo job, usar:

run: echo ${{ needs.{job-id}.outputs.{output-name} }}

Exemplo de como usar um output em um outro job

job2:

runs-on: ubuntu-latest
 needs: job1
 steps:
 - name: Get IP Address
   run: echo ${{ needs.job1.outputs.ip }} 

Segue o workflow completo para quem quiser experimentar:

Exemplo prático de como manipular outputs no Github Actions

Aqui vou mostrar um exemplo com algumas maneiras de usar o output em um workflow:

1. workflow inicial
   
2. Na aba Actions (conforme imagem abaixo)

3. O resultado: workflow run

Podemos observar que os 3 primeiros jobs são relacionados, o job 1 cria 2 outputs (hello e world) usados no job 2 (para mostrar “hello world“), e o job 3 aguarda a execução do job 1 e do job 2  para ser executado.

O job 4 é a execução do exemplo do artigo, com a criação do output de ip-address e seu uso em outros steps (de 2 formas, criando um json ou não).

Finalmente, o job 5 mostra como usar um output para decidir qual operação realizar. Neste caso, é gerado um número aleatoriamente, e se ele for maior do que um certo valor (neste caso, 1) ele executa um step, senão ele executa um outro step. Usando uma condição através de um if usando o valor do output.

PS: Até deixei um job 6 comentado no workflow inicial mostrando que é possível criar outputs através de actions. Neste caso, a associação do valor ao nome do output (o ::set-output) é feita dentro da actions, e é possível usar ele no nosso fluxo após a sua execução (como se tivesse feito em um step). Aqui, o exemplo retorna como output o valor da URL de um HTML após a geração de uma release.

Variáveis de outputs com workflows no Github Actions: mais facilidade para o seu dia a dia

Por hoje é isso! Espero que este artigo tenha deixado mais claro como usar outputs no Github Actions para usar com seus workflows nos seus repositórios do Github.

Quem quiser aprofundar no Github Actions para testar o que foi explicado aqui e muito mais, é só criar seu repositório com seus workflows e experimentar. Isso, pois o plano FREE da plataforma permite você testar seus fluxos de trabalhos em repositórios públicos sem limites de tempo.

Deixo aqui registrado um repositório pessoal, onde testei vários tipos de implementações e eventos diferentes com Github Actions, caso queira fazer um fork.

Lembrando que a documentação do Github Actions em português é muito boa e vale uma lida.

Referências

• Definir um parâmetro de saída – GitHub
• Outputs (saída) – GitHub
• Usar o set-output num fluxo de trabalho – GitHub