Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 12: Composite Actions und Reusable Workflows

Ziel: Wiederholte Steps in eine Composite Action auslagern, einen ganzen Job als Reusable Workflow bauen und von ci.yml und release.yml aus aufrufen. · Dauer: ca. 75 min · Voraussetzung: Tag 11

Briefing

  • ci.yml und release.yml wiederholen sich: dreimal checkout plus setup-go, zweimal derselbe Build-Job.
  • Eine Composite Action bündelt Steps. Sie liegt in einem Ordner mit action.yml und wird mit uses: ./pfad als ein Step aufgerufen.
  • Ein Reusable Workflow bündelt Jobs. Er hat den Trigger workflow_call, und ein Job ruft ihn mit uses: auf – statt runs-on und steps.
  • Faustregel: Composite für „diese drei Steps immer zusammen“, Reusable Workflow für „dieser ganze Ablauf, auch mit eigenem Runner und eigenen Rechten“.
 ci.yml ─┬─ test:  steps: uses ./.github/actions/go-setup  (Composite)
         └─ build: uses ./.github/workflows/go-build.yml   (Reusable, Matrix)
 release.yml ─ build: uses ./.github/workflows/go-build.yml

Drill 1: Eine Composite Action

cd ~/gha-lab/notes-actions
mkdir -p .github/actions/go-setup
cat > .github/actions/go-setup/action.yml <<'EOF'
name: go-setup
description: Go aus go.mod, optional ohne Cache
inputs:
  cache:
    description: Go-Cache nutzen
    default: "true"
outputs:
  go-version:
    description: Installierte Go-Version
    value: ${{ steps.go.outputs.go-version }}
runs:
  using: composite
  steps:
    - id: go
      uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
      with:
        go-version-file: go.mod
        cache: ${{ inputs.cache }}
    - shell: bash
      env:
        GO_VERSION: ${{ steps.go.outputs.go-version }}
      run: echo "Go $GO_VERSION bereit"
EOF
  • runs.using: composite macht die Datei zur Composite Action.
  • Jeder run:-Step braucht hier shell: – eine Vorgabe wie im Workflow gibt es nicht.
  • Eingaben sind immer Text: default: "true" in Anführungszeichen.
  • outputs reicht einen Wert aus einem inneren Step nach außen.
  • Kein checkout in der Action: Sie liegt im Repository, und uses: ./… findet sie erst, wenn ausgecheckt ist. Der Checkout bleibt im Workflow. Eine Action aus einem anderen Repository (uses: <du>/go-setup@v1) lädt der Runner selbst – sie dürfte auch auschecken.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Die Composite Action nutzen

Im Job test von ci.yml ersetzt sie setup-go. Die ganze Datei, mit build und smoke vorerst unverändert:

cat > .github/workflows/ci.yml <<'EOF'
name: ci
permissions:
  contents: read
concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

on:
  push:
    branches: [main]
    paths-ignore: ['**.md']
  pull_request:

jobs:
  test:
    strategy:
      matrix:
        os: [ubuntu-24.04, ubuntu-24.04-arm]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - uses: ./.github/actions/go-setup
      - name: Statische Prüfung
        run: go vet ./...
      - run: go test ./...

  build:
    needs: test
    uses: ./.github/workflows/go-build.yml
    with:
      version: ${{ github.sha }}

  smoke:
    needs: build
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          name: notes-api-linux-amd64
      - name: Starten und prüfen
        run: |
          chmod +x notes-api-linux-amd64
          NOTES_API_KEY=lab-api-key-123 PORT=8090 ./notes-api-linux-amd64 &
          sleep 1
          curl -fsS localhost:8090/healthz

  lint:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - uses: ./.github/actions/go-setup
      - uses: golangci/golangci-lint-action@ba0d7d2ec06a0ea1cb5fa41b2e4a3ab91d21278a # v9.3.0
        with:
          version: v2.15.0
EOF

