GitHub-APIs: Rezepte für den Entwickler-Alltag

In der Softwareentwicklung gibt es immer wieder Routinetätigkeiten, die automatisiert werden wollen. Befindet sich das Code-Repository auf GitHub, so stehen dafür verschiedene APIs zur Verfügung. Und manchmal eröffnen die APIs neue Möglichkeiten, an die man vorher gar nicht gedacht hat.

Dieser Vortrag führt durch verschiedene praktische Beispiele und zeigt was hier möglich ist: Sei es, um Releases mit GitHub Actions zu automatisieren, Code-Qualität zu prüfen, Repository-Einstellungen als Configuration-as-Code abzulegen, eigene Custom-Dashboards zu Issues und Pull-Requests zu erstellen oder Aktionen über Bots oder REST-APIs zu automatisieren.

Die Teilnehmer erhalten dadurch Anknüpfungspunkte, um eigene Aufgaben zu automatisieren und um bestehende Automatisierungen z. B. in Open-Source-Projekten zu verstehen.

Transcript

1. GitHub-APIs:
   Rezepte für den Entwickler-Alltag
   Alexander Schwartz, Principal Software Engineer @ Red Hat
   JavaLand | 2023-03-22
   

   View Slide

2. CC BY-NC-SA 4.0 | März 2023 | GitHub APIs: Rezepte für den Entwickler-Alltag | Alexander Schwartz 3
   GitHub-APIs: Rezepte für den Entwickler Alltag
   Motivation
   GitBot der auf
   Kommentare reagiert
   REST API
   für Änderungen
   Pull Requests
   prüfen und
   annotieren
   Daten abfragen
   per GraphQL
   Website auf
   GitHub Pages
   publizieren
   Build ausführen bei
   neuen Commit
   Eigene interaktive
   UIs bauen
   Dependencies aktualisieren
   via Dependabot
   Releases
   erstellen
   

   View Slide

3. CC BY-NC-SA 4.0 | März 2023 | GitHub APIs: Rezepte für den Entwickler-Alltag | Alexander Schwartz 4
   Git ist eine Versionsverwaltung – und was ist GitHub?
   Git:
   Software zur dezentralen Versionsverwaltung von Quellcode.
   Git-Repository:
   Datenbank mit Quellcode zu einem konkreten Software-Projekt.
   GitHub:
   Amerikanisches Unternehmen, welches cloudbasierte Dienste und APIs rund um
   Git-Repositories anbietet.
   

   View Slide

4. CC BY-NC-SA 4.0 | März 2023 | GitHub APIs: Rezepte für den Entwickler-Alltag | Alexander Schwartz 5
   Hello world: Website bauen, die Inhalte von aus zwei Repositories enthält
   Website
   Git 1
   Build
   Git 2
   Standard
   ?
   

   View Slide

5. CC BY-NC-SA 4.0 | März 2023 | GitHub APIs: Rezepte für den Entwickler-Alltag | Alexander Schwartz 6
   Hello World: Einen Web Hook ausführen
   name: Website
   on:
   push:
   branches:
   - main
   paths:
   - 'doc/**'
   jobs:
   triggerNetlify:
   runs-on: ubuntu-latest
   steps:
   - name: Trigger Build
   shell: bash
   env:
   NETLIFY_BUILD_TOKEN: ${{ secrets.NETLIFY_BUILD_TOKEN }}
   run: >
   curl -f -X POST -d {}
   https://api.netlify.com/build_hooks/${NETLIFY_BUILD_TOKEN}
   Repo: asciidoctor/asciidoctor-intellij-plugin
   

   View Slide

6. GitHub Workflow
   Cache
   CC BY-NC-SA 4.0 | März 2023 | GitHub APIs: Rezepte für den Entwickler-Alltag | Alexander Schwartz 8
   Den Code prüfen und Artefakte publizieren
   Push
   Checkout
   Build
   Publish
   Artefact
   

   View Slide

