Frequentemente, eu preciso construir um pipeline para compilar projetos em Java. Às vezes, é open source, outras não. Recentemente, decidi tentar transferir parte dos meus repositórios do Travis-CI e TeamCity para o GitHub Actions, e aqui está o que eu obtive.
O que vamos automatizar
Para começar, precisamos de um projeto que vamos automatizar, vamos criar um pequeno aplicativo em Spring Boot / Java 11 / Maven. No âmbito deste artigo, a lógica do aplicativo não nos interessa muito, o que importa é a infraestrutura ao redor do aplicativo, então um simples controlador REST API é o suficiente.
Você pode ver os códigos-fonte aqui: todos os estágios de construção do pipeline estão refletidos nos pull requests deste projeto.
JIRA e planejamento
Vale a pena mencionar que normalmente usamos o JIRA como rastreador de tarefas, então vamos criar um quadro separado para este projeto e adicionar lá as primeiras tarefas:
Mais tarde, voltaremos ao que pode ser interessante na combinação JIRA e GitHub.
Automatizando a construção do projeto
Nosso projeto de teste é construído através do Maven, então a construção é bastante simples, tudo o que precisamos é mvn clean package.
Para fazer isso usando o GitHub Actions, precisamos criar um arquivo no repositório com a descrição do nosso workflow, isso pode ser feito com um arquivo .yml, não posso dizer que gosto de "programação em yml", mas o que podemos fazer - vamos criar um arquivo build.yml na diretório .github/workflow/ onde descreveremos as ações para a construção do branch master:
name: Build
on:
pull_request:
branches:
- '*'
push:
branches:
- 'master'
jobs:
build:
runs-on: ubuntu-18.04
steps:
- uses: actions/checkout@v1
- name: set up JDK 11
uses: actions/setup-java@v1
with:
java-version: 1.11
- name: Maven Package
run: mvn -B clean package -DskipTests
ativado — esta é a descrição do evento que acionará nosso script.
on: pull_request / push — indica que este workflow deve ser acionado a cada push para o master e a criação de pull requests.
Em seguida, vem a descrição das tarefas (jobs) e os passos de execução (steps) para cada tarefa.
runs-on — aqui podemos escolher o sistema operacional alvo, surpreendentemente, podemos até escolher o Mac OS, mas em repositórios privados isso é uma opção bastante cara (em comparação com o linux).
uses permite reutilizar outras ações, por exemplo, usando a ação actions/setup-java instalamos o ambiente para Java 11.
Com o with Podemos especificar os parâmetros com os quais iniciamos a ação, na verdade, são argumentos que serão passados para a ação.
Agora, só falta iniciar a construção do projeto com o Maven: run: mvn -B clean package --all -B indica que precisamos do modo não interativo, para que o Maven não decida nos fazer perguntas.
Ótimo! Agora, a cada commit na branch master, a construção do projeto será iniciada.
Vamos automatizar a execução dos testes
Construir é bom, mas na realidade, um projeto pode ser construído com sucesso e ainda assim não funcionar. Portanto, o próximo passo é automatizar a execução dos testes. Além disso, é bastante prático ver os resultados dos testes durante a revisão do PR — você sabe exatamente que os testes passaram e que ninguém esqueceu de executar sua branch antes de fazer o merge.
Vamos executar os testes ao criar um pull request e ao fazer merge na master, e também adicionar a geração de um relatório de cobertura de código.
name: Build
on:
pull_request:
branches:
- '*'
push:
branches:
- 'master'
jobs:
build:
runs-on: ubuntu-18.04
steps:
- uses: actions/checkout@v1
- name: set up JDK 11
uses: actions/setup-java@v1
with:
java-version: 1.11
- name: Maven Verify
run: mvn -B clean verify
- name: Test Coverage
uses: codecov/codecov-action@v1
with:
token: ${{ secrets.CODECOV_TOKEN }}
Para a cobertura dos testes, eu uso o codecov em conjunto com o plugin jacoco. O codecov tem sua própria ação, mas para trabalhar com nosso pull request, ele precisa de um token:
${{ secrets.CODECOV_TOKEN }} — essa construção ainda aparecerá algumas vezes, 'secrets' é um mecanismo de armazenamento de segredos no GitHub, podemos lá armazenar senhas/tokens/hospedagens/URLs e outros dados que não devemos expor no código do repositório.
Adicionar uma variável nos secrets pode ser feito nas configurações do repositório no GitHub:
Você pode obter o token em depois de se autenticar pelo GitHub, para adicionar um projeto público você só precisa visitar um link como: /[repo name]. Приватный репозиторий тоже можно добавить, для этого надо дать права codecov приложению в гитхабе.
Adicionamos o plugin jacoco no arquivo POM:
org.jacoco
jacoco-maven-plugin
0.8.4
prepare-agent
report
test
report
org.apache.maven.plugins
maven-surefire-plugin
2.22.2
plain
**/*Test*.java
**/*IT*.java
Agora, todos os nossos pull requests terão o bot do codecov que irá adicionar um gráfico de cobertura de alterações:
Vamos adicionar um analisador estático
Na maioria de meus projetos de código aberto, utilizo o sonar cloud para análise estática de código, e é bastante fácil conectá-lo ao travis-ci. Portanto, isso é um passo lógico na migração para o GitHub Actions, fazer o mesmo. O Marketplace de ações é uma excelente ferramenta, mas desta vez ele me decepcionou um pouco, porque, por hábito, encontrei a ação necessária e a escrevi no workflow. Mas, na verdade, o sonar não suporta a execução através de uma ação para projetos maven ou gradle. Está claro na documentação, mas quem a lê?!
Não é possível através da ação, então faremos isso através do plugin mvn:
name: SonarCloud
on:
push:
branches:
- master
pull_request:
types: [opened, synchronize, reopened]
jobs:
sonarcloud:
runs-on: ubuntu-16.04
steps:
- uses: actions/checkout@v1
- name: Set up JDK
uses: actions/setup-java@v1
with:
java-version: 1.11
- name: Analyze with SonarCloud
# set environment variables:
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
# run sonar maven plugin:
run: mvn -B verify sonar:sonar -Dsonar.projectKey=antkorwin_github-actions -Dsonar.organization=antkorwin-github -Dsonar.host.url=https://sonarcloud.io -Dsonar.login=$SONAR_TOKEN -Dsonar.coverage.jacoco.xmlReportPaths=./target/site/jacoco/jacoco.xml
SONAR_TOKEN — pode ser obtido em e deve ser adicionado aos secrets. GITHUB_TOKEN — é um token incorporado que o GitHub gera, com ele o sonarcloud[bot] poderá se autenticar no git para nos deixar mensagens nos pull requests.
Dsonar.projectKey — o nome do projeto no sonar, que pode ser visto nas configurações do projeto.
Dsonar.organization — o nome da organização do GitHub.
Fazemos um pull request e esperamos o sonarcloud[bot] aparecer nos comentários:
Gerenciamento de lançamento
O build foi configurado, os testes foram executados, então vamos fazer o lançamento. Vamos ver como o GitHub Actions pode ajudar a simplificar bastante o gerenciamento de lançamentos.
No trabalho, tenho projetos cuja base de código está no bitbucket (tudo como naquela história de "escrevo no bitbucket durante o dia, comito no GitHub à noite"). Infelizmente, no bitbucket não há ferramentas integradas para gerenciar lançamentos. Isso é um problema, pois para cada lançamento é necessário criar manualmente uma página no confluence e adicionar todas as funcionalidades que foram incluídas no lançamento, e revisar os trabalhos na mente, as tarefas no jira, os commits no repositório. Há muitas chances de erro, é possível esquecer algo ou incluir o que já foi lançado da última vez, às vezes não está claro como classificar um pull request — se é uma nova funcionalidade ou correção de bugs, ou alteração de testes, ou algo de infraestrutura.
Como o GitHub Actions pode nos ajudar? Há uma excelente ação — release drafter, que permite definir um modelo de arquivo de notas de lançamento, para categorizar os pull requests e agrupá-los automaticamente no arquivo de notas de lançamento:
Exemplo de modelo para configurar o relatório (.github/release-drafter.yml):
name-template: 'v$NEXT_PATCH_VERSION'
tag-template: 'v$NEXT_PATCH_VERSION'
categories:
- title: ' Novas Funcionalidades'
labels:
- 'type:features'
# nesta categoria, agrupamos todos os PRs com o rótulo type:features
- title: ' Correções de Bugs'
labels:
- 'type:fix'
# similar para o rótulo type:fix, e assim por diante.
- title: ' Documentação'
labels:
- 'type:documentation'
- title: ' Configuração'
labels:
- 'type:config'
change-template: '- $TITLE @$AUTHOR (#$NUMBER)'
template: |
## Mudanças
$CHANGES
Adicionando o script para gerar o rascunho do lançamento (.github/workflows/release-draft.yml):
name: "Criar rascunho de lançamento"
on:
push:
branches:
- master
jobs:
update_draft_release:
runs-on: ubuntu-18.04
steps:
- uses: release-drafter/release-drafter@v5
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Todos os pull requests a partir deste momento serão coletados nas notas de lançamento automaticamente — magia!
Aqui pode surgir a pergunta: e se os desenvolvedores esquecerem de adicionar rótulos no PR? Então não ficará claro a qual categoria ele pertence, e será necessário resolver isso manualmente, com cada PR separadamente. Para corrigir esse problema, podemos usar outra ação — label verifier — que verifica a presença de tags no pull request. Se não houver nenhuma tag obrigatória, a verificação falhará e veremos uma mensagem a respeito no nosso pull request.
name: "Verificar rótulos de tipo"
on:
pull_request:
types: [opened, labeled, unlabeled, synchronize]
jobs:
triage:
runs-on: ubuntu-18.04
steps:
- uses: zwaldowski/match-label-action@v2
with:
allowed: 'type:fix, type:features, type:documentation, type:tests, type:config'
Agora, qualquer pull request precisa ser marcado com uma das tags: type:fix, type:features, type:documentation, type:tests, type:config.
Auto-anotação de pull requests
Uma vez que abordamos o tema do trabalho eficaz com pull requests, é importante mencionar outra ação, chamada labeler, que atribui rótulos ao PR com base nos arquivos que foram alterados. Por exemplo, podemos rotular como [build] qualquer pull request que contenha alterações no diretório .github/workflow.
A sua integração é bastante simples:
name: "Atribuição automática de temas a PR"
on:
- pull_request
jobs:
triage:
runs-on: ubuntu-18.04
steps:
- uses: actions/labeler@v2
with:
repo-token: ${{ secrets.GITHUB_TOKEN }}
Também precisaremos de um arquivo descrevendo a correspondência de diretórios do projeto com os temas dos pull requests:
theme:build:
- ".github/**"
- "pom.xml"
- ".travis.yml"
- ".gitignore"
- "Dockerfile"
theme:code:
- "src/main/*"
theme:tests:
- "src/test/*"
theme:documentation:
- "docs/**"
theme:TRASH:
- ".idea/**"
- "target/**"
Conectar a ação que automaticamente atribui rótulos aos pull requests com a ação que verifica a presença de rótulos obrigatórios não funcionou para mim, o match-label simplesmente não reconhece os rótulos atribuídos pelo bot. Parece mais fácil escrever minha própria ação, combinando ambas as etapas. Mas mesmo assim, é bastante conveniente utilizar, é necessário escolher um rótulo da lista ao criar um pull request.
É hora de fazer o deploy
Eu tentei várias opções de deploy através do GitHub Actions (via ssh, via scp, e utilizando docker-hub), e posso dizer que, provavelmente, você encontrará uma maneira de enviar o binário para o servidor, independentemente de quão complexo seja seu pipeline.
Gostei da opção de manter toda a infraestrutura em um lugar, então vamos ver como fazer o deploy no GitHub Packages (que é um repositório para conteúdo binário, npm, jar, docker).
Script para construir a imagem docker e publicá-la no GitHub Packages:
nome: Implantar imagem docker
em:
push:
branches:
- 'master'
trabalhos:
construir_imagem_docker:
runs-on: ubuntu-18.04
etapas:
# Construir JAR:
- uses: actions/checkout@v1
- name: configurar JDK 11
uses: actions/setup-java@v1
with:
java-version: 1.11
- name: Pacote Maven
run: mvn -B clean compile package -DskipTests
# Definir variáveis de ambiente globais:
- name: definir env global
id: global_env
run: |
echo "::set-output name=IMAGE_NAME::${GITHUB_REPOSITORY#*/}"
echo "::set-output name=DOCKERHUB_IMAGE_NAME::docker.pkg.github.com/${GITHUB_REPOSITORY}/${GITHUB_REPOSITORY#*/}"
# Construir imagem Docker:
- name: Construir e marcar imagem
run: |
docker build -t "${{ steps.global_env.outputs.DOCKERHUB_IMAGE_NAME }}:latest" -t "${{ steps.global_env.outputs.DOCKERHUB_IMAGE_NAME }}:${GITHUB_SHA::8}" .
- name: Login no Docker
run: docker login docker.pkg.github.com -u $GITHUB_ACTOR -p ${{secrets.GITHUB_TOKEN}}
# Publicar imagem no repositório de pacotes do github:
- name: Publicar imagem
env:
IMAGE_NAME: $GITHUB_REPOSITORY
run: docker push "docker.pkg.github.com/$GITHUB_REPOSITORY/${{ steps.global_env.outputs.IMAGE_NAME }}"
Para começar, precisamos compilar o arquivo JAR do nosso aplicativo e, em seguida, calculamos o caminho para o registro docker do GitHub e o nome da nossa imagem. Existem algumas sutilezas aqui com as quais ainda não nos deparamos:
- A construção na forma: echo «::set-output name=NAME::VALUE» permite definir o valor de uma variável na etapa atual, de modo que possa ser lido nas outras etapas.
- Para obter o valor da variável definida na etapa anterior, utilizamos o identificador dessa etapa: ${{ steps.global_env.outputs.DOCKERHUB_IMAGE_NAME }}
- Na variável padrão GITHUB_REPOSITORY é armazenado o nome do repositório e seu proprietário («owner/repo-name»). Para extrair dessa string tudo, exceto o nome do repositório, utilizaremos a sintaxe bash: ${GITHUB_REPOSITORY#*/}
Em seguida, precisamos construir a imagem docker:
docker build -t "docker.pkg.github.com/antkorwin/github-actions/github-actions:latest"
Fazer login no registro:
docker login docker.pkg.github.com -u $GITHUB_ACTOR -p ${{secrets.GITHUB_TOKEN}}
E publicar a imagem no GitHub Packages Repository:
docker push "docker.pkg.github.com/antkorwin/github-actions/github-actions"
Para especificar a versão da imagem, usamos os primeiros dígitos do SHA do commit — GITHUB_SHA tem suas peculiaridades, pois, se você fizer essas compilações não apenas ao mesclar no master, mas também ao criar um pull request, o SHA pode não coincidir com o hash que vemos no histórico do git, porque a ação actions/checkout gera seu hash único para evitar bloqueios mútuos de ações em um PR.
Se tudo correr bem, ao abrir a seção de pacotes (https://github.com/antkorwin/github-actions/packages) no repositório, você verá uma nova imagem docker:
Lá você pode ver a lista de versões da imagem do Docker.
Resta apenas configurar nosso servidor para trabalhar com esse registry e reiniciar o serviço. Sobre como fazer isso através do systemd, talvez eu comente em outra ocasião.
Monitoramento
Vamos ver uma forma simples de fazer o health check da nossa aplicação usando GitHub Actions. Em nossa aplicação de boot, já existe um actuator, então não precisamos nem escrever uma API para verificar seu estado, para os preguiçosos, já está tudo feito. Precisamos apenas acessar o host: SERVER-URL:PORT/actuator/health
$ curl -v 127.0.0.1:8080/actuator/health
> GET /actuator/health HTTP/1.1
> Host: 127.0.0.1:8080
> User-Agent: curl/7.61.1
> Accept: */*
< HTTP/1.1 200
< Content-Type: application/vnd.spring-boot.actuator.v3+json
< Transfer-Encoding: chunked
< Date: Thu, 04 Jun 2020 12:33:37 GMT
{"status":"UP"}
Tudo que precisamos é escrever uma tarefa de verificação do servidor no cron, e se por acaso ele não responder, enviaremos uma notificação no telegram.
Para começar, vamos entender como executar o workflow no cron:
on:
schedule:
- cron: '* /5 * * * *'
Tudo é simples, nem dá para acreditar que no GitHub é possível criar esses eventos que não se encaixam nos webhooks. Os detalhes estão na documentação:
Faremos a verificação do status do servidor manualmente através do curl:
jobs:
ping:
runs-on: ubuntu-18.04
steps:
- name: curl actuator
id: ping
run: |
echo "::set-output name=status::$(curl ${{secrets.SERVER_HOST}}/api/actuator/health)"
- name: health check
run: |
if [[ ${{ steps.ping.outputs.status }} != *"UP"* ]]; then
echo "health check falhou"
exit 1
fi
echo "Está OK"
Primeiro, salvamos em uma variável o que o servidor respondeu à solicitação, no próximo passo verificamos se o status é UP e, se não for, saímos com um erro. Se necessário "derrubar" a ação manualmente, então exit 1 — é a arma adequada.
- name: send alert in telegram
if: ${{ failure() }}
uses: appleboy/telegram-action@master
with:
to: ${{ secrets.TELEGRAM_TO }}
token: ${{ secrets.TELEGRAM_TOKEN }}
message: |
Health check of the:
${{secrets.SERVER_HOST}}/api/actuator/health
failed with the result:
${{ steps.ping.outputs.status }}
A mensagem para o Telegram será enviada apenas se a ação falhar na etapa anterior. Para enviar a mensagem, usamos appleboy/telegram-action; sobre como obter o token do bot e o ID do chat, você pode ler na documentação:
Não se esqueça de configurar nos segredos do GitHub: a URL do servidor e os tokens para o bot do Telegram.
Bônus track — JIRA para os preguiçosos
Eu prometi que voltaríamos ao JIRA, e aqui estamos. Já vi centenas de vezes em reuniões rápidas situações em que os desenvolvedores criaram uma funcionalidade, mesclaram a branch, mas esqueceram de mover a tarefa no JIRA. Claro, se tudo fosse feito em um só lugar, seria mais fácil, mas na prática escrevemos o código no IDE, mesclamos branches no Bitbucket ou GitHub, e depois movemos as tarefas para o JIRA, para isso precisamos abrir novas janelas, às vezes fazer login novamente etc. Quando você se lembra perfeitamente do que deve fazer a seguir, abrir o quadro mais uma vez não faz sentido. No fim das contas, de manhã, na reunião rápida, precisamos gastar tempo atualizando o quadro de tarefas.
O GitHub nos ajudará também nesta tarefa rotineira; para começar, podemos arrastar tarefas automaticamente para a coluna de revisão de código quando enviamos um pull request. Tudo que precisamos fazer é seguir a convenção no nome das branches:
[nome do projeto]-[número da tarefa]-título
por exemplo, se a chave do projeto ‘GitHub Actions’ for GA, então GA-8-jira-bot pode ser a branch para implementar a tarefa GA-8.
A integração com o JIRA funciona através de ações da Atlassian; não são perfeitas, devo dizer que algumas delas não funcionaram para mim. Mas discutiremos apenas aquelas que funcionam e são ativamente utilizadas.
Primeiro, precisamos passar pela autenticação no JIRA usando a ação: atlassian/gajira-login
jobs:
build:
runs-on: ubuntu-latest
name: Jira Workflow
steps:
- name: Login
uses: atlassian/gajira-login@master
env:
JIRA_BASE_URL: ${{ secrets.JIRA_BASE_URL }}
JIRA_USER_EMAIL: ${{ secrets.JIRA_USER_EMAIL }}
JIRA_API_TOKEN: ${{ secrets.JIRA_API_TOKEN }}
Para isso, você precisa obter um token no JIRA; como fazer isso está descrito aqui:
Extraímos o identificador da tarefa do nome da branch:
- name: Find Issue
id: find_issue
shell: bash
run: |
echo "::set-output name=ISSUE_ID::$(echo ${GITHUB_HEAD_REF} | egrep -o 'GA-[0-9]{1,4}')"
echo nome da branch: $GITHUB_HEAD_REF
echo tarefa extraída: ${GITHUB_HEAD_REF} | egrep -o 'GA-[0-9]{1,4}'
- name: Check Issue
shell: bash
run: |
if [[ "${{steps.find_issue.outputs.ISSUE_ID}}" == "" ]]; then
echo "Por favor, nomeie sua branch de acordo com a tarefa do JIRA: [project_key]-[task_number]-branch_name"
exit 1
fi
echo tarefa do JIRA encontrada com sucesso: ${{steps.find_issue.outputs.ISSUE_ID}}
Se você procurar no GitHub marketplace, pode encontrar uma ação para essa tarefa, mas eu tive que escrever a mesma coisa usando grep pelo nome da branch, pois essa ação da Atlassian não quis funcionar no meu projeto; descobrir o que estava errado levou mais tempo do que fazer manualmente.
Agora, só falta mover a tarefa para a coluna "Code review" ao criar o pull request:
- name: Transitar tarefa
if: ${{ success() }}
uses: atlassian/gajira-transition@master
with:
issue: ${{ steps.find_issue.outputs.ISSUE_ID }}
transition: "Code review"
Para isso, há uma ação especial no GitHub, tudo o que ela precisa é o identificador da tarefa obtido na etapa anterior e autorização no JIRA, que fizemos anteriormente.
Da mesma forma, é possível arrastar tarefas durante o merge no master e em outros eventos do fluxo de trabalho do GitHub. No geral, tudo depende da sua imaginação e do desejo de automatizar processos rotineiros.
Como resultado, obtemos um serviço de "monitoramento como serviço", automatizado na linha de produção de integração contínua. O desenvolvedor ou testador precisa apenas definir a lista de métricas em um arquivo JSON, e tudo o mais acontece automaticamente. Obtemos um controle de qualidade transparente dos lançamentos: todas as notificações sobre desempenho, consumo de recursos ou regressões arquitetônicas.
Se olharmos para o diagrama clássico de DEVOPS, cobrimos todas as etapas, exceto a de operação; acho que, se nos esforçarmos, podemos encontrar alguma ação no mercado para integração com um sistema de help-desk, então podemos considerar que o pipeline ficou robusto e, com base em seu uso, podemos tirar conclusões.
Acesso direto aos sistemas de cabos transpacíficos. Ping mínimo para a China, Japão, Austrália e costa oeste dos EUA.
- O Marketplace com ações prontas para todas as situações é muito legal. Na maioria delas, ainda é possível visualizar o código-fonte para entender como resolver uma tarefa semelhante ou postar uma solicitação de recurso diretamente ao autor no repositório do GitHub.
- A escolha da plataforma de destino para montagem: Linux, macOS, Windows é uma funcionalidade bastante interessante.
- O GitHub Packages é uma ótima ferramenta, manter toda a infraestrutura em um só lugar é conveniente, não é necessário navegar por várias janelas, tudo a um ou dois cliques do mouse e perfeitamente integrado com as GitHub Actions. O suporte ao docker registry na versão gratuita também é uma boa vantagem.
- O GitHub oculta segredos nos logs de montagem, por isso usar para armazenar senhas e tokens não é tão assustador. Durante todos os meus experimentos, nunca consegui ver um segredo em texto claro no console.
- Gratuito para projetos de código aberto
Pontos negativos:
- YML, eu simplesmente não gosto dele. Quando trabalho com esse fluxo, minha mensagem de commit mais frequente é "corrigir formato yml", pois às vezes esqueço de colocar um tab, ou escrevo na linha errada. No geral, ficar em frente à tela com um transportador e uma régua não é a atividade mais agradável.
- DEBUG, depurar o fluxo com commits, reexecução de montagem e saída no console nem sempre é conveniente, mas isso é mais da categoria "vocês estão exigentes", acostumados a trabalhar com IDEs confortáveis, onde é possível depurar tudo.
- Você pode escrever sua ação em qualquer linguagem se a empacotar em um contêiner Docker, mas apenas o JavaScript é suportado nativamente; claro, isso é uma questão de gosto, mas eu preferiria algo diferente ao invés de js.
Lembro que o repositório com todos os scripts está aqui:
Na próxima semana, farei uma apresentação na conferência Heisenbug 2020 Piter. Vou falar não apenas sobre como evitar erros ao preparar dados de teste, mas também compartilharei meus segredos para trabalhar com conjuntos de dados em aplicativos Java!
Fonte: habr.com
