Entendendo e criando GitHub Docker Container Action

[Guest geovanasouza]

Entendendo e criando GitHub Docker Container Action

 

 

 

 

Actions são tarefas individuais que podem ser combinadas para criar jobs (trabalhos) e personalizar workflows (fluxos de trabalho), ajudando a diminuir a quantidade repetitiva de código. Você pode utilizar as actions publicadas no GitHub Marketplace ou criar e customizar suas próprias actions.

 

 

 

O GitHub Actions permite criar 3 tipos de actions customizadas: Javascript, Composite e Docker Container. Nesse artigo, vamos entender sobre Docker Container Actions (DCA), como implementar sua primeira Docker action e testá-la em um GitHub workflow.

 

 

 

Docker container permite que você crie actions customizadas empacotando o ambiente com o código da action. Dessa forma, quem consumir sua action não precisa se preocupar com as dependências necessárias para executá-la, basta referenciar a action em seu workflow e executar, pois ela já conterá todos os componentes necessários para execução.

 

 

Quando usar Docker Container Action?

 

 

 

 

DCA é a opção ideal para actions que precisam ser executadas em ambientes com configurações específicas, já que permite personalizar o sistema operacional, as ferramentas, código e dependências sem necessitar adicionar ao runner (executor), basta apenas o runner possuir o Docker e é possível executar no mesmo runner diversas Docker actions e cada uma com sua personalização.

 

 

 

Você também pode utilizar DCA quando Javascript actions não for uma opção, seja por querer utilizar uma versão específica do Node, já que Javascript actions utilizam Node(16) ou até mesmo por familiaridade com outras linguagens, já que com Docker container é possível construir actions utilizando suas linguagens favoritas, seja Python, Go, Bash, Ruby e entre outras.

 

 

Criando Docker Container Actions

 

 

 

 

Agora vamos entender e executar os passos necessários para criar DCA, e teremos então uma Docker container action desenvolvida em Python que faz uma chamada a API do GitHub para listar branches de um repositório público.

 

 

Pré-requisitos

 

 

 

 

• 
  SO Linux e Docker: Para rodar DCA, os runners auto-hospedados precisam utilizar o sistema operacional Linux e ter o Docker instalado, mas você pode utilizar os runners hospedados no GitHub, que são gerenciados pelo GitHub e já possuem o Docker, como por exemplo ubuntu-latest.
   
   
  
• 
  Repositório: Antes de iniciar, é necessário criar um repositório GitHub.
   
  
  • 
    Crie um novo repositório GitHub: Vamos utilizar list-branches-docker-action como nome do repositório, mas você pode criar com o nome que preferir. Para informações de criação de repositórios, consulte: Criando um novo repositório.
     
     
    
  • 
    Clone o repositório: Após criar o repositório, clone em sua máquina. Saiba mais em: Clonando repositório.
     
     
    
  • 
    Mude o diretório: Em seu terminal, execute o comando a seguir para mudar o diretório para o novo repositório:
     
    cd list-branches-docker-action
    

 

Código da action

 

 

 

 

No diretório raiz list-branches-docker-action, vamos criar o arquivo main.py que conterá o código escrito em Python que a action irá executar:

 

 

 

# Código da action

import requests

import json

import sys

 

r=requests.get("https://api.github.com/repos/"+sys.argv[1]+"/"+sys.argv[2]+"/branches", headers={"Accept": "application/vnd.github+json" ,"X-GitHub-Api-Version":"2022-11-28"})

 

objeto = json.loads(r.text)

 

print("\nLista de branches do repositório "+sys.argv[2]+ " :")

for v in objeto:

print(v['name'])

 

Esse script faz uma chamada a API do GitHub https://api.github.com/repos/OWNER/REPO/branches, que recebe dois parâmetros: OWNER, representando o proprietário do repositório e REPO, que representa o nome do repositório do qual iremos listar as branches.

 

 

 

Para fazer essa chamada, inicialmente importamos os módulos necessários. Sendo requests, que possibilita realizarmos chamadas http, json para trabalharmos com os dados JSON e sys para manipularmos os parâmetros que são passados na execução do programa.

 

 

 

Onde fazemos a chamada da API, substituímos os argumentos OWNER e REPO por sys.argv[1] e sys.argv[2] correspondente, pois esses parâmetros serão atualizados com os valores passados como argumento para o contêiner.

 

 

 

Por fim, convertemos o json da resposta da API em um objeto Python Dictionary para conseguirmos percorrer esse objeto e trazer apenas o nome das branches.

 

 

Dockerfile

 

 

 

 

