GitHub Actions Tutorial — workflow_call

1 minute read

workflow_call

The workflow_call trigger turns a regular workflow file into a reusable workflow. Any other workflow can call it using uses: in a job definition — like calling a function.

Basic Reusable Workflow

.github/workflows/build.yml (the reusable workflow):


name: Build

on:
  workflow_call:                 # makes this workflow callable

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

.github/workflows/ci.yml (the caller):


name: CI

on:
  push:
    branches: [main]

jobs:
  build:
    uses: ./.github/workflows/build.yml    # call the reusable workflow

How It Works

Caller workflow (ci.yml)
│
├── Triggers on: push to main
│
└── Job: build
    └── uses: ./.github/workflows/build.yml
        │
        └── Reusable workflow (build.yml)
            └── on: workflow_call
            └── Job: build
                ├── checkout
                ├── npm ci
                └── npm run build

The reusable workflow’s jobs run as if they were defined in the caller. The caller job essentially delegates to the reusable workflow.

Reusable Workflow Rules

Rule Detail
Trigger Must include on: workflow_call
Location Must be in .github/workflows/ directory
Nesting Can call other reusable workflows (max 4 levels deep)
Caller syntax uses: at the job level (not step level)
Concurrency Inherits the caller’s concurrency settings

workflow_call vs Other Triggers

A reusable workflow can have multiple triggers:


on:
  workflow_call:                 # callable by other workflows
  push:                         # also runs on push
    branches: [main]

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

This workflow runs both when called by another workflow AND on direct pushes to main.

Calling Cross-Repository Workflows

Call a reusable workflow from another repository:


jobs:
  build:
    uses: my-org/shared-workflows/.github/workflows/build.yml@main
    #      └── owner/repo          └── path                   └── ref
Ref Type Example Notes
Branch @main Always latest; may break
Tag @v1 Recommended for stability
SHA @abc123def456... Most secure and reproducible

Common Mistakes

Mistake Fix
Missing workflow_call trigger The reusable workflow must have on: workflow_call
uses: at step level Reusable workflows are called at the job level, not step level
Workflow not in .github/workflows/ Must be in the correct directory
Nesting too deep Max 4 levels of nested reusable workflow calls

Quick Reference

Concept Syntax
Make reusable on: workflow_call
Call (same repo) uses: ./.github/workflows/file.yml
Call (cross-repo) uses: owner/repo/.github/workflows/file.yml@ref
Max nesting 4 levels
Multiple triggers workflow_call + push, pull_request, etc.

← Back to: Chapter 10: Reusable Workflows

Next: Inputs, Outputs, Secrets →

Updated:

You may also enjoy