Reducing CI Duplication with GitHub Actions Reusable Workflows

The Problem: The Same CI File in Every Repository

If you maintain several services, you may have a nearly identical .github/workflows/ci.yml in each one. Updating a Node.js version, adding a dependency scan, or changing a cache key means opening pull requests across every repository. GitHub Actions reusable workflows let you define that logic once and call it from other repositories, so the caller only needs a few lines of YAML.

How Reusable Workflows Operate

A reusable workflow is a standard workflow file that uses the workflow_call trigger. It does not run on push or pull_request by itself. Another workflow invokes it with the uses keyword, and GitHub runs the reusable workflow's jobs as part of the caller's run, with separate logs and status for each job.

Reuse happens at the job level, not the step level. You cannot insert a reusable workflow into the middle of an existing job's steps; it must be its own job in the caller workflow. GitHub also imposes a nesting limit on how many reusable workflows can call other reusable workflows; check current GitHub Actions documentation for the exact depth, as platform limits can change.

Worked Example: Shared Node.js CI

Suppose you have a central repository, org-name/shared-workflows, that holds the shared pipeline. The following is a structural example; verify action versions and syntax against current GitHub documentation before using it in production.

# org-name/shared-workflows/.github/workflows/node-ci.yml
name: Shared Node CI

on:
  workflow_call:
    inputs:
      node-version:
        required: true
        type: string
    secrets:
      API_TOKEN:
        required: false

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout
      - uses: actions/setup-node
        with:
          node-version: ${{ inputs.node-version }}
      - run: npm ci
      - run: npm test
      - name: Integration Test
        if: ${{ secrets.API_TOKEN != '' }}
        run: npm run test:integration
        env:
          TOKEN: ${{ secrets.API_TOKEN }}

The caller repository, org-name/user-api, references the shared workflow by repository, path, and ref. Pinning to a tag or commit SHA prevents an untested change in the shared repository from immediately affecting downstream pipelines.

# org-name/user-api/.github/workflows/ci.yml
name: User API CI

on:
  push:
    branches: [main]

jobs:
  call-shared-ci:
    uses: org-name/shared-workflows/.github/workflows/node-ci.yml@v1.0.0
    with:
      node-version: '20'
    secrets: inherit

secrets: inherit passes the caller's available secrets to the reusable workflow. Secrets are not passed automatically when listed explicitly in the reusable workflow; you must either declare them in the caller's secrets block or use inherit. Organization and repository settings can restrict which secrets are available to workflows, so a secret that exists in the caller may still be unavailable to the called job.

Access, Secrets, and Versioning Risks

Cross-repository reuse requires permission. A reusable workflow in a private or internal repository is not automatically usable by another repository. The owning repository or organization must grant access to the calling repository, depending on your GitHub plan and settings. Public reusable workflows can generally be called by public repositories, but private cross-repo usage often requires explicit access configuration.

Versioning is the main operational risk. If callers reference @main, a breaking change merged into the shared repository can fail every downstream pipeline at once. Treat shared workflows like internal libraries: tag releases, pin callers to specific tags or commit SHAs, and update callers deliberately after testing.

Verify the Result and Roll Back if Needed

1. In the shared repository, create and push a tag: git tag v1.0.0 && git push origin v1.0.0. This requires write or admin permission to create tags. Risk: the tag becomes a reference point immediately; do not push breaking changes to main while callers point to @main.
2. In the caller repository, add the caller workflow above and push to main.
3. Open the Actions tab in the caller repository and trigger the workflow. Confirm that the job from the reusable workflow appears with its own logs and status.
4. If the shared workflow introduces a failure, point the caller back to the previous tag or commit SHA, or delete the problematic tag if you created it by mistake: git tag -d v1.0.0 && git push origin --delete v1.0.0. Deleting a remote tag may be restricted by repository rules.

Reusable workflows reduce duplication, but they centralize risk. Pin versions, manage access explicitly, and verify each caller's run after a shared change.