Jeg bygger ofte pipeline til opbygning af projekter i Java. Nogle gange er det open source, andre gange ikke. For nylig besluttede jeg mig for at prøve at flytte nogle af mine repositories fra Travis-CI og TeamCity til GitHub Actions, og her er hvad jeg fik ud af det.
Hvad skal vi automatisere
For at starte har vi brug for et projekt, som vi skal automatisere. Lad os lave en lille ansøgning med Spring Boot / Java 11 / Maven. I denne artikel vil vi overhovedet ikke være interesserede i applikationens logik. Vi fokuserer på infrastrukturen omkring applikationen, så en simpel REST API-controller vil være tilstrækkelig.
Du kan se kildekoden her: alle trin i opbygningen af pipeline-konvojen er reflekteret i pull-requests i dette projekt.
JIRA og planlægning
Det er værd at nævne, at vi normalt bruger JIRA som opgavetracker, så lad os oprette en separat board til dette projekt og smide de første opgaver ind på den:
Vi vender tilbage til, hvad der er interessant at give i samspillet mellem JIRA og GitHub.
Automatiserer opbygningen af projektet
Vores testprojekt bygges ved hjælp af Maven, så opbygningen er ret simpel; alt, hvad vi behøver, er mvn clean package.
For at gøre dette ved hjælp af GitHub Actions skal vi oprette en fil i repositoryet, der beskriver vores workflow. Dette kan gøres med en almindelig yml-fil. Jeg kan ikke sige, at jeg kan lide "programmering i yml", men hvad skal man gøre — vi laver en fil build.yml i mappen .github/workflow/, hvor vi vil beskrive handlingerne ved opbygningen af master-branchen:
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
on — dette er beskrivelsen af den begivenhed, der vil udløse vores script.
on: pull_request / push — angiver, at dette workflow skal køres ved hver push til master og oprettelse af pull requests.
Dernæst følger beskrivelsen af opgaverne (jobs) og trinnene i udførelsen (steps) for hver opgave.
runs-on — her kan vi vælge det måloperativsystem, og overraskende nok kan vi endda vælge Mac OS, men for private repositories er det en ret kostbar fornøjelse (sammenlignet med Linux).
uses giver mulighed for at genbruge andre handlinger, så for eksempel bruger vi handlingen actions/setup-java til at opsætte miljøet for Java 11.
Ved hjælp af with Vi kan angive de parametre, som vi bruger til at køre handlingen; i princippet er det argumenter, der vil blive sendt til handlingen.
Det er kun tilbage at starte Maven med projektets build: run: mvn -B clean package til at vælge alle ressourcer i det angivne navnerum for den angivne ressource type. -B det betyder, at vi har brug for non-interactive mode, så Maven ikke pludselig ønsker at stille os spørgsmål
Fremragende! Nu kører projektets build ved hver commit til master.
Vi automatiserer kørsel af tests
Bygningen er god, men i virkeligheden kan et projekt blive bygget korrekt, men ikke fungere. Så næste skridt er at automatisere testkørslerne. Det er også ret praktisk at se resultaterne af testene, når man laver PR-review – fordi du ved præcis, at testene går igennem, og ingen har glemt at køre deres gren, før de laver merge.
Vi gør det muligt at køre tests ved oprettelse af pull-anmodninger og ved merge til master, og lad os tilføje opbygning af test coverage rapporten.
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 }}
Til testdækning bruger jeg Codecov sammen med JaCoCo-pluginet. Codecov har sin egen handling, men den har brug for en token for at arbejde med vores pull-request:
${{ secrets.CODECOV_TOKEN }} — denne konstruktion vil vi støde på flere gange; secrets er en mekanisme til opbevaring af hemmeligheder i GitHub, hvor vi kan gemme adgangskoder/token/hoteller/URL'er og andre oplysninger, der ikke bør være synlige i kodebasen.
Du kan tilføje en variabel til secrets i repository-indstillingerne på GitHub:
Du kan få tokenen på efter at have logget ind med GitHub, skal du blot følge et link af typen: /[repo name]. Приватный репозиторий тоже можно добавить, для этого надо дать права codecov приложению в гитхабе.
Tilføj JaCoCo-pluginet til POM-filen:
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
Nu vil codecov-botten komme ind i hver af vores pull requests og tilføje et diagram over dækningen af ændringer:
Lad os tilføje en statisk analayser
I de fleste af mine open source-projekter bruger jeg SonarCloud til statisk kodeanalyse, hvilket er ret nemt at integrere med Travis CI. Så det er et logisk skridt i migreringen til GitHub Actions at gøre det samme. Actions marketplace er en fantastisk ting, men denne gang svigtede det lidt, fordi jeg af vane fandt den nødvendige action og skrev den ind i workflowet. Det viste sig, at Sonar ikke understøtter analyse af projekter via en action for Maven eller Gradle. Det står selvfølgelig i dokumentationen, men hvem læser den?!
Via action er det ikke muligt, så vi gør det med mvn-plugin:
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 — kan opnås på og skal indtastes i secrets. GITHUB_TOKEN — er en indbygget token, som GitHub genererer. Med den kan sonarcloud[bot] autentificere sig i GitHub for at efterlade kommentarer i vores pull requests.
Dsonar.projectKey — projektets navn i Sonar, som kan ses i projektindstillingerne.
Dsonar.organization — organisationsnavn fra GitHub.
Lav en pull request og vent, indtil sonarcloud[bot] dukker op i kommentarerne:
Release management
Builden er konfigureret, testene er kørt, nu kan vi foretage en release. Lad os se, hvordan GitHub Actions væsentligt forenkler release management.
På arbejdet har jeg projekter, hvis kodebase ligger i bitbucket (som i den historie "om dagen skriver jeg i bitbucket, om natten committer jeg til GitHub"). Desværre har bitbucket ikke indbyggede værktøjer til at håndtere udgivelser. Det er et problem, fordi jeg manuelt skal oprette en side i confluence for hver udgivelse og sende alle funktioner, der er inkluderet i udgivelsen, derind, gennemgå alle tanker, opgaver i jira, commits i repositoryet. Risikoen for fejl er stor; jeg kan glemme noget eller skrive noget, som allerede er blevet udgivet før, og nogle gange er det bare uklart, hvordan man skal klassificere en pull-request — er det en funktion eller en fejlrettelse, eller en testændring, eller noget infrastrukturelt.
Hvordan kan GitHub actions hjælpe os? Der er en fremragende action — release drafter, der giver mulighed for at angive en skabelon til release notes-filen, så man kan indstille kategorier for pull-requests og automatisk gruppere dem i release notes-filen:
Eksempel på en skabelon til at indstille rapporten (.github/release-drafter.yml):
name-template: 'v$NEXT_PATCH_VERSION'
tag-template: 'v$NEXT_PATCH_VERSION'
categories:
- title: ' Nye funktioner'
labels:
- 'type:features'
# i denne kategori samler vi alle PR med etiketten type:features
- title: ' Fejlrettelser'
labels:
- 'type:fix'
# på samme måde for etiketten type:fix osv.
- title: ' Dokumentation'
labels:
- 'type:documentation'
- title: ' Konfiguration'
labels:
- 'type:config'
change-template: '- $TITLE @$AUTHOR (#$NUMBER)'
template: |
## Ændringer
$CHANGES
Vi tilføjer et script til at generere et udkast til udgivelsen (.github/workflows/release-draft.yml):
name: "Opret udkast til udgivelse"
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 }}
Alle pull-requests fra dette tidspunkt vil automatisk blive samlet i release notes — magisk!
Her kan der opstå spørgsmålet: hvad nu hvis udviklerne glemmer at tilføje etiketter i PR? Så er det uklart, hvilken kategori man skal placere den i, og så må man igen finde ud af det manuelt, med hver PR separat. For at løse dette problem kan vi bruge endnu en action — label verifier — som tjekker for tilstedeværelsen af tags på pull-requesten. Hvis der ikke er en eneste obligatorisk tag, vil kontrollen fejle, og vi vil se en besked om dette i vores pull-request.
name: "Verificer type etiketter"
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'
Nu skal enhver pull-request mærkes med en af tags: type:fix, type:features, type:documentation, type:tests, type:config.
Automatisk annotering af pull-requests
Da vi nu har berørt emnet effektivt arbejde med pull-requests, er det værd at nævne en handling som labeler, som tildeler etiketter i PR'en baseret på hvilke filer der er ændret. For eksempel kan vi mærke enhver pull-request som [build], hvor der er ændringer i mappen .github/workflow.
Det er ret nemt at tilslutte:
name: "Auto-assign themes to PR"
on:
- pull_request
jobs:
triage:
runs-on: ubuntu-18.04
steps:
- uses: actions/labeler@v2
with:
repo-token: ${{ secrets.GITHUB_TOKEN }}
Vi har også brug for en fil, der beskriver overensstemmelsen mellem projektmapperne og temaerne i 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/**"
Jeg har ikke haft held med at kombinere handlingen, der automatisk tildeler etiketter til pull-requests med handlingen, der kontrollerer for obligatoriske etiketter; match-label nægter konsekvent at se de etiketter, der er tildelt af botten. Det ser ud til, at det er lettere at skrive min egen handling, der kombinerer begge trin. Men selv i denne form er det ret praktisk; man skal vælge en etikette fra listen, når man opretter en pull-request.
Det er tid til at deploye
Jeg har prøvet flere forskellige deployment-metoder via GitHub Actions (gennem ssh, gennem scp og ved hjælp af docker-hub), og jeg kan sige, at du sandsynligvis vil finde en måde at uploade binærfiler til serveren, uanset hvor kompleks din pipeline måtte være.
Jeg kunne lide muligheden for at holde hele infrastrukturen et sted, så lad os se på, hvordan man laver deployment til GitHub Packages (dette er et repository til binært indhold, npm, jar, docker).
Script til opbygning af en docker-billede og offentliggørelse af det i GitHub Packages:
navn: Udrul docker-billede
på:
push:
grene:
- 'master'
jobs:
build_docker_image:
runs-on: ubuntu-18.04
steps:
# Byg JAR:
- uses: actions/checkout@v1
- name: opsæt JDK 11
uses: actions/setup-java@v1
with:
java-version: 1.11
- name: Maven Pakke
run: mvn -B clean compile package -DskipTests
# Sæt globale miljøvariabler:
- name: sæt globalt miljø
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#*\/}"
# Byg Docker-billede:
- name: Byg og tag billede
run: |
docker build -t "${{ steps.global_env.outputs.DOCKERHUB_IMAGE_NAME }}:latest" -t "${{ steps.global_env.outputs.DOCKERHUB_IMAGE_NAME }}:${GITHUB_SHA::8}" .
- name: Docker login
run: docker login docker.pkg.github.com -u $GITHUB_ACTOR -p ${{secrets.GITHUB_TOKEN}}
# Udgiv billede til github-pakke-repository:
- name: Udgiv billede
env:
IMAGE_NAME: $GITHUB_REPOSITORY
run: docker push "docker.pkg.github.com/$GITHUB_REPOSITORY/${{ steps.global_env.outputs.IMAGE_NAME }}"
For at begynde skal vi bygge JAR-filen til vores applikation, hvorefter vi beregner stien til GitHub docker registry og navnet på vores billede. Der er nogle tricks her, som vi ikke har stødt på før:
- Konstruktionen echo «::set-output name=NAME::VALUE» giver os mulighed for at indstille værdien af en variabel i det nuværende skridt, så den senere kan læses i alle andre skridt.
- For at få værdien af en variabel indstillet i det forrige skridt, kan vi bruge identifikatoren for det skridt: ${{ steps.global_env.outputs.DOCKERHUB_IMAGE_NAME }}
- Den standardvariabel GITHUB_REPOSITORY gemmer navnet på repositoryet og dets ejer («owner/repo-name»). For at udtrække alt undtagen navnet på repositoryet fra denne streng, kan vi bruge bash-syntaks: ${GITHUB_REPOSITORY#*\/}
Derefter skal vi bygge docker-billedet:
docker build -t "docker.pkg.github.com/antkorwin/github-actions/github-actions:latest"
Log ind på registry:
docker login docker.pkg.github.com -u $GITHUB_ACTOR -p ${{secrets.GITHUB_TOKEN}}
Og udgive billedet i GitHub Packages Repository:
docker push "docker.pkg.github.com/antkorwin/github-actions/github-actions"
For at angive billedversionen bruger vi de første cifre fra SHA-hashen for committet — GITHUB_SHA har også sine nuancer, hvis du planlægger at lave sådanne builds ikke kun ved sammenslutning til master, men også ved oprettelse af pull-requests, så kan SHA'en være forskellig fra hash, som vi ser i git-historikken, fordi handlingen actions/checkout genererer sin unikke hash for at undgå indbyrdes blokering af handlinger i PR.
Hvis alt er lykkedes, vil du åbne pakkesektionen (https://github.com/antkorwin/github-actions/packages) i repositoryet og se det nye docker-billede:
Her kan man også se listen over versioner af Docker-billedet.
Det eneste, der er tilbage, er at konfigurere vores server til at arbejde med dette registry og genstarte tjenesten. Hvordan man gør det via systemd, vil jeg nok fortælle om en anden gang.
Overvågning
Lad os se på en enkel måde at lave health check af vores applikation ved hjælp af GitHub Actions. I vores boot-applikation er der en actuator, så API'et til at kontrollere dens tilstand behøver vi slet ikke at skrive, alt er allerede lavet for dovne. Vi skal bare kalde hosten: 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"}
Alt, hvad vi skal gøre, er at skrive en cron-job for serverkontrol, og hvis den ikke svarer, sender vi en meddelelse til Telegram.
Lad os først se, hvordan man starter workflow'en via cron:
on:
schedule:
- cron: '*\/5 * * * *'
Det er enkelt, det er næsten uvirkeligt, at man kan lave sådanne begivenheder i GitHub, som slet ikke passer ind i webhooks. Detaljer findes i dokumentationen:
Vi tjekker serverstatus manuelt via 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 is failed"
exit 1
fi
echo "It's OK"
Først gemmer vi det, som serveren svarede på, i en variabel; i det næste trin tjekker vi, at status er UP, og hvis ikke, afslutter vi med en fejl. Hvis man skal 'tvinge' handlingen, så exit 1 — er det det rette våben.
- 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 }}
Vi sender en besked til Telegram, kun hvis handlingen fejlede i det forrige trin. Til at sende meddelelsen bruger vi appleboy/telegram-action; man kan læse om, hvordan man får en bot-token og chat-id i dokumentationen:
Glem ikke at angive i hemmelighederne på GitHub: URL til serveren og tokens til Telegram-boten.
Bonus spor — JIRA til dovne
Jeg lovede, at vi ville vende tilbage til JIRA, og det gjorde vi. Jeg har hundrede gange observeret situationen på stand-ups, hvor udviklerne har lavet en funktion, har slået en gren sammen, men glemte at flytte opgaven til JIRA. Selvfølgelig ville det være lettere, hvis alt foregik ét sted, men i praksis skriver vi kode i IDE, slår grene sammen i Bitbucket eller GitHub, mens vi senere flytter opgaver til JIRA; dette kræver, at vi åbner nye vinduer, nogle gange logger vi ind igen osv. Når man klart husker, hvad man skal gøre videre, giver det ikke mening at åbne boardet endnu en gang. Derfor skal vi bruge tid på stand-up'en til at opdatere opgavelisten om morgenen.
GitHub vil hjælpe os med denne rutine, for i starten kan vi automatisere flytningen af opgaver til kolonnen code_review, når vi sender en pull-request. Alt, hvad der kræves, er at følge aftalen om navngivning af grene:
[projekt_navn]-[opgave_nummer]-beskrivelse
For eksempel, hvis projektnøglen "GitHub Actions" er GA, så GA-8-jira-bot kan være grenen til implementeringen af opgaven GA-8.
Integrationen med JIRA fungerer gennem handlinger fra Atlassian, og de er ikke perfekte; jeg må sige, at nogle af dem overhovedet ikke fungerede for mig. Men vi vil kun diskutere dem, der helt sikkert virker og aktivt bruges.
For at starte skal du autorisere dig i JIRA via handlingen: 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 }}
For dette skal du få en token i JIRA; hvordan du gør dette, er beskrevet her:
Vi udtrækker opgave-ID'et fra grenens navn:
- 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 branch name: $GITHUB_HEAD_REF
echo extracted issue: ${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 "Venligst navngiv din gren i henhold til JIRA-opgaven: [project_key]-[task_number]-branch_name"
exit 1
fi
echo successfully found JIRA issue: ${{steps.find_issue.outputs.ISSUE_ID}}
Hvis du søger i GitHub marketplace, kan du finde handlingen til denne opgave, men jeg måtte skrive det samme ved hjælp af grep baseret på grenens navn, fordi denne handling fra Atlassian ikke ville fungere på mit projekt; det ville tage længere tid at finde ud af, hvad der gik galt, end at gøre det manuelt.
Det er kun nødvendigt at flytte opgaven til kolonnen "Code review", når pull-requesten oprettes:
- name: Overfør opgave
if: ${{ success() }}
uses: atlassian/gajira-transition@master
with:
issue: ${{ steps.find_issue.outputs.ISSUE_ID }}
transition: "Code review"
Der findes en speciel handling på GitHub; alt, hvad den har brug for, er opgave-id'et, som blev modtaget i det forrige trin, og autentificering i JIRA, som vi gjorde tidligere.
På samme måde kan opgaver flyttes ved merge til master og andre begivenheder i GitHub workflow. Generelt afhænger det af din fantasi og dit ønske om at automatisere rutineprocesser.
Konklusioner
Hvis man ser på det klassiske DEVOPS-diagram, har vi dækket alle faser bortset fra operation, men jeg tror, at hvis man anstrenger sig, kan man finde en eller anden handling i markedet til integration med et help-desk system, så vi kan konkludere, at pipeline'en er grundig, og der kan drages konklusioner baseret på dens anvendelse.
Fordele:
- Marketplace med færdige handlinger til alle formål er virkelig fantastisk. I de fleste af dem kan man også se kildekoden for at forstå, hvordan man kan løse en lignende opgave eller indsende en feature request direkte til forfatteren i GitHub-repositoriet.
- Valget af målplatform til opbygning: Linux, macOS, Windows er en ret interessant funktion.
- GitHub Packages er en fantastisk ting, at have al infrastruktur samlet ét sted er praktisk; man slipper for at surfe rundt i forskellige vinduer, alt er inden for en eller to museklik og er perfekt integreret med GitHub Actions. Understøttelse af docker registry i gratisversionen er også en god fordel.
- GitHub skjuler hemmeligheder i bygge-logs, så at bruge det til at gemme adgangskoder og tokens er ikke så skræmmende. I løbet af mine eksperimenter har jeg aldrig set en hemmelighed i klar tekst i konsollen.
- Gratis for open source-projekter
Ulemper:
- YML, jeg er ikke vild med det. Når jeg arbejder med sådan et flow, er min mest almindelige commit-besked "fix yml format"; nogle gange glemmer man at sætte en tabulator, eller så skriver man ikke på den rigtige linje. At sidde foran skærmen med en transportør og lineal er ikke det mest behagelige job.
- DEBUG, at debugge flow med commits, genopbygning og output i konsollen er ikke altid praktisk, men det er mere et spørgsmål om, at "I er kræsne", man er vant til at arbejde med bekvemme IDE'er, hvor man kan debugge hvad som helst.
- Du kan skrive din egen handling på hvad som helst, hvis du pakker det ind i Docker, men det understøttes kun nativt af JavaScript. Selvfølgelig er det en smagssag, men jeg ville foretrække noget andet i stedet for js.
Jeg vil minde om, at lageret med alle scripts er her:
Næste uge skal jeg holde et oplæg på konferencen Heisenbug 2020 Piter. Jeg vil ikke kun fortælle, hvordan man undgår fejl, når man forbereder testdata, men også dele mine hemmeligheder til arbejde med datasæt i Java-applikationer!
Kilde: habr.com
