Running GitHub Actions workflows for specific folder changes

Learn how to configure GitHub Actions to trigger workflows only when specific files or directories change.

Problem

You have a repository with multiple folders and want to run GitHub Actions workflows only when files in a specific directory are modified. For example:

- folder1/
  - file1
  - other files
- folder2/
  - file1
  - other files
- .gitignore
- package.json
- other files

You need the workflow to trigger on push events, but only if changes occur within folder1.

Solution: Path filters

The most efficient solution uses GitHub's built-in path filtering in workflow triggers.

Basic path filtering

on:
  push:
    paths:
      - 'folder1/**'

This workflow will only run when files matching the pattern folder1/** are changed in a push.

Including multiple patterns

on:
  push:
    paths:
      - 'folder1/**'
      - 'folder2/subfolder/**'

Combining with branch filtering

on:
  push:
    branches: ['main', 'develop']
    paths: ['folder1/**']

TIP

Use single quotes around patterns to ensure proper YAML parsing, especially when using special characters.

Advanced filtering patterns

Excluding specific subdirectories

You can combine positive and negative patterns to exclude specific subdirectories:

on:
  push:
    paths:
      - 'folder1/**'
      - '!folder1/docs/**'  # Exclude docs subdirectory

WARNING

You must include at least one positive pattern when using negative patterns (! prefix). Patterns are evaluated in order.

Using paths-ignore

As an alternative to negative patterns, you can use paths-ignore:

on:
  push:
    paths-ignore:
      - 'folder1/docs/**'

DANGER

You cannot use both paths and paths-ignore for the same event. Choose one approach.

Including workflow files

If you want the workflow to run when the workflow file itself changes, include it in the paths:

on:
  push:
    paths:
      - 'folder1/**'
      - '.github/workflows/**'  # Include workflow changes

Handling pull requests

To apply the same filtering to pull requests:

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

Job-level filtering

Path filters only work at the workflow trigger level. For job-level filtering based on changed files, use the changed-files action:

jobs:
  my-job:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: tj-actions/changed-files@v42
        id: changed-files
        with:
          files: folder1/**
      
      - name: Run if folder1 changes
        if: steps.changed-files.outputs.any_changed == 'true'
        run: echo "Folder1 was modified!"

INFO

The changed-files action is useful when you need conditional execution within jobs, while path filtering is more efficient for determining whether to run the workflow at all.

Best practices

1. Test your patterns: Use the GitHub Actions interface to verify which changes trigger your workflow
2. Keep patterns specific: Avoid overly broad patterns that might trigger unnecessarily
3. Combine with branch filters: Add branch restrictions for better control
4. Consider workflow changes: Include .github/workflows/** if workflow modifications should trigger runs

By implementing these path filtering techniques, you can optimize your GitHub Actions workflows to run only when relevant code changes occur, saving computation resources and providing faster feedback loops.