dorny/paths-filter

Use dorny/paths-filter@v4 to detect file changes and set an output variable. You can then use this output in a GitHub Actions if conditional to run specific steps or jobs only when certain files (e.g., in a src folder) have been modified.

- uses: dorny/paths-filter@v4
  id: changes
  with:
    filters: |
      src:
        - 'src/**'

# run only if some file in 'src' folder was changed
- if: steps.changes.outputs.src == 'true'
  run: ...

You can use the changes output to dynamically populate a GitHub Actions matrix. This allows you to run jobs only for the specific packages that were modified.

1. Create a changes job that runs the filter.
2. Map the steps.filter.outputs.changes to a job output.
3. Use fromJSON() in the downstream job's matrix strategy to parse the array.

jobs:
  changes:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: read
    outputs:
      packages: ${{ steps.filter.outputs.changes }}
    steps:
    - uses: dorny/paths-filter@v4
      id: filter
      with:
        filters: |
          package1: src/package1
          package2: src/package2

  build:
    needs: changes
    strategy:
      matrix:
        package: ${{ fromJSON(needs.changes.outputs.packages) }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - ...

The action supports various GitHub event types:

• Pull requests (pull_request, pull_request_target): Detects changes against the PR base branch using the GitHub REST API. Requires pull-requests: read permission.
• Feature branches (push or other events): Detects changes against the merge-base with the configured base branch using git commands. Requires the repository to be checked out.
• Merge queue (merge_group): Detects changes using git commands. base and ref default to commit hashes from the event.
• Long-lived branches (push): If base is the same as the triggering branch, changes are detected against the most recent commit before the push.
• Local changes: If base is set to HEAD, changes are detected against the current HEAD (untracked files are ignored).

Depending on your workflow trigger, you can specify the base to compare changes against:

• Pull Requests: Automatically detects changes against the PR base branch (no base config needed).
• Feature Branches: Use base: <branch_name> to compare against a specific branch (e.g., develop).
• Long-lived Branches: Use base: ${{ github.ref }} to compare against the most recent commit on the same branch.
• Local Changes: Use base: HEAD to detect staged and unstaged local changes.

You can control how the ${FILTER_NAME}_files output is formatted using the list-files option:

• shell: Paths are escaped and space-delimited. Ideal for passing as command-line arguments in a Linux shell.
• json: Paths are formatted as a JSON array. Ideal for passing to other GitHub Actions that consume JSON lists.

- uses: dorny/paths-filter@v4
  id: filter
  with:
    list-files: shell
    filters: |
      markdown:
        - '*.md'

Instead of defining filters inline in your workflow YAML, you can point to an external file using the filters option.

- uses: dorny/paths-filter@v4
  id: filter
  with:
    filters: .github/filters.yaml

If running in a container job, you might encounter Git dubious ownership errors. The action attempts to handle this automatically by retrying with a temporary HOME.

If your workflow relies on credentials in ~/.git-credentials or ~/.netrc, you must manually mark the repository as safe in a preceding step:

git config --global --add safe.directory "$GITHUB_WORKSPACE"

The predicateQuantifier determines the logic used when evaluating multiple patterns within a single filter rule. This is configured via the FilterConfig object passed to the Filter constructor.

• SOME: (Default) A file matches the rule if it satisfies at least one of the patterns. This corresponds to the some logic quantifier.
• EVERY: A file matches the rule only if it satisfies all of the patterns. This corresponds to the every logic quantifier.

The predicate-quantifier input determines the logic used to decide if a filter group matches.

• some: The filter matches if at least one file in the changed set matches any of the rules in the filter group. (Default)
• all: The filter matches only if all files in the changed set match the rules in the filter group.

By setting the list-files input, you can retrieve a list of all files that matched your filters via the <id>.outputs.paths_<filter_name> output variable. Supported formats include:

• csv: Comma-separated list, wrapping filenames with unsafe characters in double quotes.
• json: A JSON array of file paths.
• shell: Space-delimited list for Linux shells, wrapping filenames with single or double quotes.
• escape: Space-delimited list for Linux shells using backslash escapes for unsafe characters.