on
[PT-BR] Introdução ao Github Actions
Introdução ao Github Actions
Passo-a-passo de como usar a ferramenta
É tão bom ver tudo verdinho
Se você nao está familializado com DevOps e CI/CD, o GitHub Actions pode parecer um pouco confuso no início. Neste artigo vamos ver um tutorial passo-a-passo de como utilizar a ferramenta.
Do ponto de vista de CI/CD (Continuous Integration/Continuous Delivery) o objetivo principal do GitHub Actions e dos Workflows é testar o software sempre que houver alguma mudança, por mínima que seja. Assim é possível detectar bugs e corrigir as coisas no momento em que elas aparecerem.
Hoje vamos aprender mais sobre o GitHub Actions e ver como usar scripts em bash e Python junto com a ferramenta.
GitHub Actions vs. Workflows
Primeiramente é importante estabelecer a diferença entre GitHub Actions e Workflows. Como a documentação do GitHub Actions menciona, ações são tarefas individuais que você pode combinar para criar jobs e customizar seu workflow. Por outro lado, Workflows são “processos automáticos customizados” que você pode configurar no seu repositório para dar build, testar e criar packages em qualquer projeto no GitHub. Em outras palavras:
-
Workflows: processos automáticos que rodam no seu repositório; Um workflow pode ter várias GitHub Actions
-
GitHub Actions: tarefas individuais; elas podem ser escritas usando Docker, JavaScript e agora também usando shell scripts com o novo Composite Run Steps; você pode escrever suas próprias actions ou usar actions criadas por outras pessoas
Criando nosso primeiro Workflow
Primeiro vamos criar um wokflow sem actions para entender como eles funcionam. Workflows são definidos usando arquivos YAML e você deve salvá-los no diretório .github/workflows, na raiz do seu repositório;
Para criar um workflow precisamos definir essas coisas:
-
O evento que aciona (trigger) o workflow
-
A máquina que cada job deve rodar
-
Os jobs que compõem o workflow (jobs contém um conjunto de etapas (steps) que performam tarefas individuais e rodam em paralelo por default)
-
Os steps que cada job deve rodar
A sintaxe básica para um workflow é:
-
on — o evento que aciona o workflow
-
runs-on — a máquina (sistema operacional) que cada job deve rodar
-
jobs — os jobs que compõem o workflow
-
steps — as tarefas que cada job deve rodar
-
run — o comando que o step deve rodar
Primeiro precisamos definir o evento que aciona o workflow. Neste exemplo nós queremos imprimir saudações sempre que alguém der push no repositório.
Um run de um worklow é composto de um ou mais jobs. Cada job roda numa máquina especificada em runs-on. A máquina pode ser um runner hospedado pelo GitHub ou hospedado pelo usuário. Neste exemplo vamos usar o runner ubuntu-latest fornecido pelo GitHub.
Um job contém uma sequência de tarefas chamada steps. Cada step roda um comando, uma ação de configuração ou uma action. Cada step pode ter um comando run que usa o shell do sistema operacional da máquina. Vamos ver como dar echo (print) em uma mensagem.
Ok, agora vamos juntar tudo que vimos até aqui. Crie um arquivo first_workflow.yml dentro do seu repositório e code file inside .github/workflows on your repo, then paste this code:
# seu-repositorio/.github/workflows/first_workflow.yml
name: First Workflow
on: push
jobs:
first-job:
name: Say hi
runs-on: ubuntu-latest
steps:
- name: Print a greeting
run: echo Hi from our first workflow!
Agora se você der commit adicionando esse arquivo ao repositório, der push e for na aba Actions no site do GitHub você pode ver o workflow e as saídas:
As saídas do primeiro workflow
Usando uma Action no nosso workflow
Actions são tarefas individuais e podemos usá-las a partir de 3 fontes:
-
Actions definidas no mesmo respositório do workflow
-
Actions definidas em um repositório público
-
Actions definidas em um container Docker
Elas rodam como um step no nosso workflow. Para chamá-las usamos a sitaxe use. Neste exemplo vamos usar uma Action que imprime arte em ASCII, escrita por Mike Coutermarsh. Como ela está definida em um repositório público nós só precisamos passar o nome do repositório:
# seu-repositorio/.github/workflows/first_workflow.yml
name: First Workflow
on: push
jobs:
first-job:
name: Say hi
runs-on: ubuntu-latest
steps:
- name: Print a greeting
run: echo Hi from our first workflow!
- name: Show ASCII greeting
uses: mscoutermarsh/ascii-art-action@master
with:
text: 'HELLO!'
A sintaxe with é um mapeamento entre parametros de entrada definidos pela action. O resultado:
O resultado da action ASCII
Usando Python nos Workflows
Como cientistas de dados nós usamos bastante Python no nosso dia-a-dia, então é uma boa aprender como usar Python nos workflows. Definir uma versão específica do Python ou PyPy é a maneira recomendada de usar Python com GitHub Actions porque assim a gente garante um comportamento consistente entre os diferentes runners e diferentes versões do Python.
Depois de definir a versão do Python nós podemos rodar os comandos como fazemos em um computador comum. Neste exemplo vamos instalar o Scrapy e rodar um script para pegar todos os posts do TDS sobre GitHub Actions. Como queremos rodar um script salvo no nosso próprio repositório precisamos da action checkout para poder acessá-lo. Vamos criar o job e rodar o script:
# seu-repositorio/.github/workflows/first_workflow.yml
name: First Workflow
on: push
jobs:
first-job:
name: Say hi
runs-on: ubuntu-latest
steps:
- name: Print a greeting
run: echo Hi from our first workflow!
- name: Show ASCII greeting
uses: mscoutermarsh/ascii-art-action@master
with:
text: 'HELLO!'
get-posts-job:
name: Get TDS posts
runs-on: ubuntu-latest
steps:
- name: Check-out the repo under $GITHUB_WORKSPACE
uses: actions/checkout@v2
- name: Set up Python 3.8
uses: actions/setup-python@v2
with:
python-version: '3.8'
- name: Install Scrapy
run: pip install scrapy
- name: Get TDS posts about GitHub Actions
run: scrapy runspider posts_spider.py -o posts.json
Queremos salvar os posts em um arquivo, então vamos aprender como fazer isso.
Persistindo os dados gerados durante um Workflow
Um artefato (artifact) é um arquivo ou uma coleção de arquivos produzidos durante a execução de um worklfow. Podemos passar esse artefato para outro job no mesmo workflow ou fazer download do arquivo usando a UI do GitHub.
Vamos baixar o JSON com os posts para ver como isso funciona. Para trabalhar com artifacts precisamos das actions upload-artifact e download-artifact. Para fazer upload de um artefato precisamos especificar o caminho para o arquivo ou diretório e o nome do artefato.
# seu-repositorio/.github/workflows/first_workflow.yml
# [...]
get-posts-job:
name: Get TDS posts
runs-on: ubuntu-latest
steps:
- name: Check-out the repo under $GITHUB_WORKSPACE
uses: actions/checkout@v2
- name: Set up Python 3.8
uses: actions/setup-python@v2
with:
python-version: '3.8'
- name: Install Scrapy
run: pip install scrapy
- name: Get TDS posts about GitHub Actions
run: scrapy runspider posts_spider.py -o posts.json
- name: Upload artifact
uses: actions/upload-artifact@v2
with:
name: posts
path: posts.json
E agora podemos baixar o arquivo usando a UI do GitHub:
Baixando o artefato
Criando sua primeira Action
Actions podem ser criadas usando containers do Docker, JavaScript ou usando shell scripts (uma action composite run steps). O principal caso de uso para actions composite run steps é quando você tem muitos shell scripts para automatizar alçoes e escrever um script para combiná-los é mais fácil do que usar JavaScript ou Docker.
Os três componentes principais de uma action são runs, inputs e outputs.
-
runs — (obrigatório) Configura o caminho para o código da action e a aplicação utilizada para executar o código
- inputs — (opcional) Parâmetros de entrada permitem que você especifique dados que a action esperar usar na execução
- outputs — (opcional) Parâmetros de saída permitem que você declare dados que uma action definie
O nome do arquivo de uma action pode ser tanto action.yml ou action.yaml. Vamos usar o exemplo da documentação do GitHub e criar uma action que imprime a mensagem “Hey [user]”. Como é uma action composite vamos usar a sintaxe using: "composite":
# action.yml
name: 'Hey From a GitHub Action'
description: 'Greet someone'
inputs:
user: # id of input
description: 'Who to greet'
required: true
default: 'You'
runs:
using: "composite"
steps:
- run: echo Hey $.
shell: bash
Se uma action é definida no mesmo repositório que o workflow podemos nos referir a ela usando ./caminho-para-o-arquivo-da-action. Neste caso precisamos acessar o arquivo dentro do repositório, então também usamos a action checkout.
Se a action for definida em um repositório público podemos nos referir a ela usando um commit específico, uma versão de um release ou um branch.
Rodando uma Action salva no mesmo repositório
# .github/workflows/use-action-same-repo.yml
name: Action from the same repo
on: push
jobs:
use-your-own-action:
name: Say Hi using your own action
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: ./ **# the action.yml file is in the root folder
with:
user: 'Déborah'
Rodando uma Action salva em um repositório público
# .github/workflows/use-action-public-repo.yml
name: Action from a public repository
on: push
jobs:
use-your-own-action:
name: Say Hi using your own action
runs-on: ubuntu-latest
steps:
- uses: dmesquita/github-actions-tutorial@master
with:
user: 'Déborah'
E chegamos ao fim do nosso passo-a-passo. Você também pode usar variáveis e secrets no workflow, fazer cache de dependência para diminuir o tempo necessário para eles rodarem e conectar bancos de dados e containers para gerenciar as ferramentas do workflow.
Neste tutorial não fazemos uso de uma das coisas mais legais do CI que é rodar testes sempre para detectar bugs no processo. Mas eu acho que é importante entender primeiro como as actions e os wokflows funcionam antes de fazer uso disso. Espero que agora seja mais fácil para você começar a usar as GitHub Actions e outras ferramentas de CI.
Você pode ver todo o código usado neste artigo aqui: https://github.com/dmesquita/github-actions-tutorial
Obrigada pela leitura!