dorny/paths-filter@v4

Execute your workflow steps only if relevant files are modified.

At a glance

Latest major
v4
Repository
dorny/paths-filter
Inputs
8 (1 required)
Outputs
1
Runs using
node24
License
MIT
Last checked

Inputs and outputs come straight from the action's official action.yml. See our editorial standards.

Usage

- uses: dorny/paths-filter@v4

Inputs

NameRequiredDefaultDescription
tokenNo${{ github.token }}GitHub Access Token
working-directoryNononeRelative path under $GITHUB_WORKSPACE where the repository was checked out.
refNononeGit reference (e.g. branch name) from which the changes will be detected. This option is ignored if action is triggered by pull_request event.
baseNononeGit reference (e.g. branch name) against which the changes will be detected. Defaults to repository default branch (e.g. master). If it references same branch it was pushed to, changes are detected against the most recent commit before the push. This option is ignored if action is triggered by pull_request event.
filtersYesnonePath to the configuration file or YAML string with filters definition
list-filesNononeEnables 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' - Serialized 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.
initial-fetch-depthNo100How many commits are initially fetched from 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 different base branch.
predicate-quantifierNosomeallows to override the "at least one pattern" behavior: 'some' - file is included if it matches at least one pattern (default). 'every' - file is included only if it matches all of the patterns. 'some-with-excludes' - file is included if it matches at least one pattern and no negated pattern (the ones prefixed with '!').

Outputs

NameDescription
changesJSON array with names of all filters matching any of changed files

Read an output with ${{ steps.<step-id>.outputs.<name> }}; the step needs an id.

Examples

Run jobs only for changed folders

In a monorepo, expose which areas changed and gate later steps on the outputs.

name: Example
on:
  push:
    branches: [main]

permissions:
  contents: read
  pull-requests: read

jobs:
  example:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - name: Paths Changes Filter
        id: changes
        uses: dorny/paths-filter@v4
        with:
          filters: |
            backend:
              - 'backend/**'
            frontend:
              - 'frontend/**'
      - run: |
          echo "backend changed: ${{ steps.changes.outputs.backend }}"

Each example passed actionlint (syntax, expressions and the inputs it knows for this action). They were not run in a live repository, so replace placeholder values such as names, ARNs and paths with your own.

Something out of date or wrong? Report it on our Contact page. This page is rebuilt from the action's repository roughly once a week.