Opscraft
GitHub Actions · Lesson 4 of 10 · 3 min read

Reuse at scale: actions and reusable workflows

Kinds of actions

Type Runs Good for
JavaScript Node on the runner Fast, cross-platform logic (most official actions)
Docker A container (Linux runners only) Tools packaged with dependencies
Composite A sequence of steps (using: composite) Bundling repeated steps across repos

A composite action (.github/actions/setup-build/action.yml or its own repo):

name: setup-build
inputs:
  java-version: { default: "21" }
runs:
  using: composite
  steps:
    - uses: actions/setup-java@v4
      with: { distribution: temurin, java-version: "${{ inputs.java-version }}", cache: gradle }
    - shell: bash
      run: ./gradlew --version

Reusable workflows

A whole workflow called by others — the GitHub equivalent of a Jenkins shared library pipeline:

# acme/platform-workflows/.github/workflows/service-ci.yml
on:
  workflow_call:
    inputs:
      service:   { type: string, required: true }
      java:      { type: string, default: "21" }
    secrets:
      SONAR_TOKEN: { required: false }
    outputs:
      image: { value: "${{ jobs.build.outputs.image }}" }
jobs:
  build:
    runs-on: ubuntu-latest
    outputs: { image: "${{ steps.img.outputs.image }}" }
    steps:
      - uses: actions/checkout@v4
      - id: img
        run: echo "image=${{ inputs.service }}:${GITHUB_SHA::7}" >> "$GITHUB_OUTPUT"
# in each service repo
jobs:
  ci:
    uses: acme/platform-workflows/.github/workflows/service-ci.yml@v3
    with: { service: orders }
    secrets: inherit

Composite action vs reusable workflow: a composite action is a group of steps inside your job; a reusable workflow is one or more whole jobs with their own runners, environments and permissions. Reusable workflows can nest (up to 10 levels in current limits) and are versioned by ref.

Enlarge diagramComposite actionReusable workflowA list of steps used inside your jobRuns on the caller's runnerCannot define jobs or environmentsGood for: setup, build, scanWhole jobs, called with uses: at job levelOwn runners, environments, secretsPlatform team owns the pipelineGood for: a standard deploy pipeline
Figure 1. Two ways to share CI across repositories. Composite actions bundle steps; reusable workflows bundle whole jobs.
Swipe sideways to see all of it, or tap to open it full screen.

Versioning and pinning

  • Reference actions by a full commit SHA (actions/checkout@<40-char-sha> # v4.2.2) for immutability — tags can be moved by the action's owner (or an attacker who compromises it). Dependabot/Renovate keep SHAs updated.
  • Publish your own workflows/actions with semantic version tags (v3, v3.2.0) and a changelog.
  • Organisation policies can restrict which actions are allowed (GitHub-owned, verified creators, an allow-list).
Enlarge diagramuses: some/action@v4uses: some/action@<40-char SHA>v4 is a movable tagA compromised maintainer can repoint itYour secrets go to whatever runsImmutable: exactly the code you reviewedComment the version beside itDependabot or Renovate bumps it
Figure 2. A tag can be moved to different code by whoever controls the action. A commit SHA cannot.
Swipe sideways to see all of it, or tap to open it full screen.