Com o código da action definido, seguindo a sintaxe e os padrões descritos em Suporte do arquivo Docker para GitHub Actions criamos o arquivo Dockerfile que será utilizado para criar a imagem que conterá o código da action.

 

 

 

#Imagem de contêiner que executa o código da action

FROM python:3.8-alpine

 

RUN pip install requests

 

COPY main.py /main.py

 

ENTRYPOINT ["python", "/main.py"]

 

Estamos utilizando python:3.8-alpine como base para nossa imagem, pois já inclui o Python. Com o comando RUN pip install requests Instalamos as bibliotecas necessárias para execução da action que são importadas no arquivo main.py, depois copiamos o arquivo que contém o código da action (main.py) para dentro do contêiner e ao final em ENTRYPOINT ["python", "/main.py"] adicionamos uma instrução para que o Docker execute o arquivo main.py assim que iniciar o contêiner. Dessa forma, estamos adicionando as dependências da action diretamente na imagem do contêiner juntamente com o código da action. Então, ao executar a imagem ela iniciará um contêiner com a action e suas dependências.

 

 

 

Note que estamos apenas instalando a biblioteca requests, pois json e sys são pacotes que já vêm integrado com o Python.

 

Arquivo de metadados da action

 

 

 

 

No diretório list-branches-docker-action, criamos um arquivo action.yml que contém toda a definição da action, como descrição, inputs (entradas) e outputs (saídas).

 

 

 

#action.yml

name: 'List Branches Docker Action'

description: 'Lista branches de um repositório público'

branding:

icon: 'git-branch'

color: 'blue'

inputs:

owner: # id do input

description: 'Sua organização ou usuário github'

required: true

repo: # id do input

description: 'Nome do repositório' # que possui as branches a serem listadas

required: true

runs:

using: 'docker'

image: 'Dockerfile'

args:

- ${{ inputs.owner }}

- ${{ inputs.repo }}

 

No action.yml acima, definimos o nome, descrição da action e o ícone e a cor que representará a action, caso deseje publicar no GitHub Marketplace.

 

 

Passar Inputs para o contêiner

 

 

 

 

Para passar os argumentos para o Docker container, precisamos declarar os inputs e então passá-los como argumento usando args. Em nosso arquivo, temos os inputs obrigatórios owner e repo, que são passados como argumentos inputs.owner e inputs.repo, pois serão utilizados para atualizar os parâmetros sys.args[1] e sys.argv[2] definidos em nosso arquivo main.py.

 

 

 

inputs:

owner: # id do input

description: 'sua organização ou usuário GitHub'

required: true

repo: # id do input

description: 'nome do repositório' # que possui as branches a serem listadas

required: true

 

runs:

args:

- ${{ inputs.owner }}

- ${{ inputs.repo }}

 

Definir a imagem da action

 

 

 

 

Precisamos especificar a imagem que será utilizada para iniciar o contêiner que contém o código da action. Na sessão run passamos a propriedade using como docker e podemos definir a imagem de 2 formas:

 

1. 
   Usando o arquivo Dockerfile presente no repositório da action:
    
   runs:
   using: 'docker'
   image: 'Dockerfile'
    
   Assim como em nosso action.yml, quando passamos Dockerfile em image, o GitHub runner construirá uma imagem a partir desse Dockerfile e iniciará um contêiner que executará o código definido em main.py.
    
    
   
2. 
   Usando uma imagem de um Docker registry:
    
   runs:
   using: 'docker'
   image: 'docker://geovana10/list-branches-docker-action:v1'
    
   Ao utilizar uma imagem de um Docker registry, o GitHub runner não precisa construí-la, basta realizar pull (recuperação) dessa imagem, buscando ela e executando-a para iniciar o contêiner contendo o código da action.
    
   

Devido a latência que o runner tem de construir e recuperar a imagem, as Docker actions costumam ser mais lentas que Javascript actions.

 

Adicionar tag e realizar push da action para o repositório do GitHub

 

 

 

 

Após a criação dos arquivos main.py, Dockerfile e action.yml, podemos fazer o commit (confirmação), realizar o push (envio) para nosso repositório do GitHub e adicionar uma tag , que será utilizada posteriormente para identificar a versão da nossa action. No diretório local list-branches-docker-action, execute:

 

 

 

git add .

git commit -m "my actions file"

git tag -a v1 -m "Primeira versão list branches tag"

git push --follow-tags

 

Testar Docker container action em um GitHub Workflow

 

 

 

 

