Reusable Workflows

Eliminate duplication with composite actions, reusable workflows (workflow_call), and shared templates across repositories.

🧒 Simple Explanation (ELI5)

Think of building with LEGO bricks.

• Composite actions are like custom bricks you make yourself. You glue a few small pieces together into one handy brick — now whenever you need that shape, you grab it off the shelf instead of assembling it from scratch every time.
• Reusable workflows are like instruction booklets for complete sub-builds. Instead of writing step-by-step instructions for the same wing or turret in every LEGO set, you create one booklet called "Build the Standard Wing" and just reference it: "See Booklet #7." You can even pass in custom colors (inputs) and get back the finished piece (outputs).
• The .github repository is your org's shared parts bin. Every team in the building can grab bricks and booklets from it — no need to duplicate them in every box.

Instead of building every creation from scratch, you make reusable LEGO bricks (actions) and instruction booklets (reusable workflows) that anyone can use. This is the DRY (Don't Repeat Yourself) principle in action.

🧱 Composite Actions

A composite action bundles multiple steps into a single reusable unit defined in an action.yml file. Think of it as creating your own custom action — like the ones from the marketplace — but tailored to your project's needs.

action.yml Structure

Every composite action requires these top-level keys:

• name — display name of the action
• description — what it does
• inputs — parameters the caller can pass in (each with description, optional default and required)
• outputs — values the action exposes back to the caller
• runs — must set using: composite and list steps

Example: Setup and Lint

# .github/actions/setup-and-lint/action.yml
name: 'Setup and Lint'
description: 'Install dependencies and run linting'
inputs:
  node-version:
    description: 'Node.js version'
    default: '20'
runs:
  using: composite
  steps:
    - uses: actions/setup-node@v4
      with:
        node-version: ${{ inputs.node-version }}
    - run: npm ci
      shell: bash
    - run: npm run lint
      shell: bash

Using the Composite Action

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ./.github/actions/setup-and-lint
        with:
          node-version: '20'

The path ./.github/actions/setup-and-lint points to a directory in your repository containing the action.yml. For actions published to the marketplace or a separate repo, use the full reference: uses: org/action-repo@v1.

Publishing to the Marketplace

1. Create a dedicated repository for the action
2. Ensure action.yml is at the root of the repo
3. Tag a release (e.g., v1.0.0), then create a major version tag (v1) pointing to the same commit
4. Go to the repo's Releases page and check "Publish this Action to the GitHub Marketplace"

🔄 Reusable Workflows (workflow_call)

Reusable workflows let you define an entire workflow (with jobs, steps, environment references) and call it from other workflows. This operates at a higher level than composite actions — you're reusing whole pipelines, not just step bundles.

Trigger: on: workflow_call

A reusable workflow declares itself callable by other workflows using the workflow_call trigger. It defines inputs, secrets, and outputs at the workflow level.

Complete Example — Called Workflow

# .github/workflows/deploy-template.yml
name: Reusable Deploy Workflow

on:
  workflow_call:
    inputs:
      environment:
        required: true
        type: string
      image-tag:
        required: true
        type: string
    secrets:
      AZURE_CREDENTIALS:
        required: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: ${{ inputs.environment }}
    steps:
      - uses: azure/login@v2
        with:
          creds: ${{ secrets.AZURE_CREDENTIALS }}
      - run: |
          az aks get-credentials --resource-group myRG --name myCluster
          helm upgrade --install myapp ./charts \
            --set image.tag=${{ inputs.image-tag }}

Complete Example — Caller Workflow

# .github/workflows/deploy.yml
name: Deploy Pipeline

on:
  push:
    branches: [main]

jobs:
  deploy-staging:
    uses: ./.github/workflows/deploy-template.yml
    with:
      environment: staging
      image-tag: ${{ github.sha }}
    secrets:
      AZURE_CREDENTIALS: ${{ secrets.AZURE_CREDENTIALS }}

  deploy-production:
    needs: deploy-staging
    uses: ./.github/workflows/deploy-template.yml
    with:
      environment: production
      image-tag: ${{ github.sha }}
    secrets:
      AZURE_CREDENTIALS: ${{ secrets.AZURE_CREDENTIALS }}

Outputs from Reusable Workflows

Reusable workflows can expose outputs back to the caller. Define outputs at the workflow level, map them from job outputs, and access them in the caller via needs.<job>.outputs.<name>.

# In the reusable workflow
on:
  workflow_call:
    outputs:
      deploy-url:
        description: 'URL of the deployed app'
        value: ${{ jobs.deploy.outputs.url }}

jobs:
  deploy:
    runs-on: ubuntu-latest
    outputs:
      url: ${{ steps.get-url.outputs.url }}
    steps:
      - id: get-url
        run: echo "url=https://myapp-staging.azurewebsites.net" >> $GITHUB_OUTPUT

Cross-Repo Calls

To call a reusable workflow from another repository, use the full reference:

jobs:
  ci:
    uses: my-org/shared-workflows/.github/workflows/ci.yml@main
    with:
      node-version: '20'
    secrets: inherit

Limitations

• Max 4 levels of nesting — a reusable workflow can call another reusable workflow, up to 4 deep
• No env context from the caller — workflow-level env: variables from the caller are not passed to the reusable workflow. Use inputs instead
• Max 20 reusable workflows per workflow file
• Reusable workflows must be in a .yml or .yaml file in the .github/workflows/ directory
• Private repo workflows are only callable by workflows in the same repository unless you enable sharing in repository settings

📊 Comparison: Composite Actions vs Reusable Workflows vs JavaScript/Docker Actions

🌐 Sharing Across Repositories

The .github Repository

Every GitHub organization can have a special repository named .github. Workflow templates and reusable workflows placed here are available org-wide. This is the recommended pattern for platform teams maintaining standardized CI/CD across many repos.

Pinning Versions

Always pin the version of reusable workflows and actions to prevent unexpected changes from breaking your pipelines:

• Major tag: @v1 — gets patch/minor updates (convenient, slightly less safe)
• Exact tag: @v1.2.0 — deterministic, you control when to upgrade
• Commit SHA: @a1b2c3d4... — most secure, immutable, immune to tag tampering

# Recommended: pin to full SHA for security-critical workflows
uses: my-org/shared-workflows/.github/workflows/ci.yml@8f3e1b2a...

# Acceptable: pin to exact version tag
uses: my-org/shared-workflows/.github/workflows/ci.yml@v1.2.0

# Convenient but less safe: pin to major tag
uses: my-org/shared-workflows/.github/workflows/ci.yml@v1

Internal Visibility for Private Orgs

To share actions or reusable workflows from a private repository, go to the repo's Settings → Actions → General and set "Access" to allow other repositories in the organization. Without this, only workflows in the same repo can reference them.

🗺️ How It All Connects

┌─────────────────────────────────────────────────────────────────────┐
│                       CALLER WORKFLOW                               │
│  deploy.yml                                                         │
│                                                                     │
│  jobs:                                                              │
│    deploy-staging:                                                   │
│      uses: ./.github/workflows/deploy-template.yml ─────────┐      │
│      with:                                                   │      │
│        environment: staging         (inputs)                 │      │
│        image-tag: abc123f           (inputs)                 │      │
│      secrets:                                                │      │
│        AZURE_CREDENTIALS: ***       (secrets)                │      │
│                                                              ▼      │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │                  REUSABLE WORKFLOW                             │  │
│  │  deploy-template.yml                                          │  │
│  │                                                               │  │
│  │  on: workflow_call                                            │  │
│  │    inputs: environment, image-tag  ◀── receives inputs        │  │
│  │    secrets: AZURE_CREDENTIALS      ◀── receives secrets       │  │
│  │    outputs: deploy-url             ──▶ returns outputs        │  │
│  │                                                               │  │
│  │  jobs:                                                        │  │
│  │    deploy:                                                    │  │
│  │      steps:                                                   │  │
│  │        - azure/login@v2                                       │  │
│  │        - helm upgrade --install ...                           │  │
│  └───────────────────────────────────────────────────────────────┘  │
│                                                              │      │
│    deploy-production:                ◀── receives outputs ───┘      │
│      needs: deploy-staging                                          │
│      uses: ./.github/workflows/deploy-template.yml                  │
└─────────────────────────────────────────────────────────────────────┘

🛠️ Hands-on Lab

Lab 1: Create a Composite Action

1. Create .github/actions/setup-node-project/action.yml
2. Define inputs: node-version (default: 20), install-command (default: npm ci)
3. Add steps: checkout (if needed), setup-node, install deps, run lint
4. Reference this action from a workflow and verify it runs successfully

Lab 2: Create a Reusable Workflow

1. Create .github/workflows/build-and-test.yml with on: workflow_call
2. Define inputs: node-version (string), run-e2e (boolean, default false)
3. Add a job that checks out code, installs deps, runs unit tests, and conditionally runs e2e tests
4. Expose an output: test-result (pass/fail)

Lab 3: Call and Chain Reusable Workflows

1. Create a caller workflow that invokes build-and-test.yml with run-e2e: true
2. Add a second job that depends on the first and reads the test-result output
3. If test-result is "pass", proceed to a deploy job; otherwise, skip deployment
4. Pass secrets using both explicit passing and secrets: inherit — observe the difference

🐛 Debugging Common Issues

"Reusable workflow not found"

• Wrong path: Ensure the path is relative to the repo root — ./.github/workflows/ci.yml, not ci.yml
• Wrong ref: For cross-repo calls, the @ref must be a branch, tag, or SHA that exists. @main is common but verify the default branch name
• Visibility: Private repo workflows are not callable from other repos unless explicitly enabled in repository settings under Actions → General → Access
• File location: Reusable workflows must be in .github/workflows/ — not in a subdirectory of it

"Input not available" or Empty Input

• Type mismatch: If the input is declared as type: boolean but you pass a string like 'true', it may not behave as expected. Ensure types match
• Not declared: The input must be declared in the reusable workflow's workflow_call.inputs. Undeclared inputs are silently ignored
• Wrong context: In the called workflow, use ${{ inputs.my-input }}, not ${{ github.event.inputs.my-input }} — that's for workflow_dispatch

"Secret not passed"

• Must explicitly pass: Secrets are not automatically forwarded to reusable workflows. You must either pass each secret explicitly or use secrets: inherit
• Typo in name: Secret names in the caller must exactly match the names declared in the reusable workflow's secrets: definition
• Missing at org/repo level: The secret must exist in the caller's repository or organization — the reusable workflow doesn't have its own secret storage

🎯 Interview Questions

Basic (5)

Intermediate (5)

Senior (5)

🏭 Real-World Scenario

A platform engineering team at a mid-size company maintains 50+ microservices, each with its own repository. Before reusable workflows, every repo had a copy-pasted CI/CD pipeline. When the team needed to add a container security scan, they had to open 50+ pull requests — and inevitably some repos got missed or had slightly different implementations.

Their solution — a central .github repository with three reusable workflows:

• ci.yml — Lint, test, build Docker image, push to ACR (inputs: node-version, image-name, run-e2e)
• deploy.yml — Deploy to AKS with Helm (inputs: environment, image-tag, chart-path)
• security-scan.yml — Trivy image scan + CodeQL analysis (inputs: image-ref, severity-cutoff)

Each microservice's workflow shrank to ~20 lines — just calling the three shared workflows with service-specific inputs. Adding the security scan was a single PR to the central repo. Teams pin to @v2 and upgrade on their own schedule. The platform team publishes changelogs and maintains backward compatibility within major versions.

Result: 95% reduction in pipeline YAML duplication, consistent security posture across all services, and new microservices get production-ready CI/CD by copying a 20-line template instead of a 200-line workflow.

📝 Summary

• Composite actions bundle multiple steps into one reusable action (action.yml with using: composite) — ideal for step-level reuse like setup and linting
• Reusable workflows use on: workflow_call to define sharable pipelines with inputs, secrets, and outputs — ideal for job/pipeline-level standardization
• Caller workflows invoke reusable workflows with uses: at the job level, passing inputs via with: and secrets explicitly or via secrets: inherit
• Reusable workflows support up to 4 levels of nesting and don't inherit the caller's env context
• The .github repository is the recommended place for org-wide shared workflows and actions
• Pin versions with tags (@v1, @v1.2.0) or commit SHAs for security and reproducibility
• Composite actions require explicit shell: in every run step for cross-platform portability
• Choose composite actions for step-level reuse, reusable workflows for pipeline-level standardization, and JavaScript/Docker actions for complex custom logic