GitHub Actions Workflow Templates, Reusable Workflows and Composite Actions (GH-200)

GitHub Actions gives you three ways to share automation, and the difference is what gets shared and whether it stays linked to the source. A workflow template (formerly called a starter workflow) is copied into a repository once and is then independent. A reusable workflow is a central workflow file with an on: workflow_call trigger that other workflows call from a job, so every caller runs the current version of the ref it names. A composite action is a central bundle of steps that a job runs as one step, on its own runner.

Choose by the requirement, not by the name. If teams need a starting point they will then change freely, use a template. If many repositories must pick up a fix to a whole pipeline without anyone editing them, or the shared work must run on a different runner from the team's own jobs, use a reusable workflow. If the shared logic must run inside an existing job, on files that earlier steps produced, without uploading artifacts, use a composite action.

You use a workflow template from the repository's Actions tab: choose New workflow, pick a template, select Configure, edit the YAML in the editor and commit it. GitHub suggests public templates (maintained in the actions/starter-workflows repository) that fit the repository's languages and files, and lists templates your organization has published in their own section.

The result is an ordinary workflow file committed to .github/workflows in your repository. From that moment it is yours:

• Customise the copy, not the template. To change one repository (a different Node.js version, an extra job), edit the workflow file in that repository. Editing the template in the organization's .github repository would change it for future copies only, and other teams' choices would be overridden next time they create from it.
• Template changes never propagate. If the platform team later adds a step to the template, existing workflows created from it stay exactly as they were until someone edits them. Nothing is disabled or re-generated.
• There is no link to call. A template has no inputs, no with: and no version reference — you cannot pass values to it from a job.

That independence is why templates suit scaffolding (a recommended CI layout teams adapt) and are the wrong tool when every repository must stay on the same, centrally fixed pipeline.

An organization publishes its own workflow templates by committing them to the workflow-templates directory of the organization's .github repository. Each template needs two files with the same base name:

• workflow-templates/<name>.yml — the workflow itself.
• workflow-templates/<name>.properties.json — its metadata. Without this file the template is not offered under New workflow, even when the YAML is valid.

{
  "name": "Octo Org Node.js CI",
  "description": "Build and test a Node.js project.",
  "iconName": "octicon package",
  "categories": ["JavaScript", "Node"],
  "filePatterns": ["package.json$"]
}

Do not confuse filePatterns with the paths filter in a workflow's trigger: filePatterns decides where a template is suggested, while paths decides when a created workflow runs.

A template's YAML can use the $default-branch placeholder, for example branches: [ $default-branch ]. GitHub replaces it with the repository's default branch name once, when a workflow is created from the template, so one template works for repositories that use main, trunk or develop. After that:

• The copy holds the literal name. The committed file says branches: [ main ], not the placeholder.
• It does not follow a rename. If the repository's default branch is later renamed, the created workflow still names the old branch until someone edits it, because renaming a branch does not rewrite the files that reference it.
• It only works in templates. Typed into an ordinary workflow file in .github/workflows, $default-branch is not substituted; it is just text. It is not an expression either, and ${{ }} expressions are not allowed in branch filters.

Creating and governing templates is an administration task covered with the enterprise governance topic; a consumer needs to recognise where they live and why one does or doesn't appear.

Which repositories can be offered an organization's templates depends on the visibility of the .github repository that holds them:

Read the table as a ceiling, not a default: a private .github repository keeps its templates away from internal repositories as well as public ones, and an internal one never serves public repositories. To keep templates confidential to private repositories, the .github repository must itself be private.

For an internal or private .github repository, the person creating the workflow also needs Read access to it. Granting Read access to the people or teams who need the templates is the way to share non-public templates while the .github repository itself stays restricted; changing its visibility widens who can read it. The repository's Actions access setting (below) is a different control: it lets workflows call reusable workflows and actions, and has nothing to do with which templates a person sees.

Templates are organized per organization: each organization publishes its own from its own .github repository.

You consume a reusable workflow with uses on a job — never on a step. A step's uses runs an action; a job's uses calls a workflow file.

jobs:
  build:
    uses: acme/platform-workflows/.github/workflows/lint.yml@v3
  unit:
    uses: $/.github/workflows/unit.yml

• Another repository: {owner}/{repo}/.github/workflows/{filename}@{ref}. The full path to the file and the @ref are both required; owner/repo/build.yml@v2 or owner/repo@v2/... are invalid.
• The same repository: $/.github/workflows/{filename} (the form GitHub now recommends) or ./.github/workflows/{filename}, both with no @ref. The called file comes from the same commit as the caller, so a pull request branch tests its own version of both files. Adding a ref to these forms is not allowed. The $/ form is not available on GitHub Enterprise Server, where ./ remains the way to write it.
• No expressions. uses is read before the run starts, so contexts and expressions such as ${{ vars.CI_TAG }} or ${{ github.sha }} cannot be used in it.

The ref decides how stable the call is:

If a tag and a branch share a name, the tag takes precedence when the ref is resolved, so keep tag and branch names distinct in repositories that publish reusable workflows. Prefixes such as refs/heads/ are not used in the ref.

Defining on: workflow_call with inputs, secrets and outputs is covered in the workflow triggers lesson; this lesson covers consuming the workflow.

A job that calls a reusable workflow is not a normal job: the called workflow's own jobs choose runners and run steps, so the calling job accepts only a short list of keywords:

• name, uses, with, secrets (including secrets: inherit)
• strategy (matrix), needs, if, concurrency, permissions

