workflow

`uses: <workflow_call>`

Reusable workflows are files that declare `on: workflow_call` and can be invoked as a job in another workflow. The caller passes typed `with:` inputs and either inherits or explicitly forwards secrets.

Syntax

jobs:
  <id>:
    uses: <owner>/<repo>/.github/workflows/<file>.yml@<ref>
    with: {...}
    secrets: inherit | {...}

Common values / subkeys

Value / Subkey	Purpose
on.workflow_call.inputs	Callee: declare typed inputs (string/boolean/number)
on.workflow_call.secrets	Callee: declare named secrets
on.workflow_call.outputs	Callee: expose outputs to the caller job
secrets: inherit	Caller: forward every secret automatically
with	Caller: pass values for declared inputs

Examples

# .github/workflows/reusable.yml
on:
  workflow_call:
    inputs:
      env: {type: string, required: true}
    secrets:
      DEPLOY_KEY: {required: true}

Callee declaration

jobs:
  deploy:
    uses: ./.github/workflows/reusable.yml
    with: {env: prod}
    secrets: inherit

Same-repo call, forwarding secrets

jobs:
  deploy:
    uses: acme/shared/.github/workflows/deploy.yml@v1
    with: {env: prod}
    secrets:
      DEPLOY_KEY: ${{ secrets.PROD_KEY }}

Cross-repo call with an explicit secret map

on:
  workflow_call:
    outputs:
      image:
        value: ${{ jobs.build.outputs.image }}

Expose an output to callers

Gotcha

Reusable workflows cannot chain more than 4 levels deep and a caller cannot invoke more than 20 reusable workflows; `secrets: inherit` is opt-in — omit it and the callee sees no secrets.

Related keywords

uses:

Runs a published action inside a step. The reference should include an immutable commit SHA or a version tag; inputs are passed via the `with:` block.

${{ secrets.NAME }}

The `secrets` context exposes repository, environment, and organization secrets to workflow expressions. Values are masked in logs and are not passed to workflows triggered from forked PRs.

${{ vars.* }} / ${{ inputs.* }}

`vars` exposes non-secret configuration variables defined at the repository, environment, or organization level. `inputs` exposes typed parameters passed to `workflow_dispatch`, `workflow_call`, or composite actions.

on:

Declares the events that trigger the workflow. Accepts a single event, a list, or a map with per-event filters (branches, paths, tags, types).

permissions:

Controls the scopes granted to the automatically generated GITHUB_TOKEN. Can be set at the workflow or job level; the job-level block overrides the workflow default.

← All GitHub Actions syntax · Git commands · Cron syntax