Paths Changes Filter

GitHub Action that enables conditional execution of workflow steps and jobs, based on the files modified by pull request, on a feature branch, or by the recently pushed commits.

Run slow tasks like integration tests or deployments only for changed components. It saves time and resources, especially in monorepo setups. GitHub workflows built-in path filters don't allow this because they don't work on a level of individual jobs or steps.

Real world usage examples:

• sentry.io - backend.yml
• GoogleChrome/web.dev - lint-workflow.yml
• blog post Configuring python linting to be part of CI/CD using GitHub actions - py_linter.yml

Supported workflows

• Pull requests:
• Workflow triggered by pull_request or pull_request_target event
• Changes are detected against the pull request base branch
• Uses GitHub REST API to fetch a list of modified files
• Requires pull-requests: read permission
• Feature branches:
• Workflow triggered by push or any other event
• The base input parameter must not be the same as the branch that triggered the workflow
• Changes are detected against the merge-base with the configured base branch or the default branch
• Uses git commands to detect changes - repository must be already checked out
• Merge queue:
• Workflow triggered by merge_group
• The base and ref input parameters default to commit hashes from the event unless explicitly specified.
• Uses git commands to detect changes - repository must be already checked out
• Master, Release, or other long-lived branches:
• Workflow triggered by push event when base input parameter is the same as the branch that triggered the workflow:
  • Changes are detected against the most recent commit on the same branch before the push
• Workflow triggered by any other event when base input parameter is commit SHA:
  • Changes are detected against the provided base commit
• Workflow triggered by any other event when base input parameter is the same as the branch that triggered the workflow:
  • Changes are detected from the last commit
• Uses git commands to detect changes - repository must be already checked out
• Local changes
• Workflow triggered by any event when base input parameter is set to HEAD
• Changes are detected against the current HEAD
• Untracked files are ignored

Example

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

For more scenarios see examples section.

Notes

• Paths expressions are evaluated using picomatch library. Documentation for path expression format can be found on the project GitHub page.
• Picomatch dot option is set to true. Globbing will also match paths where file or folder name starts with a dot.
• It's recommended to quote your path expressions with ' or ". Otherwise, you will get an error if it starts with *.
• Local execution with act works only with alternative runner image. Default runner doesn't have git binary.
• Use: act -P ubuntu-latest=nektos/act-environments-ubuntu:18.04
• Git dubious ownership errors in container jobs are handled automatically - the action retries with a temporary HOME containing a safe.directory entry, the same technique used by actions/checkout. Only if fetching relies on credentials stored in HOME-relative files (e.g. ~/.git-credentials or ~/.netrc), mark the repository as safe yourself in a step before this action: git config --global --add safe.directory "$GITHUB_WORKSPACE"

What's New

• Automatic workaround for git dubious ownership errors in container jobs
• New major release v4 after update to Node 24 [Breaking change]
• Add ref input parameter
• Add list-files: csv format
• Configure matrix job to run for each folder with changes using changes output
• Improved listing of matching files with list-files: shell and list-files: escape options
• Paths expressions are now evaluated using picomatch library

For more information, see CHANGELOG

Usage

