Reusable Workflows with workflow_call

Reusable Workflows

Reusable workflows let you define a workflow once and call it from multiple other workflows — reducing duplication across repositories and teams. They use the workflow_call trigger.

Reusable Workflow (callee)

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

on:
  workflow_call:
    inputs:
      environment:
        required: true
        type: string
      app-name:
        required: true
        type: string
    secrets:
      deploy-token:
        required: true
    outputs:
      deploy-url:
        description: "Deployment URL"
        value: ${{ jobs.deploy.outputs.url }}

jobs:
  deploy:
    runs-on: ubuntu-latest
    outputs:
      url: ${{ steps.deploy.outputs.url }}
    environment: ${{ inputs.environment }}
    steps:
      - uses: actions/checkout@v4

      - name: Deploy
        id: deploy
        run: |
          echo "Deploying ${{ inputs.app-name }} to ${{ inputs.environment }}"
          echo "url=https://${{ inputs.app-name }}.${{ inputs.environment }}.example.com" >> $GITHUB_OUTPUT
        env:
          TOKEN: ${{ secrets.deploy-token }}

Caller Workflow

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run build

  deploy-staging:
    needs: build
    uses: ./.github/workflows/deploy-template.yml
    with:
      environment: staging
      app-name: my-app
    secrets:
      deploy-token: ${{ secrets.DEPLOY_TOKEN }}

  deploy-production:
    needs: deploy-staging
    uses: ./.github/workflows/deploy-template.yml
    with:
      environment: production
      app-name: my-app
    secrets:
      deploy-token: ${{ secrets.DEPLOY_TOKEN }}

Key Concepts

• Inputs: Typed parameters (string, number, boolean) passed from caller to callee
• Secrets: Sensitive values passed explicitly (not automatically inherited unless using secrets: inherit)
• Outputs: Values returned from the reusable workflow to the caller
• Cross-repo: Reference workflows in other repositories: uses: org/repo/.github/workflows/template.yml@main

Limitations

• Maximum 4 levels of nesting (workflow calls workflow calls workflow...)
• Reusable workflows must be in the .github/workflows/ directory
• Caller cannot pass environment variables — use inputs instead
• The called workflow runs in the context of the caller's repository