Reusable workflows

A reusable workflow is a workflow file with an on: workflow_call trigger that other workflows call as a job, with jobs.<id>.uses. Use one to keep a build, test or deploy pipeline in one place and call it from many workflows or repositories. Diffinery implements GitHub's syntax and behaviour; the differences are listed in Differences from GitHub.

#A minimal example

The called workflow declares its inputs, secrets and outputs under on.workflow_call:

# .github/workflows/build.yml
name: Build
on:
  workflow_call:
    inputs:
      node-version:
        type: string
        default: "22"
      run-e2e:
        type: boolean
        default: false
    secrets:
      NPM_TOKEN:
        required: true
    outputs:
      version:
        description: The version that was built
        value: ${{ jobs.build.outputs.version }}

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      version: ${{ steps.meta.outputs.version }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
      - run: npm ci
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
      - id: meta
        run: echo "version=$(node -p 'require(\"./package.json\").version')" >> "$GITHUB_OUTPUT"
      - if: ${{ inputs.run-e2e }}
        run: npm run test:e2e

The caller uses it as a job:

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

jobs:
  build:
    uses: ./.github/workflows/build.yml
    with:
      run-e2e: true
    secrets:
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

  report:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - run: echo "Built version ${{ needs.build.outputs.version }}"

#Calling a workflow

A calling job has uses instead of runs-on and steps. It accepts these keys:

Any other key produces a warning (unknown reusable-workflow job key '...') and is ignored. That includes environment: as on GitHub, a calling job can't use an environment, so put environment: on the jobs inside the called workflow (see Environments in called workflows). steps or runs-on on a calling job is an error.

#Local workflows

uses: ./.github/workflows/build.yml

The path starts with ./, is relative to the repository root, names a file in .github/workflows/ or .diffinery/workflows/ and ends in .yml or .yaml. The file is read from the same commit as the calling workflow, so a branch or pull request can change both together. Workflows under .diffinery/workflows/ can be called the same way (./.diffinery/workflows/build.yml).

#Workflows in other repositories

uses: acme/shared-workflows/.github/workflows/deploy.yml@v2

The format is <owner>/<repo>/<path>@<ref>, where <ref> is a branch, a tag or a commit SHA, and the repository is on the same Diffinery instance (here, diffinery.com). A workflow on github.com can't be called; copy it into a Diffinery repository first.

Which repositories you can call:

Access is decided by the two repositories' owners, not by who pushed the commit. A call that isn't allowed fails with repository acme/shared-workflows not found, or its workflows are not shared with acme/website.

Inside a workflow called from another repository, a local ./ reference resolves in that other repository, at the commit the called workflow came from.

A branch or tag <ref> is resolved once, when the run is planned: every job of the run, including one that waits for an environment's approval, uses the called workflow from that commit, even if the branch moves during the run.

#Inputs

Declare inputs under on.workflow_call.inputs. Each input must have a type:

The caller passes values with with. Rules:

• Every key in with must be a declared input. An unknown key fails the run with jobs.<id>.with.<key>: <uses> has no input named '<key>'.
• with values can use expressions with the github, needs (the calling job's needs), inputs (when the caller is itself inside a reusable workflow) and vars contexts.
• Values are converted to the declared type: a boolean input is true for true or "true"; a number input goes through Number().
• A missing optional input with no default is "", false or 0 depending on its type.
• A missing required input fails the jobs inside the call with jobs.<id>: input '<name>' is required by <uses>.

Inside the called workflow, read inputs with ${{ inputs.<name> }}.

#Secrets

The called workflow only sees the secrets the caller passes, plus GITHUB_TOKEN, which is always the job's own token, plus, in a job with environment:, that environment's secrets (see Environments in called workflows).

Pass specific secrets with a mapping. Each value is an expression evaluated against the caller's secrets:

secrets:
  DEPLOY_KEY: ${{ secrets.PROD_DEPLOY_KEY }}
  NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

Or pass everything the caller has with inherit:

secrets: inherit

At the top level, "everything the caller has" is the calling repository's secrets plus its organization's secrets. In a nested call, it's whatever the enclosing call received.

Declare the secrets a workflow needs under on.workflow_call.secrets. A secret declared with required: true that the caller doesn't provide fails the jobs inside the call with jobs.<id>: secret '<NAME>' is required by <uses>. Secret names are case-insensitive and are stored uppercase.

Secrets for a cross-repository call always come from the calling repository and its organization, never from the repository that holds the workflow.

#Outputs

A called workflow exposes results through on.workflow_call.outputs. Each output has a value, an expression that can read the jobs context of the called workflow (jobs.<job id>.outputs.<name> and jobs.<job id>.result) and its inputs:

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

The caller reads it as ${{ needs.<calling job id>.outputs.image }}. Values are strings; objects are JSON-encoded. Only declared outputs are visible to the caller.

needs.<calling job id>.result summarizes the jobs inside the call: failure if any failed or timed out, otherwise cancelled if any was cancelled, skipped if all were skipped, and success otherwise.

#Contexts inside a called workflow

Because github.repository is the caller's, actions/checkout with no inputs checks out the calling repository, as on GitHub. To check out the repository that holds the workflow, pass repository:. The job's GITHUB_TOKEN can read that repository when it's public; when it's private, also pass a token: from a secret.

#Permissions in called workflows

The jobs inside a call get their GITHUB_TOKEN permissions like this, as on GitHub:

1. Start from the calling job's effective permissions: its own permissions:, or else the calling workflow's, or else the repository default.
2. If the called workflow or the called job declares permissions:, use that instead, but lowered scope by scope to what the calling job has. A called workflow can never get more than its caller.
3. If neither declares anything, the called jobs get exactly the calling job's permissions.

# .github/workflows/release.yml in acme/website
jobs:
  deploy:
    permissions:
      contents: read
      id-token: write
    uses: ./.github/workflows/deploy.yml

Here the jobs in deploy.yml can have at most contents: read and id-token: write. If deploy.yml declares permissions: write-all, its jobs still get only those two. If it declares packages: write, its jobs get no packages access, because the calling job has none. This applies to id-token for OIDC, to packages for the container registry, and to every other scope. See GITHUB_TOKEN permissions.

#Environments in called workflows

A job inside a called workflow can deploy to an environment with environment:, and the environment's name and url can use the called workflow's inputs:

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: ${{ inputs.environment }}
      url: https://${{ inputs.environment }}.example.com
    steps:
      - run: ./deploy.sh

How it works:

• The environment belongs to the calling repository, the one whose run it is, even when the workflow file lives in another repository. Its branch policy is checked against the caller's ref.
• The job gets the environment's secrets and variables without the caller passing them in secrets:, as on GitHub. An environment secret replaces a passed secret with the same name.
• A secret declared with required: true under on.workflow_call.secrets must still be passed by the caller, even if the environment has it. Don't declare secrets that come from the environment.
• The job records a deployment like any other job with environment:, and the usual rules for who receives environment secrets apply (pull request refs never do; runs whose code came from an agent only from environments set to protected branches only).

#How calls appear in runs and checks

The called workflow's jobs become jobs of the caller's run. A calling job build that calls a workflow with jobs compile and test produces the jobs build / compile and build / test (the calling job's name, if it has one, replaces build). Checks on the commit are named <workflow name> / <calling job> / <job>.

Ordering follows GitHub:

• Jobs inside the call that have no needs wait for the calling job's needs.
• A job that needs the calling job waits for every job inside the call.
• If the calling job's if is false, or (with the default if) any job it depends on, directly or through other jobs, failed or was skipped, every job inside the call is reported as skipped.

#Nesting

A called workflow can itself call reusable workflows, up to four levels below the top-level workflow, as on GitHub. A fifth level fails the run with:

jobs.a/b/c/d/e: reusable workflows can be nested at most 4 levels deep

A run can call at most 20 reusable workflows in total (counting every call at every level); more fails with a run can call at most 20 reusable workflows.

#Matrix on the calling job

A strategy.matrix on a job that calls a reusable workflow isn't supported yet. The run fails with:

jobs.deploy: a matrix on a job that calls a reusable workflow is not supported yet

Put the matrix on the jobs inside the called workflow instead, passing the list as an input:

# caller
jobs:
  test:
    uses: ./.github/workflows/test.yml
    with:
      versions: '["20", "22"]'

# .github/workflows/test.yml
on:
  workflow_call:
    inputs:
      versions:
        type: string
        required: true
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node: ${{ fromJSON(inputs.versions) }}
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
      - run: node --version

Or write one calling job per value.

#Example: a shared deploy pipeline

An organization keeps its deploy workflow in acme/shared-workflows (private) and calls it from acme/website (same owner, so allowed):

# acme/shared-workflows: .github/workflows/deploy.yml
name: Deploy
on:
  workflow_call:
    inputs:
      environment:
        type: string
        required: true
      dry-run:
        type: boolean
        default: false
    secrets:
      CLOUDFLARE_API_TOKEN:
        required: true
    outputs:
      url:
        value: ${{ jobs.deploy.outputs.url }}

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: ${{ inputs.environment }}   # acme/website's staging or production environment
    outputs:
      url: ${{ steps.deploy.outputs.url }}
    steps:
      - uses: actions/checkout@v4          # checks out acme/website, the caller
      - run: npm ci && npm run build
      - id: deploy
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
        run: |
          if [ "${{ inputs.dry-run }}" = "true" ]; then
            npx wrangler deploy --dry-run
          else
            npx wrangler deploy --env "${{ inputs.environment }}"
          fi
          echo "url=https://${{ inputs.environment }}.example.com" >> "$GITHUB_OUTPUT"

# acme/website: .github/workflows/release.yml
name: Release
on:
  push:
    branches: [main]

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

  staging:
    needs: test
    uses: acme/shared-workflows/.github/workflows/deploy.yml@v2
    with:
      environment: staging
    secrets: inherit

  production:
    needs: staging
    uses: acme/shared-workflows/.github/workflows/deploy.yml@v2
    with:
      environment: production
    secrets:
      CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}

  announce:
    needs: production
    runs-on: ubuntu-latest
    steps:
      - run: echo "Live at ${{ needs.production.outputs.url }}"

The deploy job uses acme/website's staging and production environments, so each call is checked against that environment's branch policy and records a deployment there. If those environments have their own CLOUDFLARE_API_TOKEN secret, it replaces the one the caller passes.

#Differences from GitHub

#Errors

Errors in the calling workflow's syntax make the workflow file invalid. On push, Diffinery records a failed run titled "Invalid workflow file: ..."; the workflow list in the API reports it as invalid.

Errors found while loading the called workflows fail the run before any job starts. The run shows one failed job, Set up workflow, with the message:

Errors in the values passed fail the jobs inside the call when they're about to start:

For the full workflow syntax, see Workflow syntax. For expressions, see Expressions and contexts.