# GitHub Actions Reusable Workflows: DRY Pipelines at Org Scale

URL: https://www.devopsness.com/blog/github-actions-reusable-workflows-org-scale
Author: Kiril Urbonas
Published: 2026-07-05
Updated: 2026-10-31
Categories: DevOps
Tags: GitHub Actions, CI/CD, Automation, DevOps, Workflows

Summary: When the same build workflow is copy-pasted into 60 repos, one bug fix means 60 PRs. Here's the reusable-workflow setup that makes it one.

---
# GitHub Actions Reusable Workflows: DRY Pipelines at Org Scale

To stop copy-pasting CI across repos, move the shared jobs into one central repo as a workflow with `on: workflow_call`, then call it from each service with a job-level `uses: org/ci/.github/workflows/build.yml@v3`. One commit to the central repo then fixes every caller. Pin third-party actions inside it to full SHAs.

> [!VERIFIED]
> GitHub Actions (github.com), actions/checkout v7.0.1, aquasecurity/trivy-action v0.36.0, against the docs.github.com reusable-workflow how-to, the workflow reference and the secure-use reference. Checked October 2026.

The usual trigger is a CVE in a build action copy-pasted across 60 repositories: 60 pull requests, 60 reviews, and a find-and-replace that breaks wherever a copy drifted. With a reusable workflow it is one commit.

## Composite action or reusable workflow: pick by scope

People mix these up. A composite action bundles a few steps you call inside a job. A reusable workflow is one or more whole jobs, called with `uses:` at the job level, never from inside a step. For "every service builds, tests, scans and pushes an image the same way", you want a reusable workflow, because you are standardizing jobs, runners and permissions, not a step or two.

The reusable workflow lives in a central repo, here `devopsness/ci`:

```yaml
# .github/workflows/build-and-push.yml (in devopsness/ci)
name: build-and-push
on:
  workflow_call:
    inputs:
      image-name:
        required: true
        type: string
      dockerfile:
        required: false
        type: string
        default: Dockerfile
    secrets:
      registry-token:
        required: true
    outputs:
      image:
        description: Fully qualified image reference that was pushed
        value: ${{ jobs.build.outputs.image }}

permissions:
  contents: read

jobs:
  build:
    runs-on: ubuntu-24.04
    outputs:
      image: ${{ steps.meta.outputs.image }}
    steps:
      - uses: actions/checkout@v7 # pin to the v7.0.1 commit SHA in production
      - id: meta
        run: echo "image=${{ inputs.image-name }}" >> "$GITHUB_OUTPUT"
      - name: Build image
        run: docker build -f "${{ inputs.dockerfile }}" -t "${{ inputs.image-name }}" .
      - name: Scan with Trivy
        uses: aquasecurity/trivy-action@v0.36.0 # pin to the release commit SHA in production
        with:
          image-ref: ${{ inputs.image-name }}
          exit-code: '1'
          severity: 'CRITICAL,HIGH'
      - name: Push
        env:
          REGISTRY_TOKEN: ${{ secrets.registry-token }}
        run: |
          echo "$REGISTRY_TOKEN" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin
          docker push "${{ inputs.image-name }}"
```

Two details matter. The `outputs` block maps a job output to a workflow output, the only way to hand values back, because `env` does not cross the call boundary in either direction. And passing the secret through `env` instead of interpolating it into the shell line keeps it out of the rendered script.

## The caller shrinks to a dozen lines

Each service repo keeps a tiny workflow that calls the shared one. None of these lines contain logic that can drift:

```yaml
# .github/workflows/ci.yml (in payments-service)
name: CI
on:
  push:
    branches: [main]
  pull_request:

concurrency:
  group: ci-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  build:
    uses: devopsness/ci/.github/workflows/build-and-push.yml@v3
    permissions:
      contents: read
      packages: write
    with:
      image-name: ghcr.io/devopsness/payments:${{ github.sha }}
    secrets:
      registry-token: ${{ secrets.GITHUB_TOKEN }}

  report:
    needs: build
    runs-on: ubuntu-24.04
    steps:
      - run: echo "Pushed ${{ needs.build.outputs.image }}"
```

Permissions flow one way: the docs say the called workflow can only downgrade the `GITHUB_TOKEN` permissions the caller passes, never elevate them. If the caller's job omits `permissions`, the called workflow gets the repo's default token permissions. Callers in the same org or enterprise can use `secrets: inherit` instead of mapping each secret, but inherited secrets reach only the directly called workflow, not workflows it calls in turn.

## Versioning: moving tag for your code, SHA for theirs

There is a real tension. A ref like `@v3` (a tag you re-point as you release fixes) gives central control: move the tag and every caller updates on its next run. A commit SHA gives immutability, and GitHub's docs call it "the safest option for stability and security", but it brings back the 60-PR problem because each caller must be bumped.

We recommend a hybrid. Internal reusable workflows are pinned to a major tag we own and advance only for backward-compatible changes, so security fixes flow automatically. Third-party actions inside the reusable workflow are pinned to full SHAs, because the secure-use reference warns that a tag "can be moved or deleted if a bad actor gains access" to the action's repo. Central logic: moving tag. External code: frozen SHA. Repos that adopt [GitHub Actions workflow lockfiles](/blog/github-actions-workflow-lockfiles) get the same freeze without hand-maintained SHAs, and the docs say lockfiles supersede SHA pinning where adopted.