- uses: dorny/paths-filter@v4
  with:
    # Defines filters applied to detected changed files.
    # Each filter has a name and a list of rules.
    # Rule is a glob expression - paths of all changed
    # files are matched against it.
    # Rule can optionally specify if the file
    # should be added, modified, or deleted.
    # For each filter, there will be a corresponding output variable to
    # indicate if there's a changed file matching any of the rules.
    # Optionally, there can be a second output variable
    # set to list of all files matching the filter.
    # Filters can be provided inline as a string (containing valid YAML document),
    # or as a relative path to a file (e.g.: .github/filters.yaml).
    # Filters syntax is documented by example - see examples section.
    filters: ''

    # Branch, tag, or commit SHA against which the changes will be detected.
    # If it references the same branch it was pushed to,
    # changes are detected against the most recent commit before the push.
    # If it is empty and action is triggered by merge_group event,
    # the base commit in the event will be used.
    # Otherwise, it uses git merge-base to find the best common ancestor between
    # current branch (HEAD) and base.
    # When merge-base is found, it's used for change detection - only changes
    # introduced by the current branch are considered.
    # All files are considered as added if there is no common ancestor with
    # base branch or no previous commit.
    # This option is ignored if action is triggered by pull_request event.
    # Default: repository default branch (e.g. master)
    base: ''

    # Git reference (e.g. branch name) from which the changes will be detected.
    # Useful when workflow can be triggered only on the default branch (e.g. repository_dispatch event)
    # but you want to get changes on a different branch.
    # If this is empty and action is triggered by merge_group event,
    # the head commit in the event will be used.
    # This option is ignored if action is triggered by pull_request event.
    # default: ${{ github.ref }}
    ref:

    # How many commits are initially fetched from the base branch.
    # If needed, each subsequent fetch doubles the
    # previously requested number of commits until the merge-base
    # is found, or there are no more commits in the history.
    # This option takes effect only when changes are detected
    # using git against base branch (feature branch workflow).
    # Default: 100
    initial-fetch-depth: ''

    # Enables listing of files matching the filter:
    #   'none'  - Disables listing of matching files (default).
    #   'csv'   - Coma separated list of filenames.
    #             If needed, it uses double quotes to wrap filename with unsafe characters.
    #   'json'  - File paths are formatted as JSON array.
    #   'shell' - Space delimited list usable as command-line argument list in Linux shell.
    #             If needed, it uses single or double quotes to wrap filename with unsafe characters.
    #   'escape'- Space delimited list usable as command-line argument list in Linux shell.
    #             Backslash escapes every potentially unsafe character.
    # Default: none
    list-files: ''

    # Relative path under $GITHUB_WORKSPACE where the repository was checked out.
    working-directory: ''

    # Personal access token used to fetch a list of changed files
    # from GitHub REST API.
    # It's only used if action is triggered by a pull request event.
    # GitHub token from workflow context is used as default value.
    # If an empty string is provided, the action falls back to detect
    # changes using git commands.
    # Default: ${{ github.token }}
    token: ''

    # Optional parameter to override the default behavior of file matching algorithm.
    # By default files that match at least one pattern defined by the filters will be included.
    # This parameter allows to override the "at least one pattern" behavior to make it so that
    # all of the patterns have to match or otherwise the file is excluded.
    # An example scenario where this is useful if you would like to match all
    # .ts files in a sub-directory but not .md files.
    # The filters below will match markdown files despite the exclusion syntax UNLESS
    # you specify 'every' as the predicate-quantifier parameter. When you do that,
    # it will only match the .ts files in the subdirectory as expected.
    #
    # backend:
    #  - 'pkg/a/b/c/**'
    #  - '!**/*.jpeg'
    #  - '!**/*.md'
    predicate-quantifier: 'some'

Outputs

• For each filter, it sets output variable named by the filter to the text:
• 'true' - if any of changed files matches any of filter rules
• 'false' - if none of changed files matches any of filter rules
• For each filter, it sets an output variable with the name ${FILTER_NAME}_count to the count of matching files.
• If enabled, for each filter it sets an output variable with the name ${FILTER_NAME}_files. It will contain a list of all files matching the filter.
• changes - JSON array with names of all filters matching any of the changed files.

Examples

Conditional execution

Execute step in a workflow job only if some file in a subfolder is changed

jobs:
  tests:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v6
    - uses: dorny/paths-filter@v4
      id: filter
      with:
        filters: |
          backend:
            - 'backend/**'
          frontend:
            - 'frontend/**'

    # run only if 'backend' files were changed
    - name: backend tests
      if: steps.filter.outputs.backend == 'true'
      run: ...

    # run only if 'frontend' files were changed
    - name: frontend tests
      if: steps.filter.outputs.frontend == 'true'
      run: ...

    # run if 'backend' or 'frontend' files were changed
    - name: e2e tests
      if: steps.filter.outputs.backend == 'true' || steps.filter.outputs.frontend == 'true'
      run: ...

Execute job in a workflow only if some file in a subfolder is changed

jobs:
  # JOB to run change detection
  changes:
    runs-on: ubuntu-latest
    # Required permissions
    permissions:
      pull-requests: read
    # Set job outputs to values from filter step
    outputs:
      backend: ${{ steps.filter.outputs.backend }}
      frontend: ${{ steps.filter.outputs.frontend }}
    steps:
    # For pull requests it's not necessary to checkout the code
    - uses: dorny/paths-filter@v4
      id: filter
      with:
        filters: |
          backend:
            - 'backend/**'
          frontend:
            - 'frontend/**'

  # JOB to build and test backend code
  backend:
    needs: changes
    if: ${{ needs.changes.outputs.backend == 'true' }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - ...

  # JOB to build and test frontend code
  frontend:
    needs: changes
    if: ${{ needs.changes.outputs.frontend == 'true' }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - ...

Use change detection to configure matrix job

```yaml jobs: # JOB to run change detection changes: runs-on: ubuntu-latest # Required permissions permissions: pull-requests: read outputs: # Expose matched filters as job 'packages' output variable packages: ${{ steps.filter.outputs.changes }} steps: