GitHub Actions in a Monorepo

GitHub Actions only discovers workflow files in .github/workflows/ at the repository root. Workflows placed in subdirectories (e.g., nextjs/my-app/.github/workflows/) are silently ignored.

The Problem

In a monorepo with multiple projects, each project might have its own CI config. But GitHub won't find them if they're nested.

The Solution

Move workflows to the root and use path filters + working-directory:

name: CI - my-project

on:
  push:
    branches: [main]
    paths:
      - 'nextjs/my-project/**'
      - '.github/workflows/ci-my-project.yml'
  pull_request:
    paths:
      - 'nextjs/my-project/**'

jobs:
  build:
    runs-on: self-hosted
    defaults:
      run:
        working-directory: nextjs/my-project

    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: 22
          cache: "npm"
          cache-dependency-path: nextjs/my-project/package-lock.json
      - run: npm ci
      - run: npm run build
      - run: npm run lint

Key Points

• Path filters ensure the workflow only runs when the specific project changes
• working-directory sets the default cd for all run steps
• cache-dependency-path must point to the project's package-lock.json
• Name workflows descriptively: ci-project-name.yml
• Include the workflow file itself in path filters for self-updates

Referenced from: Mar 20, 2026