7. CC BY-NC-SA 4.0 | März 2023 | GitHub APIs: Rezepte für den Entwickler-Alltag | Alexander Schwartz 9
   Den Code prüfen
   • Build
   • Cache
   • Conditionals
   • Secrets
   # .github/workflows/build.yml
   name: Java CI with Maven
   on:
   push:
   jobs:
   build:
   runs-on: ubuntu-latest
   steps:
   - uses: actions/checkout@v3
   - uses: actions/setup-java@v3
   with:
   distribution: 'temurin'
   java-version: '11'
   cache: 'maven'
   - name: Build with Maven
   run: |
   ./mvnw -B test
   Repo: ahus1/dropwizard-keycloak-integration
   

   View Slide

8. CC BY-NC-SA 4.0 | März 2023 | GitHub APIs: Rezepte für den Entwickler-Alltag | Alexander Schwartz 10
   Den Code prüfen
   • Build
   • Cache
   • Conditionals
   • Secrets
   # add to the steps:
   - name: Cache Maven Wrapper
   uses: actions/cache@v3
   with:
   path: .mvn/wrapper/maven-wrapper.jar
   key: ${{ runner.os }}-maven-wrapper-
   ${{ hashFiles('**/maven-wrapper.properties') }}
   restore-keys: |
   ${{ runner.os }}-maven-wrapper-
   

   View Slide

9. CC BY-NC-SA 4.0 | März 2023 | GitHub APIs: Rezepte für den Entwickler-Alltag | Alexander Schwartz 11
   Den Code prüfen
   • Build
   • Cache
   • Conditionals
   • Secrets
   on:
   push:
   branches-ignore:
   - 'dependabot/**'
   

   View Slide

10. CC BY-NC-SA 4.0 | März 2023 | GitHub APIs: Rezepte für den Entwickler-Alltag | Alexander Schwartz 12
    Artefakt publizieren
    • Build
    • Cache
    • Conditionals
    • Secrets
    # add to the steps:
    - name: publish
    if: >
    ${{ success() && github.event_name != 'pull_request' &&
    github.ref == 'refs/heads/master' }}
    env:
    SONATYPE_PASSWORD: ${{ secrets.SONATYPE_PASSWORD }}
    SONATYPE_USERNAME: ${{ secrets.SONATYPE_USERNAME }}
    run: |
    mvn deploy --settings cisettings.xml -DskipTests=true -B
    

    View Slide

11. GitHub Workflow
    Cache
    CC BY-NC-SA 4.0 | März 2023 | GitHub APIs: Rezepte für den Entwickler-Alltag | Alexander Schwartz 13
    Den Code prüfen und Artefakte publizieren
    Push
    Checkout
    Build
    Publish
    Artefact
    

    View Slide

12. CC BY-NC-SA 4.0 | März 2023 | GitHub APIs: Rezepte für den Entwickler-Alltag | Alexander Schwartz 14
    Draft Release anlegen
    - name: Remove Old Release Drafts
    env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    run: |
    curl -H "Authorization: Bearer $GITHUB_TOKEN" ... | jq ... | curl ...
    - name: Create Release Draft
    id: createDraft
    uses: actions/create-release@v1
    env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    with:
    tag_name: ${{ needs.build.outputs.version }}
    release_name: ${{ needs.build.outputs.version }}
    body: ${{ needs.build.outputs.changelog }}
    draft: true
    prerelease: false
    Repo: asciidoctor/asciidoctor-intellij-plugin
    

    View Slide

13. Dependabot
    CC BY-NC-SA 4.0 | März 2023 | GitHub APIs: Rezepte für den Entwickler-Alltag | Alexander Schwartz 15
    Dependabot aktualisiert GitHub Actions in Workflows
    Neues
    Release
    der GHA Pull
    Request
    📒 .github
    └─📄 dependabot.yml
    Repo: asciidoctor/asciidoctor-intellij-plugin
    

    View Slide

14. CC BY-NC-SA 4.0 | März 2023 | GitHub APIs: Rezepte für den Entwickler-Alltag | Alexander Schwartz 16
    Dependabot aktualisiert (auch) GitHub Actions in Workflows
    version: 2
    updates:
    - package-ecosystem: "gradle"
    directory: "/"
    schedule:
    interval: "daily"
    - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
    interval: "daily"
    Repo: asciidoctor/asciidoctor-intellij-plugin
    

    View Slide

