Skip to content
Hands-on IT IT Drills

Day 12: Composite Actions and Reusable Workflows

Goal: Move repeated steps into a composite action, build a whole job as a reusable workflow and call it from ci.yml and release.yml. · Duration: approx. 75 min · Prerequisite: Day 11

Briefing

  • ci.yml and release.yml repeat themselves: three times checkout plus setup-go, twice the same build job.
  • A composite action bundles steps. It lives in a folder with action.yml and is called as one step with uses: ./pfad.
  • A reusable workflow bundles jobs. It has the workflow_call trigger, and a job calls it with uses: – instead of runs-on and steps.
  • Rule of thumb: composite for “these three steps always together”, reusable workflow for “this whole process, including its own runner and its own permissions”.
 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: A 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 makes the file a composite action.
  • Every run: step needs shell: here – there is no default as in a workflow.
  • Inputs are always text: default: "true" in quotes.
  • outputs passes a value from an inner step to the outside.
  • No checkout in the action: it lives in the repository, and uses: ./… only finds it once the code is checked out. The checkout stays in the workflow. An action from another repository (uses: <du>/go-setup@v1) is downloaded by the runner itself – it could check out too.

Save your progress? Sign up for free

Drill 2: Using the composite action

In the test job of ci.yml it replaces setup-go. The whole file, with build and smoke unchanged for now:

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

The build job already calls the reusable workflow, which doesn’t exist yet. Without it, ci.yml is invalid – so keep going right away; you push after Drill 3.

Save your progress? Sign up for free

Drill 3: A 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 makes the workflow callable. Inputs have a type here: string, boolean or number.
  • The caller passes them with with:. A job with uses: has no steps and no runs-on – both are in the called workflow.
  • Artifacts that the reusable workflow uploads belong to the caller’s run. That is why smoke finds them as before.
  • ${VERSION#v} removes a leading v: the tag v0.6.0-rc.2 (Drill 4) becomes 0.6.0-rc.2. From ci.yml comes the full commit SHA – expressions cannot shorten strings, and shortening in ci.yml would need a step of its own.

With the ID from gh run list --workflow ci.yml --limit 1, as soon as the run is finished:

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

Expected:

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

build / bauen (amd64): the build job in the caller, inside it the bauen job from go-build.yml, inside that the matrix value.

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

Expected (timestamps shortened, the order may differ):

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

Save your progress? Sign up for free

Drill 4: Reuse in the release

release.yml uses the same build – without a cache, as decided on Day 9:

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 }} passes the tag with v; go-build.yml removes it.
  • A pre-release does not trigger a deployment (if: in the deploy job).

As soon as the run from gh run list --workflow release.yml --limit 1 is finished:

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

Expected:

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

Save your progress? Sign up for free

Checkpoint

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

Expected:

.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

Expected:

.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

The build job should let the caller know which artifacts were created. Print the reusable workflow’s output artefakte in smoke.

Hint: You reach the outputs of a reusable workflow like job outputs: needs.<job>.outputs.<name>.

Solution

In the smoke job of ci.yml, add a step (with the editor, before “Starten und prüfen”). No colon after “Gebaut” – otherwise the YAML is invalid:

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

With the ID, as soon as the run is finished:

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

Expected (timestamp shortened):

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

Save your progress? Sign up for free

Enterprise Note

  • Central workflows: Platform teams put reusable workflows into a repository of their own (<org>/workflows), and teams call them with uses: <org>/workflows/.github/workflows/go-build.yml@<sha>. A fix there reaches everyone.
  • Required workflows: Rulesets at the organization level can require that a specific workflow is green in every pull request – regardless of what is in the repository.
  • SLSA Level 3: If the build runs in a reusable workflow from another repository, the caller cannot change it. job_workflow_ref in the OIDC token (Day 10) and in the provenance shows which workflow really did the build.
  • Limits: Reusable workflows can be nested up to ten levels deep, and a workflow calls at most 50 others.