What’s the best way to trigger a GitHub Actions workflow only when specific files or folders change?

[Amanuel776]

Why are you starting this discussion?

Question

What GitHub Actions topic or product is this about?

Misc

Discussion Details

I have a monorepo setup, and I want to run certain workflows only when files in a specific folder (like /backend/ or /docs/) are modified.

I’ve tried using paths in the on.push trigger, but I’m not sure if I’m doing it optimally or if it works with pull requests too.

What’s the best practice for this use case?
Also, how does it behave with file deletions or renames?

Here’s a snippet of what I’m currently using:

on:
push:
paths:
- backend/
Any advice, improvements, or gotchas to look out for?

[AmanT776]

GitHub Actions Path Filtering for Monorepos

This is about GitHub Actions' path filtering capabilities, specifically for monorepo workflows. Let me break down the best practices and considerations:

Optimal Path Filtering Setup

For your monorepo, you can optimize path filtering like this:

on:
  push:
    paths:
      - 'backend/**'
      - 'backend/*'
  pull_request:
    paths:
      - 'backend/**'
      - 'backend/*'

Key Considerations

1. Double Asterisk (**) vs Single Asterisk (*):

   • backend/** matches all files in backend and its subdirectories
   • backend/* matches only files directly in the backend directory

2. Pull Request Behavior:

   • Path filtering works with pull requests, but only for the final merged state
   • It doesn't trigger on intermediate commits during PR review

3. File Deletions and Renames:

   • Deletions will trigger the workflow if the deleted file matched the path filter
   • Renames are treated as deletion+addition - both old and new paths are evaluated

Improved Approach for Monorepos

Consider this more robust pattern:

on:
  push:
    paths:
      - 'backend/**'
      - 'backend/*'
      - 'package.json'
      - 'yarn.lock'
      - 'pnpm-lock.yaml'
      - 'lerna.json'
  pull_request:
    paths-ignore:
      - 'docs/**'
      - 'README.md'

Gotchas to Watch For

1. Default Branch Behavior: Path filtering doesn't apply to workflow dispatch or scheduled events

2. First Push Limitation: The initial push to a new branch evaluates all files, not just changed ones

3. Performance Impact: GitHub evaluates path filters against every file changed in the commit

4. Negative Patterns: You can use paths-ignore to exclude certain paths

Advanced Example

For complex monorepos, consider using a matrix approach:

jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
include:
- package: backend
path: 'backend/'
- package: frontend
path: 'frontend/'
steps:
- uses: actions/checkout@v4
- name: Build ${{ matrix.package }}
if: contains(github.event..files..filename, matrix.path)
run: echo "Building ${{ matrix.package }}"

[yuvarajsakthi]

The best way to trigger a GitHub Actions workflow only when specific files or folders change is by using the [paths](https://github.com/proxy/docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpaths) or [paths-ignore] filter under the on.push or on.pull_request event in your workflow YAML file.

Here’s an example:

name: Run on Specific File Changes

on:
  push:
    paths:
      - 'src/**'
      - 'config/*.yml'
  pull_request:
    paths:
      - 'src/**'
      - 'config/*.yml'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: echo "Changes detected in src or config folder."

Explanation:

• The paths filter ensures this workflow runs only when files in src/ or config/ change.
• You can use glob patterns like ** to include subdirectories.

💡 Pro Tip: If you're combining multiple workflows, use paths strategically to optimize CI/CD runs and save compute time.

[SamG101-Developer]

is there any way to run the path config to individual jobs within a workflow? so say you had jobs "build" and "docs", and only want "build" to run if "src" was pushed to? thanks

[MarkAlex1234]

For a single folder, on.push.paths / on.pull_request.paths is the simplest answer. Note that a workflow skipped this way never reports a status, so it can block a required check.

Monorepos with several services usually want something else: run CI only for the projects that changed, plus the projects that depend on them (change libs/shared → rebuild everything that uses it). Path lists get hard to maintain for that. Here is a pattern that avoids them:

1. One "plan" job works out which projects are affected and outputs a JSON list.
2. The build job fans out over that list with strategy.matrix: ${{ fromJSON(...) }}.
3. Guard the matrix job with if: on a "has changes" output, because an empty matrix fails the job.

I maintain an open-source action that does step 1 without any config. It detects projects from package.json, go.mod, Cargo.toml, Dockerfile, pyproject.toml, pom.xml and similar files, and reads their dependencies from the manifests (disclosure: I am the author):

jobs:
  plan:
    runs-on: ubuntu-latest
    outputs:
      build: ${{ steps.plan.outputs.build }}
      has_build: ${{ steps.plan.outputs.has_build }}
      paths: ${{ steps.plan.outputs.paths }}
    steps:
      - uses: actions/checkout@v4
      - uses: Continuous-Actions/dynamic-monorepo@v1
        id: plan
  build:
    needs: plan
    if: needs.plan.outputs.has_build == 'true'
    runs-on: ubuntu-latest
    strategy:
      matrix:
        project: ${{ fromJSON(needs.plan.outputs.build) }}
    steps:
      - uses: actions/checkout@v4
      - run: echo "build ${{ matrix.project }}"
        working-directory: ${{ fromJSON(needs.plan.outputs.paths)[matrix.project] }}

Demo with example PRs: https://github.com/Continuous-Actions/dynamic-monorepo-demo. Whatever tool you use, the plan → fromJSON matrix → if: guard pattern is the part that matters.