> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Demo Build and Consume Reusable Workflows

> Guide to create and consume reusable GitHub Actions workflows from an organization level .github repository, centralizing CI steps and explaining usage, permissions, and common errors.

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.

```yaml theme={null}
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.](https://mintcdn.com/kodekloud-c4ac6d9a/IdpF6mT8Tun72cng/images/GitHub-Administration-Certification/GitHub-Actions-and-Runners/Demo-Build-and-Consume-Reusable-Workflows/github-workflows-reusable-ci-screenshot.jpg?fit=max\&auto=format\&n=IdpF6mT8Tun72cng\&q=85\&s=456b45b60de3f83e0127b347bfa82af5)

***

## 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:

```yaml theme={null}
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.](https://mintcdn.com/kodekloud-c4ac6d9a/IdpF6mT8Tun72cng/images/GitHub-Administration-Certification/GitHub-Actions-and-Runners/Demo-Build-and-Consume-Reusable-Workflows/github-dark-mode-dotgithub-files.jpg?fit=max\&auto=format\&n=IdpF6mT8Tun72cng\&q=85\&s=663fab00593d62a13fbc5568eeb3a608)

***

## 3) Common errors and permissions

If the calling workflow fails with an error like:

```text theme={null}
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.](https://mintcdn.com/kodekloud-c4ac6d9a/IdpF6mT8Tun72cng/images/GitHub-Administration-Certification/GitHub-Actions-and-Runners/Demo-Build-and-Consume-Reusable-Workflows/github-actions-workflows-runs-sidebar.jpg?fit=max\&auto=format\&n=IdpF6mT8Tun72cng\&q=85\&s=743b195375f7570437e39e836ead6fd2)

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.](https://mintcdn.com/kodekloud-c4ac6d9a/IdpF6mT8Tun72cng/images/GitHub-Administration-Certification/GitHub-Actions-and-Runners/Demo-Build-and-Consume-Reusable-Workflows/github-actions-settings-readonly-game-devstudio.jpg?fit=max\&auto=format\&n=IdpF6mT8Tun72cng\&q=85\&s=b6997a7bcd6a2870e9d73ca40c663467)

***

## 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`):

```yaml theme={null}
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](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](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](https://docs.github.com/actions/learn-github-actions/authorizing-deployments#using-environments-for-deployments)

> [card] [Watch Video](https://learn.kodekloud.com/user/courses/github-administration-certification/module/3ba840c5-7afb-4da9-8395-a430a6354557/lesson/b0ab863f-36e6-463a-add2-78485fa068a6)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.