dorny/paths-filter

Detect which parts of a monorepo changed and run only the affected jobs.

Community actionCategory: Utilities & ScriptingLatest v3View on GitHub

What it does

dorny/paths-filter matches the changed files against named filters you define and exposes a boolean output per filter. It is the common way to make a monorepo build only what changed.

Use the outputs in job or step if: conditions.

Usage

workflow (.yml)

jobs:
  changes:
    runs-on: ubuntu-latest
    outputs:
      api: ${{ steps.f.outputs.api }}
    steps:
      - uses: actions/checkout@v4
      - id: f
        uses: dorny/paths-filter@v3
        with:
          filters: |
            api:
              - 'services/api/**'
  api:
    needs: changes
    if: ${{ needs.changes.outputs.api == 'true' }}
    runs-on: ubuntu-latest
    steps:
      - run: echo build api

Inputs

Input	Description	Default	Required
`filters`	YAML mapping of filter name to path globs.	-	Yes
`base`	Base ref to diff against.	`event base`	No

Outputs

Output	Description
`<filter>`	true if any file matched that filter.
`changes`	JSON array of the filters that matched.

Notes

To gate whole jobs, expose the filter output as a job output and reference it in the dependent job's if:.

Common errors

Filters never matching on pull_request usually means the base ref is wrong; the defaults handle PRs, but a custom base can break it.

Security and pinning

Pin to a commit SHA.

Alternatives and related

tj-actions/changed-filesList the files changed in a push or pull request so later steps can run conditionally.

Frequently asked questions

How do I only build changed services in a monorepo?

Define a filter per service in paths-filter, expose the outputs as job outputs, and gate each service job with an if: on its filter.