15. Workflow mit einer
    Custom GitHub Action
    CC BY-NC-SA 4.0 | März 2023 | GitHub APIs: Rezepte für den Entwickler-Alltag | Alexander Schwartz 17
    Einen eigenen GitBot bauen
    Event
    (z. B. Kommentar)
    Aktion via GitHub
    REST API o. Ä.,
    (z. B. Rerun Failed
    Workflow Jobs)
    Repo: keycloak/keycloak-gh-actionbot
    

    View Slide

16. CC BY-NC-SA 4.0 | März 2023 | GitHub APIs: Rezepte für den Entwickler-Alltag | Alexander Schwartz 18
    Einen eigenen GitBot bauen
    name: Keycloak GitHub bot
    on:
    issue_comment:
    types:
    - created
    permissions:
    actions: write
    pull-requests: write
    jobs:
    act:
    runs-on: ubuntu-latest
    steps:
    - uses: keycloak/keycloak-gh-actionbot@v0.1.0
    with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    „uses“ enthält ein GitHub Repository:
    Owner, Repository und Version
    Repo: keycloak/keycloak-gh-actionbot
    

    View Slide

17. 19
    CC BY-NC-SA 4.0 | März 2023 | GitHub APIs: Rezepte für den Entwickler-Alltag | Alexander Schwartz
    Einen eigenen GitBot bauen
    # action.yml
    name: Keycloak Bot
    description: Bot reacting on comments
    inputs:
    github_token:
    required: true
    debug:
    required: false
    default: "false"
    runs:
    using: node16
    main: dist/index.js
    📒 keycloak-gh-actionbot
    ├─📄 action.yml
    ├─📄 index.js
    ├─📄 package.json
    └─📂 dist
    └─📄 index.js
    Repo: keycloak/keycloak-gh-actionbot
    

    View Slide

