Choose the right reuse boundary

Duplicated YAML across repos is annoying. Copy-pasting security policy across ten repositories is worse. One security fix in ten copies means ten pull requests and one repo always lags behind.

Reuse has three layers. Pick the smallest one that removes real duplication. Jumping straight to a reusable workflow on day one often hides inputs you forgot to define.

Layer 1: project scripts

If the repeated part is npm ci && npm test, put it in package.json:

"scripts": {
  "ci": "npm run lint && npm test && npm run build"
}

The workflow calls npm run ci. Every repo language can do this with Make, Rake, or shell scripts too.

Layer 2: composite actions

Share a sequence of steps inside one repository or org:

# .github/actions/setup-node-app/action.yml
name: Setup Node app
runs:
  using: composite
  steps:
    - uses: actions/setup-node@v4
      with:
        node-version-file: .node-version
        cache: npm
    - run: npm ci
      shell: bash

Use composite actions for repeated setup, not for whole deployment policy.

Layer 3: reusable workflows

When several repositories need the same jobs, permissions, and gates, extract a reusable workflow:

# .github/workflows/deploy-site.yml
on:
  workflow_call:
    inputs:
      environment:
        required: true
        type: string
    secrets:
      CLOUDFLARE_API_TOKEN:
        required: true

jobs:
  deploy:
    environment: ${{ inputs.environment }}
    runs-on: ubuntu-latest
    steps:
      - run: npx wrangler pages deploy dist/

Call it from each repo with explicit inputs and inherited secrets only where required.

Do not abstract too early

One-off YAML does not need a reusable workflow on day one. Extract after the second repo copies the same bug fix.

At every boundary, document inputs, secrets, permissions, and who owns updates. A reusable workflow that inherits secrets: inherit by default can expose production tokens to a repo you did not intend.

Compare two workflows side by side. Count duplicated lines. If the overlap is three setup steps, use a composite action. If the overlap is jobs, permissions, environments, and approval gates, consider a reusable workflow.

Try this on your own project: find two identical step blocks and decide whether a script, composite action, or reusable workflow is the smallest fix.