Der Job build ruft schon den Reusable Workflow auf, den es noch nicht gibt. Ohne ihn ist ci.yml ungültig – also gleich weiter, gepusht wird nach Drill 3.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Ein Reusable Workflow

cat > .github/workflows/go-build.yml <<'EOF'
name: go-build
on:
  workflow_call:
    inputs:
      version:
        description: Wert für main.version
        type: string
        required: true
      cache:
        type: boolean
        default: true
    outputs:
      artefakte:
        description: Namen der hochgeladenen Artefakte
        value: notes-api-linux-amd64 notes-api-linux-arm64

permissions:
  contents: read

jobs:
  bauen:
    strategy:
      matrix:
        goarch: [amd64, arm64]
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - uses: ./.github/actions/go-setup
        with:
          cache: ${{ inputs.cache }}
      - name: Bauen
        env:
          CGO_ENABLED: "0"
          GOOS: linux
          GOARCH: ${{ matrix.goarch }}
          VERSION: ${{ inputs.version }}
        run: >-
          go build -trimpath -ldflags "-s -w -X main.version=${VERSION#v}"
          -o notes-api-linux-$GOARCH .
      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: notes-api-linux-${{ matrix.goarch }}
          path: notes-api-linux-${{ matrix.goarch }}
          retention-days: 7
