Sharing CI/CD Logic with GitHub Actions Reusable Workflows

Why use reusable workflows

Reusable workflows let you define a set of jobs once and call them from many repositories, reducing duplication and keeping CI/CD practices consistent.

Example reusable workflow

Create .github/workflows/reusable.yml in the source repository:

name: Reusable CI
on:
  workflow_call:
    inputs:
      build-tool:
        description: 'Tool to show version'
        required: true
        type: string
    secrets:
      npm-token:
        required: true
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Install dependencies
        run: npm ci
        env:
          NPM_TOKEN: ${{ secrets.npm-token }}
      - name: Show tool version
        run: ${{ inputs.build-tool }} --version

Caller workflow

In any other repository reference the reusable workflow:

name: Caller CI
on:
  push:
    branches: [ main ]
jobs:
  use-reusable:
    uses: owner/repo/.github/workflows/reusable.yml@v1
    with:
      build-tool: 'npm'
    secrets:
      npm-token: ${{ secrets.NPM_TOKEN }}

Limits

• Reusable workflows cannot access the caller’s repository secrets unless they are explicitly listed in the secrets: block.
• They run with the caller’s GITHUB_TOKEN and inherit its permissions.
• Nesting depth is capped at four levels.
• A single workflow run may invoke at most twenty reusable workflows.

Common mistakes

• Omitting the workflow_call trigger – the workflow will not be callable.
• Declaring an input or secret as required but forgetting to pass it from the caller.
• Using a relative path like ./.github/workflows/reusable.yml instead of the full owner/repo/.github/workflows/file@ref syntax.
• Assuming the reusable workflow can push to protected branches without granting contents: write permission on the caller’s token.