Com a action disponível em nosso repositório, já podemos testá-la em um GitHub workflow. As actions públicas podem ser utilizadas em qualquer repositório, mas podemos ter actions em repositório privado onde podemos controlar o acesso e podemos publicá-las no GitHub Marketplace. Para mais informações, veja Publicar actions no GitHub Marketplace.

 

 

 

Para usarmos a action, precisamos ter um arquivo .yml no diretório .github/workflows, então nesse diretório criamos o arquivo main.yml, que é executado sempre que for realizado um push na branch main do repositório.

 

 

 

on:

push:

branches: [ main ]

 

jobs:

List-Branches:

runs-on: ubuntu-latest

name: Job para listar Branches de repositório GitHub

steps:

- name: Listar Branches action step

id: list

uses: geovanams/list-branches-docker-action@v1

with:

owner: 'geovanams'

repo: 'public-repo'

 

Esse workflow possui um único job chamado List-Branches que executará o step (etapa) List Branches action step. Nesse step em uses chamamos a action que criamos anteriormente.

 

 

 

Como a action está em um repositório público, estamos definindo a action usando a seguinte sintaxe: geovanams/list-branches-docker-action@v1, que você pode substituir com as suas informações, onde temos o nome do usuário GitHub ou organização, em seguida o nome do repositório e então @v1 representando a versão da action, que corresponde a tag que criamos anteriormente, mas podemos versionar usando commit ID ou até mesmo o nome da branch. Para mais informações sobre como gerenciar versão de actions com tags e releases, visite: Melhores práticas para gerenciamento de versões

 

 

 

Para passarmos os parâmetros da action, utilizamos o atributo with. Nesse workflow, passamos os parâmetros owner e repo que você pode substituir os valores pelo proprietário e nome do repositório do qual deseja listar as branches.

 

 

 

uses: geovanams/list-branches-docker-action@v1

with:

owner: 'geovanams'

repo: 'public-repo'

 

Após salvar o arquivo no repositório, o GitHub já iniciará o workflow. Na aba Actions, podemos visualizar os logs de execução do job e steps do workflow.

 

 

 

Lista de steps do workflow que foi executado

 

 

 

Note que temos 2 steps principais:

 

 

 

1- Build geovanams/list-branches-docker-action@v1: Como definimos Dockerfile em nosso arquivo action.yml, o GitHub adicionou esse step de build para construir a imagem a partir do arquivo Dockerfile presente no repositório.

 

 

 

Log do step de build construindo a imagem

 

 

 

Como dito anteriormente, se utilizarmos a imagem de um Docker registry, para recuperar a imagem o GitHub adicionaria o step de pull ao invés do de build. Exemplo:

 

 

 

Log do step de pull recuperando a imagem do Docker registry

 

 

 

2 - Listar Branches action: Esse é o step que de fato chamamos a Docker action, ele mostra os parâmetros passados para action e o resultado de sua execução, listando então todas as branches do repositório definido.

 

 

 

Log do step Listar Branches action trazendo os parâmetros e a lista de branches

 

 

README

 

 

 

 

Criar um README é uma ótima maneira de definir como as pessoas devem utilizar suas actions. No diretório raiz list-branches-docker-action criamos o arquivo README.md, que contêm as informações necessárias de como utilizar a action que criamos.

 

 

 

# List Branches Docker Action

Essa action lista as branches de um repositório público.

 

## Inputs

 

## `owner`

 

**Required** Sua organização ou usuário GitHub que possui o repositório do qual deseja listar.

 

## `repo`

 

**Required** nome do repositório que possui as branches a ser listadas.

 

## Example usage

 

uses: geovanams/list-branches-docker-action@v1

with:

owner: 'geovanams'

repo: 'public-repo'

 

Estrutura de arquivos do repositório

 

 

 

 

Ao concluir os passos anteriores, teremos então um repositório estruturado da seguinte forma:

 

 

 

.

├── .github/workflows

│ └── main.yml

├── Dockerfile

├── README.md

├── action.yml

└── main.py

 

Você pode baixar essa estrutura com o código completo da Docker action do repositório GitHub List-Branches-Docker-Action.

 

 

Conclusões

 

 

 

 

Docker Container Action é uma excelente escolha para a criação de actions personalizadas que requerem linguagens ou configurações específicas. Com ela, você pode criar actions da maneira que preferir e usando as linguagens que desejar. Neste artigo, explicamos o que são Docker container actions, quando devem ser usadas e como criá-las e testá-las em um GitHub workflow.

 

 

Referências

 

 

 

 

1. Sobre actions personalizadas | GitHub Docs
   
   
2. Criando Docker container action | GitHub Docs
   
   
3. Entendendo GitHub Actions | GitHub Docs
   
   

 

Continue reading...