EOF
git add .github
git commit -qm "ci: Composite go-setup, Reusable go-build"
git push -q
  • on: workflow_call macht den Workflow aufrufbar. Eingaben haben hier einen Typ: string, boolean oder number.
  • Der Aufrufer übergibt sie mit with:. Ein Job mit uses: hat keine steps und kein runs-on – beides steht im aufgerufenen Workflow.
  • Artefakte, die der Reusable Workflow hochlädt, gehören zum Lauf des Aufrufers. Darum findet smoke sie wie bisher.
  • ${VERSION#v} entfernt ein führendes v: Aus dem Tag v0.6.0-rc.2 (Drill 4) wird 0.6.0-rc.2. Aus ci.yml kommt der volle Commit-SHA – Ausdrücke können keine Zeichenketten kürzen, und das Kürzen in ci.yml bräuchte einen eigenen Step.

Mit der ID aus gh run list --workflow ci.yml --limit 1, sobald der Lauf fertig ist:

gh run view <ID> --json jobs --jq '.jobs[].name'

Erwartet:

lint
test (ubuntu-24.04)
test (ubuntu-24.04-arm)
build / bauen (arm64)
build / bauen (amd64)
smoke

build / bauen (amd64): der Job build im Aufrufer, darin der Job bauen aus go-build.yml, darin der Matrix-Wert.

gh run view <ID> --log | grep -E 'Z Go [0-9.]+ bereit' | head -2

Erwartet (Zeitstempel gekürzt, die Reihenfolge kann abweichen):

lint    Run ./.github/actions/go-setup  ... Go 1.27.0 bereit
test (ubuntu-24.04) Run ./.github/actions/go-setup  ... Go 1.27.0 bereit

Fortschritt speichern? Kostenlos registrieren

Drill 4: Wiederverwenden im Release

release.yml nutzt denselben Build – ohne Cache, wie an Tag 9 entschieden:

cat > .github/workflows/release.yml <<'EOF'
name: release
on:
  push:
    tags: ['v*']

permissions:
  contents: read

jobs:
  build:
    uses: ./.github/workflows/go-build.yml
    with:
      version: ${{ github.ref_name }}
      cache: false

  release:
    needs: build
    runs-on: ubuntu-24.04
    permissions:
      contents: write
    steps:
      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          pattern: notes-api-linux-*
          merge-multiple: true
      - name: Prüfsummen
        run: sha256sum notes-api-linux-* > SHA256SUMS
      - name: Release anlegen
        env:
          GH_TOKEN: ${{ github.token }}
          VORAB: ${{ contains(github.ref_name, '-') }}
        run: >-
          gh release create "$GITHUB_REF_NAME" notes-api-linux-* SHA256SUMS
          --repo "$GITHUB_REPOSITORY" --generate-notes --prerelease="$VORAB"

  deploy:
    needs: release
    if: ${{ !contains(github.ref_name, '-') }}
    runs-on: ubuntu-24.04
    permissions:
      actions: write
    steps:
      - name: Deployment anstoßen
        env:
          GH_TOKEN: ${{ github.token }}
        run: >-
          gh workflow run deploy.yml --repo "$GITHUB_REPOSITORY"
          -f version="${GITHUB_REF_NAME#v}"
EOF
git commit -qam "release: Build aus go-build.yml"
git push -q
git tag v0.6.0-rc.2
git push -q origin v0.6.0-rc.2
  • version: ${{ github.ref_name }} übergibt das Tag mit v; go-build.yml entfernt es.
  • Eine Vorabversion löst kein Deployment aus (if: im Job deploy).

Sobald der Lauf aus gh run list --workflow release.yml --limit 1 fertig ist:

gh release view v0.6.0-rc.2 --json isPrerelease,assets \
  --jq '.isPrerelease, [.assets[].name]'

Erwartet:

true
["notes-api-linux-amd64","notes-api-linux-arm64","SHA256SUMS"]

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

ls .github/actions/go-setup .github/workflows

Erwartet:

.github/actions/go-setup:
action.yml

.github/workflows:
ci.yml
deploy.yml
go-build.yml
gpu.yml
hallo.yml
image.yml
issue.yml
release.yml
vm.yml
grep -c 'uses: ./.github/workflows/go-build.yml' .github/workflows/*.yml

Erwartet:

.github/workflows/ci.yml:1
.github/workflows/deploy.yml:0
.github/workflows/go-build.yml:0
.github/workflows/gpu.yml:0
.github/workflows/hallo.yml:0
.github/workflows/image.yml:0
.github/workflows/issue.yml:0
.github/workflows/release.yml:1
.github/workflows/vm.yml:0

Challenge

Der Job build soll im Aufrufer wissen, welche Artefakte entstanden sind. Gib in smoke den Output artefakte des Reusable Workflows aus.

Hinweis: Outputs eines Reusable Workflows erreichst du wie Job-Outputs: needs.<job>.outputs.<name>.

Lösung

Im Job smoke von ci.yml kommt ein Step dazu (mit dem Editor, vor „Starten und prüfen“). Kein Doppelpunkt hinter „Gebaut“ – sonst ist das YAML ungültig:

      - name: Artefakte
        env:
          ARTEFAKTE: ${{ needs.build.outputs.artefakte }}
        run: echo "Gebaut $ARTEFAKTE"
git commit -qam "ci: Artefaktliste anzeigen"
git push -q

Mit der ID, sobald der Lauf fertig ist:

gh run view <ID> --log | grep 'Z Gebaut '

Erwartet (Zeitstempel gekürzt):

smoke   Artefakte   ... Gebaut notes-api-linux-amd64 notes-api-linux-arm64

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Zentrale Workflows: Plattform-Teams legen Reusable Workflows in ein eigenes Repository (<org>/workflows) und Teams rufen sie mit uses: <org>/workflows/.github/workflows/go-build.yml@<sha> auf. Ein Fix dort erreicht alle.
  • Required Workflows: Rulesets auf Organisationsebene können verlangen, dass ein bestimmter Workflow in jedem Pull-Request grün ist – unabhängig davon, was im Repository steht.
  • SLSA Level 3: Läuft der Build in einem Reusable Workflow aus einem anderen Repository, kann der Aufrufer ihn nicht verändern. job_workflow_ref im OIDC-Token (Tag 10) und in der Provenance zeigt, welcher Workflow wirklich gebaut hat.
  • Grenzen: Reusable Workflows lassen sich bis zu zehn Ebenen tief verschachteln, und ein Workflow ruft höchstens 50 andere auf.