Cut releases like this:

```
$ git tag -a v3.4.0 -m "build-and-push: add SBOM step"
$ git push origin v3.4.0
$ git tag -f v3 v3.4.0 && git push -f origin v3
```

One trap: if a branch and a tag share a name, the tag wins. Never create a `v3` branch.

## Guardrails so one bad commit doesn't break 60 repos

The flip side of one-commit-updates-everything is one-commit-breaks-everything. Three controls:

1. **Test the central repo.** A workflow in `devopsness/ci` calls `./.github/workflows/build-and-push.yml` against a sample service on every PR, so a broken change fails before merge.
2. **Canary the tag move.** Five repos track `@v3-canary`. Advance that first, watch a day of runs, then move `@v3`.
3. **Lock down who may call what.** In org settings under Actions, allow only your own org's actions and reusable workflows plus a vetted list. For a private central repo, the docs require its Actions **Access** policy to be explicitly set to allow the calling repos.

Concurrency surprised us more than anything else. Reusable workflows bill and queue like inlined jobs, and once dozens of repos share identical push triggers they saturate runner concurrency together. The `concurrency` block in the caller above cancels superseded runs on the same ref. For broader token and runner hardening, see [GitHub Actions security hardening](/blog/github-actions-security-hardening).

## Failure modes and the errors you'll see

- **`workflow was not found`** or the run fails at startup: the ref does not exist, the path is wrong (it must be under `.github/workflows/`), or the private central repo's Access policy does not include the caller. Check the tag exists with `git ls-remote --tags origin v3`.
- **`Invalid secret, registry-token is not defined in the referenced workflow`**: the caller passes a secret the callee does not declare under `on.workflow_call.secrets`. Declare it, or use `secrets: inherit`.
- **`Input image-name is required, but not provided while calling`**: a required input is missing from the caller's `with:` block.
- **Permission denied pushing to GHCR inside the called workflow**: the caller did not grant `packages: write`. The callee cannot raise it.
- **Values set with `GITHUB_ENV` vanish in the caller**: by design. Use job outputs mapped to `on.workflow_call.outputs`.
- **A re-run picks up different code than the first attempt**: with a tag or branch ref, "re-run all jobs" uses whatever the ref points at now, while re-running failed jobs uses the SHA from the first attempt.

## Where this breaks

Reusable workflows are a poor fit when services genuinely differ: if half your callers pass ten feature-flag inputs to skip steps, you have built a configuration language in YAML, and two or three smaller workflows are clearer. The documented hard limits also bite in deep designs: at most ten levels of nesting, and at most 50 unique reusable workflows from a single workflow file, counting nested calls. GitHub Enterprise Server versions lag github.com features, so check your server's docs before copying syntax.

## Questions people ask

### What is the difference between a reusable workflow and a composite action?

A composite action is a bundle of steps that runs inside a job you already defined, on that job's runner. A reusable workflow is a set of complete jobs, triggered by `workflow_call` and invoked with `uses:` at the job level. Use composite actions to share a few steps, and reusable workflows to standardize whole jobs, including runners, permissions and secrets.

### Can a reusable workflow live in a private repository?

Yes. Reference it as `owner/repo/.github/workflows/file.yml@ref`. For a private repo, GitHub requires the Access policy on that repo's Actions settings page to explicitly allow access from the repositories containing the caller workflows. Every workflow in a nested chain must also be accessible to the original caller, or the run fails.

### Should I pin reusable workflows to a tag or a commit SHA?

GitHub calls the SHA the safest option. For third-party workflows and actions, follow that. For your own org's workflows, a major tag you control (`@v3`) is a reasonable trade: you move it for compatible fixes and every caller picks them up. Protect the central repo's tags and canary each move.

### Do environment variables pass into a reusable workflow?

No. Workflow-level `env` in the caller is not propagated to the called workflow, and `env` set in the called workflow does not come back. Pass values in as `inputs`, return them through workflow `outputs`, and use the `vars` context for configuration shared across workflows.

## The call we'd make

If more than about ten repos share pipeline logic, move it into reusable workflows in a central repo now. The copy-paste model looks harmless until one CVE turns into sixty PRs. Pin your own reusable workflows to a moving major tag, pin third-party actions to SHAs or a lockfile, test the central repo against a sample service, canary every tag move, and grant permissions in the caller. If you are still writing your first pipeline, start with [a first CI/CD pipeline in GitHub Actions](/blog/first-cicd-pipeline-github-actions-tutorial) and extract the shared job once a second repo needs it.

## Sources

- [GitHub Docs: Reuse workflows](https://docs.github.com/en/actions/how-tos/reuse-automations/reuse-workflows)
- [GitHub Docs: Reusable workflow configuration reference (limits, env, permissions)](https://docs.github.com/en/actions/reference/workflows-and-actions/reusing-workflow-configurations)
- [GitHub Docs: Secure use reference (pinning actions and workflows)](https://docs.github.com/en/actions/reference/security/secure-use)
- [actions/checkout releases](https://github.com/actions/checkout/releases)