18. 20
    CC BY-NC-SA 4.0 | März 2023 | GitHub APIs: Rezepte für den Entwickler-Alltag | Alexander Schwartz
    Einen eigenen GitBot bauen
    // index.js
    import core from "@actions/core";
    import { context } from "@actions/github";
    import { Octokit } from "octokit";
    async function run() {
    const githubToken = core.getInput("github_token");
    const octokit = new Octokit({ auth: githubToken });
    if (context.eventName === "issue_comment") {
    /* permission checks skipped until finally: */
    await octokit.rest.actions.reRunWorkflowFailedJobs({
    owner: context.payload.repository.owner.login,
    repo: context.payload.repository.name,
    run_id: job.run_id,
    })
    }
    📒 keycloak-gh-actionbot
    ├─📄 action.yml
    ├─📄 index.js
    ├─📄 package.json
    └─📂 dist
    └─📄 index.js
    Repo: keycloak/keycloak-gh-actionbot
    

    View Slide

19. CC BY-NC-SA 4.0 | März 2023 | GitHub APIs: Rezepte für den Entwickler-Alltag | Alexander Schwartz 21
    Sicherheit bei GitHub Actions
    Berechtigungen:
    Die Rechte können nur grob eingeschränkt werden.
    Vertrauenswürdige Quellen:
    Alle „action/…“ sind von GitHub, alle anderen von anderen Personen.
    Versionierung:
    Eine Version wie „@2“ zeigt auf einen Branch oder Tag, welcher vom Owner
    jederzeit umgehängt werden kann. Auch SHA-1 (böswillige) Kollisionen sind
    möglich.
    

    View Slide

20. Workflow mit einer
    GitHub Action die
    CodeQL erzeugt
    (z. B. JetBrains Qodana)
    CC BY-NC-SA 4.0 | März 2023 | GitHub APIs: Rezepte für den Entwickler-Alltag | Alexander Schwartz 22
    Code-Qualität prüfen mit CodeQL
    Pull Request
    mit Code
    oder Docs
    SARIF report mit
    Upload,
    Annotation im
    Pull Request
    HTML Report mit
    Abweichungen
    Repo: asciidoctor/asciidoctor-intellij-plugin
    

    View Slide

21. CC BY-NC-SA 4.0 | März 2023 | GitHub APIs: Rezepte für den Entwickler-Alltag | Alexander Schwartz 23
    Code-Qualität prüfen mit CodeQL
    // steps in my GitHub workflow
    - name: 'Qodana for Docs'
    uses: JetBrains/qodana-action@v2022.2.1
    with:
    args: >
    --linter,jetbrains/qodana-jvm-community:2022.2,
    -v,${{ github.workspace }}/grazie:/opt/idea/plugins/grazie,
    -v,${{ github.workspace }}/asciidoctor-intellij...
    --baseline,doc/qodana-baseline.sarif.json
    - name: Upload SARIF report to GitHub
    uses: github/codeql-action/upload-sarif@v2
    with:
    sarif_file: ${{ runner.temp }}/qodana/results/qodana.sarif.json
    Repo: asciidoctor/asciidoctor-intellij-plugin
    

    View Slide

22. CC BY-NC-SA 4.0 | März 2023 | GitHub APIs: Rezepte für den Entwickler-Alltag | Alexander Schwartz 24
    Code-Qualität prüfen mit CodeQL
    Repo: asciidoctor/asciidoctor-intellij-plugin
    

    View Slide

23. Terraform
    CC BY-NC-SA 4.0 | März 2023 | GitHub APIs: Rezepte für den Entwickler-Alltag | Alexander Schwartz 25
    GitHub Configuration-as-Code
    GitHub REST API
    terraform.tfstate
    main.tf
    

    View Slide

24. (statische)
    Website bauen
    CC BY-NC-SA 4.0 | März 2023 | GitHub APIs: Rezepte für den Entwickler-Alltag | Alexander Schwartz 26
    Eine Website publizieren mit GitHub Pages (neuer Prozess)
    Code-
    Änderung
    Website ist
    live
    Archiv hochladen
    an die Workflow-
    Instanz
    GitHub Pages
    publizieren
    Repo: keycloak/keycloak-benchmark
    

    View Slide

25. CC BY-NC-SA 4.0 | März 2023 | GitHub APIs: Rezepte für den Entwickler-Alltag | Alexander Schwartz 27
    Eine Website publizieren mit GitHub Pages (neuer Prozess)
    // add as job in workflow
    build-and-publish-docs:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - name: Set up Node.js
    uses: actions/setup-node@v3
    with:
    node-version: '16.x'
    cache: 'yarn'
    cache-dependency-path: 'antora/yarn.lock'
    - name: Build docs
    working-directory: antora
    run: ./build.sh
    - name: Upload artifact
    uses: actions/upload-pages-artifact@v1
    with:
    path: antora/_site/keycloak-benchmark
    

    View Slide

26. CC BY-NC-SA 4.0 | März 2023 | GitHub APIs: Rezepte für den Entwickler-Alltag | Alexander Schwartz 28
    Eine Website publizieren mit GitHub Pages (neuer Prozess)
    // add as job in workflow
    github-pages:
    environment:
    name: github-pages
    url: ${{ steps.deployment.outputs.page_url }}
    name: GitHub Pages
    runs-on: ubuntu-latest
    needs:
    - build
    permissions:
    pages: write
    id-token: write
    steps:
    - name: Deploy to GitHub Pages
    id: deployment
    uses: actions/deploy-pages@v1
    Repo: keycloak/keycloak-benchmark
    

    View Slide

27. Report erstellen
    (gh, bash)
    CC BY-NC-SA 4.0 | März 2023 | GitHub APIs: Rezepte für den Entwickler-Alltag | Alexander Schwartz 29
    Dashboard mit GitHub CLI für Auswertungen erstellen
    Cron Job
    Website ist
    live
    Website Bauen
    (Jekyll konvertiert
    Markdown in HTML)
    GitHub Pages
    publizieren
    Repo: stianst/keycloak-dashboard
    

    View Slide

28. CC BY-NC-SA 4.0 | März 2023 | GitHub APIs: Rezepte für den Entwickler-Alltag | Alexander Schwartz 30
    Dashboard mit GitHub CLI für Auswertungen erstellen
    build-dashboard:
    runs-on: ubuntu-latest
    outputs:
    build: ${{ steps.report.outputs.build }}
    steps:
    - uses: actions/checkout@v3
    - id: report
    env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    run: |
    bash report.sh > README.md
    if ( ! git diff --exit-code &>/dev/null ); then
    git config --global user.email ...
    git config --global user.name ...
    git commit -a -m "Updated dashboard"
    git push
    echo ::set-output name=build::"true"
    fi
    Repo: stianst/keycloak-dashboard
    OLD
    

    View Slide

29. CC BY-NC-SA 4.0 | März 2023 | GitHub APIs: Rezepte für den Entwickler-Alltag | Alexander Schwartz 31
    Dashboard mit GitHub CLI für Auswertungen erstellen
    build-dashboard:
    runs-on: ubuntu-latest
    outputs:
    build: ${{ steps.report.outputs.build }}
    steps:
    - uses: actions/checkout@v3
    - id: report
    env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    run: |
    bash report.sh > README.md
    if ( ! git diff --exit-code &>/dev/null ); then
    git config --global user.email ...
    git config --global user.name ...
    git commit -a -m "Updated dashboard"
    git push
    echo "build=true" >> $GITHUB_OUTPUT
    fi
    Repo: stianst/keycloak-dashboard
    NEW
    

    View Slide

30. CC BY-NC-SA 4.0 | März 2023 | GitHub APIs: Rezepte für den Entwickler-Alltag | Alexander Schwartz 32
    Dashboard mit GitHub CLI für Auswertungen erstellen
    # report.sh
    DATE_6_EXPIRED=`date -d "-6 month" +%Y-%m-%d`
    # ...
    PR_COUNT=`gh api -X GET search/issues -f q="repo:keycloak/keycloak is:pr is:open"
    -f per_page=1 -q .total_count`
    PR_EXPIRED_6_COUNT=`gh api -X GET search/issues -f q="repo:keycloak/keycloak is:pr
    is:open created:<$DATE_6_EXPIRED" -f per_page=1 -q .total_count`
    # ...
    echo "|PRs| |"
    echo "|---|-|"
    echo "|[Open PRs](https://github.com/keycloak/keycloak/pulls)|$PR_COUNT|"
    echo "|[Older than 6
    months](https://github.com/keycloak/keycloak/pulls?q=is%3Apr+is%3Aopen+created%3A%
    3C$DATE_6_EXPIRED)|$PR_EXPIRED_6_COUNT|"
    

    View Slide

