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://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.