Anything else — runs-on, steps, env, environment, timeout-minutes, container, services — makes the workflow invalid. Fix it by removing the key and, if the value matters, passing it to the called workflow as an input.

Fanning out with a matrix is allowed: put strategy.matrix on the calling job and pass the value through with:. Each matrix combination calls the reusable workflow once, in parallel.

jobs:
  rollout:
    strategy:
      matrix:
        cluster: [blue, green, canary]
    uses: acme/release-pipelines/.github/workflows/rollout.yml@9c41e7a2d58b3f06e1a7c2d94b8f5e03a6d17c2b
    with:
      cluster: ${{ matrix.cluster }}

Environments belong on the called workflow's jobs. Because environment is not allowed on the calling job, approvals and environment secrets come from the deploy job inside the reusable workflow. To keep one workflow for staging and production, declare an input (for example target) and set environment: ${{ inputs.target }} on the called job; the production environment's protection rules and secrets then apply when the caller passes production.

A caller can use a reusable workflow only if it can access it. Workflows in a public repository can be called from anywhere. For a private (or internal) repository, an administrator of the repository that holds the workflows must open Settings > Actions > General > Access and allow access from repositories in the organization (or enterprise). This repository-level setting is the only switch: access is not granted by tokens or by permissions on the calling workflow.

• A private repository can share only with private repositories; an internal repository with internal and private ones. A public repository can never call a workflow in a private repository — move the workflows it needs into a public repository instead.
• Read access for people is not the same thing: granting a team Read access does not let workflows call the repository's workflows.

Nesting rules. Reusable workflows can call other reusable workflows:

• A chain can have at most ten levels: the top-level caller plus up to nine nested reusable workflows.
• Loops are not permitted, whatever conditions the jobs have.
• Every workflow in the chain must be accessible to the caller. If a nested workflow sits in another private repository still on default settings, the run fails until that repository's Actions access setting allows the organization.
• A single workflow file can call at most 50 unique reusable workflows, counting nested trees.

Permissions only go down. The GITHUB_TOKEN permissions of a called workflow can be kept or reduced through the chain, never elevated. If a called job asks for more than the caller granted (for example contents: write when the caller allows only contents: read), the extra permission is not granted and the run fails with a permissions error instead of running the job. Grant the permission on the caller (or its calling job) instead.

Context and variables. The github context in a called workflow always describes the caller's run: github.repository is the calling repository and github.sha the commit that triggered it, not the repository or ref of the reusable workflow. Variables in the caller's workflow-level env are not propagated to the called workflow, and the called workflow's env is not visible to the caller — pass values as inputs.

A composite action is consumed as a step: uses: acme/toolchain-setup@v1 inside an existing job's steps. Its steps run in place, which gives it three defining properties:

• Same runner and workspace. It runs on the calling job's runner and sees the files earlier steps wrote — checked-out code, compiled binaries — with no artifact upload. action.yml has no runs-on; it declares runs: using: composite.
• Data in through inputs. Values come from with: on the step and must be declared as inputs in action.yml. The secrets context is not available inside the action's own files, so referencing a secret there fails as an unrecognized context. Declare an input and have the calling workflow pass the secret into it with with:; the value stays masked in logs. secrets: inherit is only for calling jobs.
• One step in the log. It appears as a single step of the calling job, not as a separate job in the run graph.

steps:
  - uses: actions/checkout@v5
  - uses: acme/cache-warmup@v1
    with:
      api-key: ${{ secrets.CACHE_API_KEY }}
  - run: make integration-test

Composite actions suit repeated setup steps and post-build steps that must touch the job's files. They cannot run work on a different runner or show each shared step separately in real time — that needs a reusable workflow. Building and publishing actions is covered in the custom actions lessons.

Disabling a workflow pauses it everywhere while keeping its file and history; deleting the workflow file removes the definition from the branch where it is deleted, and only from that branch.

Ways to disable or enable a single workflow:

• UI: Actions tab > select the workflow > the … menu > Disable workflow (later, Enable workflow).
• GitHub CLI: gh workflow disable nightly-report.yml and gh workflow enable nightly-report.yml.
• REST API: PUT /repos/{owner}/{repo}/actions/workflows/{workflow_id}/disable and …/enable. workflow_id accepts the numeric ID or the file name, which makes it easy to script across many repositories.

Don't confuse this with turning Actions off for the whole repository (PUT /repos/{owner}/{repo}/actions/permissions with enabled: false, or the repository settings page), which stops every workflow, or with cancelling a run, which stops only that run. Editing the file is no substitute either: an event runs the workflow file as it exists in the commit or branch the event is evaluated against, so a trigger change committed to one branch does not change the copies other branches still carry. Disabling is the one action that stops a workflow on every branch without changing any branch.

A workflow's state is reported by the API as active, disabled_manually, disabled_inactivity, disabled_fork or deleted.

GitHub disables some workflows on its own, and the fix is to enable them again — new activity does not do it.

• Inactive public repositories. In a public repository, scheduled workflows are automatically disabled when there has been no repository activity for 60 days. A maintainer re-enables the workflow from the Actions tab, with gh workflow enable or the REST API. Later activity in the repository does not switch it back on by itself, and scheduled workflows always run from the default branch.
• Forks. When you fork a public repository, its scheduled workflows are disabled by default in the fork, so a nightly job upstream does not start running on the fork's account. Enable them in the fork if you want them.

These states show up in the API as disabled_inactivity and disabled_fork, distinct from a workflow someone disabled manually.