Demo Build and Consume Reusable Workflows

This guide shows how to create a reusable GitHub Actions workflow in a central (organization-level) repository and call it from a consumer repository. Reusable workflows help you centralize CI logic (checkout, tool setup, installs) so many repositories can share the same steps without duplication.

1) Create a reusable workflow

Create an organization-level repository named .github and add a workflow at .github/workflows/reusable-ci.yml with the contents below. This workflow uses on: workflow_call so other workflows can invoke it and accepts a node-version input.

name: Reusable CI
on:
  workflow_call:
    inputs:
      node-version:
        required: true
        type: string
jobs:
  npm-install:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
      - run: npm install

Why this works

on: workflow_call declares the workflow as reusable by other workflows.
The workflow takes a required string input node-version.
The npm-install job: runs on ubuntu-latest, checks out code, sets up Node.js using the passed input, and runs npm install.

Once you commit this file to the .github repository’s default branch (commonly main), the reusable workflow becomes available to consumer repositories.

Screenshot of a GitHub repository in dark mode showing the .github/workflows directory with a reusable-ci.yml file. The left sidebar shows the file tree and the main pane lists the workflow file and its commit message.

2) Call the reusable workflow from a consumer repository

In your application repository (for example, ghas-catrils-demo) create a workflow file at .github/workflows/ci.yml that references the reusable workflow. Example:

name: Using Reusable CI Workflow
on:
  - push
  - workflow_dispatch
jobs:
  init-ci:
    uses: game-devstudio/.github/.github/workflows/reusable-ci.yml@main
    with:
      node-version: '24'

Key points

The uses value must follow the format: owner/repository/path/to/workflow@ref. For an organization-level .github repo the path will include .github in the repository name and again in the path: owner/.github/.github/workflows/reusable-ci.yml@main.
push triggers runs on commits; workflow_dispatch enables manual runs from the Actions UI.
The with block passes the node-version input required by the reusable workflow.

Files summary

File path	Purpose	Example
`.github/workflows/reusable-ci.yml`	Central reusable workflow hosted in the organization `.github` repo	See reusable CI workflow above
`.github/workflows/ci.yml`	Consumer repository workflow that calls the reusable workflow	`uses: game-devstudio/.github/.github/workflows/reusable-ci.yml@main`

Important: the consumer workflow file must be placed in .github/workflows/ci.yml on the repository’s default branch. If it is outside the workflows directory, GitHub Actions will not pick it up.

A dark-mode screenshot of a GitHub repository page showing the .github folder and file tree. The main panel lists files like ISSUE_TEMPLATE, CODEOWNERS, PULL_REQUEST_TEMPLATE.md, SECURITY.md, ci.yml and dependabot.yml.

3) Common errors and permissions

If the calling workflow fails with an error like:

Invalid workflow file: .github/workflows/ci.yml#L7
error parsing called workflow ".github/workflows/ci.yml" -> "game-devstudio/.github/.github/workflows/reusable-ci.yml@main" : workflow was not found. See https://docs.github.com/actions/learn-github-actions/reusing-workflows#access-to-reusable-workflows for more information.

This usually means one of two issues: a wrong path/ref or repository access restrictions. Checklist to verify

Item	What to check
Path & ref	Confirm the reusable workflow exists at the exact path and branch referenced. For `.github` repos, ensure the `uses` string includes the repository name: `owner/.github/.github/workflows/reusable-ci.yml@main`.
Repository access	If the reusable workflow repo is private, ensure the consumer repo has permission to use Actions from that repository. Check the Actions access settings in the reusable workflow repo.

If the reusable workflow repository is private, you must explicitly allow access from consumer repositories. Go to the reusable repository’s Settings → Actions → General and adjust “Access” so other repositories in your organization can use its workflows.

A dark-themed GitHub Actions page showing a repository's workflows and a list of recent workflow runs with status icons. The left sidebar displays workflow files and management options like caches, runners, and metrics.

If the reusable workflow repository is public, consumers can call it without extra configuration. If it is private (or you change visibility later), verify the Actions access settings remain correct and that the referenced branch or ref still exists.

A dark-mode screenshot of a GitHub repository's Actions settings page. It shows "Workflow permissions" and "Access" options with radio buttons selecting read-only repository contents and accessibility from the "game-devstudio" organization.

4) Triggering and observing the reusable workflow run

Once the consumer workflow is correctly placed and permissions are set:

A push to the consumer repository or a manual workflow_dispatch will invoke the reusable workflow.
In the consumer repository’s Actions UI you will see the run and the jobs defined by the reusable workflow (for example, npm-install).
The steps (checkout, setup-node, npm install) will execute in the context of the consumer repository run, but sourced from the central reusable workflow.

Centralizing shared steps in a reusable workflow reduces duplication and makes it easier to update CI behavior across many repositories.

Reusable workflows require on: workflow_call. When the reusable workflow lives in the special .github repository, include the repository name in the uses path—for example: owner/.github/.github/workflows/reusable-ci.yml@main.

5) Final reusable workflow reference

For convenience, here is the reusable workflow again (copy this into your .github/workflows/reusable-ci.yml):

name: Reusable CI
on:
  workflow_call:
    inputs:
      node-version:
        required: true
        type: string
jobs:
  npm-install:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
      - run: npm install

This pattern helps you keep CI logic consistent and maintainable across many repositories while keeping consumer workflows simple.

Links and references

Reusing workflows (GitHub Actions): https://docs.github.com/actions/learn-github-actions/reusing-workflows
Workflow syntax for GitHub Actions: https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions
Actions permissions and repository access: https://docs.github.com/actions/learn-github-actions/authorizing-deployments#using-environments-for-deployments

Course Introduction

Foundation Setup

Identity and Access Management

Governance and Roles

Security and Compliance

GitHub Actions and Runners

Administration and Support

Monitoring and Optimization

Demo Build and Consume Reusable Workflows

1) Create a reusable workflow

2) Call the reusable workflow from a consumer repository

3) Common errors and permissions

4) Triggering and observing the reusable workflow run

5) Final reusable workflow reference

Links and references

Watch Video

​1) Create a reusable workflow

​2) Call the reusable workflow from a consumer repository

​3) Common errors and permissions

​4) Triggering and observing the reusable workflow run

​5) Final reusable workflow reference

​Links and references

Watch Video

1) Create a reusable workflow

2) Call the reusable workflow from a consumer repository

3) Common errors and permissions

4) Triggering and observing the reusable workflow run

5) Final reusable workflow reference

Links and references