31. Quarkus Web App
    CC BY-NC-SA 4.0 | März 2023 | GitHub APIs: Rezepte für den Entwickler-Alltag | Alexander Schwartz 33
    Dynamische Web-App als Dashboard und persönlicher Client
    GitHub GraphQL
    GitHub REST API
    GitHub Personal
    Access Token
    

    View Slide

32. Keycloak GitHub Action Bot
    (GitHub Bot)
    keycloak/keycloak-gh-actionbot
    IntelliJ AsciiDoc Plugin
    (Releases, Webhook, Qodana, CodeQL)
    asciidoctor/asciidoctor-intellij-plugin
    Keycloak Dropwizard
    (Build, Sonatype Nexus)
    ahus1/keycloak-dropwizard-integration
    Keycloak Static Dashboard
    (gh, bash, Markdown, Jekyll)
    stianst/keycloak-dashboard
    CC BY-NC-SA 4.0 | März 2023 | GitHub APIs: Rezepte für den Entwickler-Alltag | Alexander Schwartz 34
    Beispiele
    @ahus1de
    Keycloak Interactive Dashboard
    (Quarkus, GitHub GraphQL)
    ahus1/keycloak-gitbot
    Keycloak Benchmark
    (Maven Build, Antora Static Documentation Site)
    keycloak/keycloak-benchmark
    GitHub REST API
    https://docs.github.com/en/rest
    

    View Slide

33. Kontakt
    Alexander Schwartz
    Principal Software Engineer
    alexander.schwartz@gmx.net
    https://www.ahus1.de
    @ahus1de
    CC BY-NC-SA 4.0 | März 2023 | GitHub APIs: Rezepte für den Entwickler-Alltag | Alexander Schwartz 35
    

    View Slide