dorny/paths-filter: Conditional Jobs by Changed Paths

By Daniel Zoghalchali·Latchkey

paths-filter outputs which path groups changed so you can skip unrelated jobs.

Define named filters with path globs. The action sets a true/false output per filter you reference in if: conditions, ideal for monorepos.

Key inputs (with:)

• filters: YAML mapping of name to path globs.
• base: base ref to diff against.
• list-files: also output the changed file list.
• token: token for fetching the diff on PRs.

Example workflow

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

On any runner

This action runs on any runner. Latchkey managed runners run it unchanged, and skipping unrelated jobs saves minutes.

Pinning and supply-chain hygiene

A third-party action runs arbitrary code with access to your workflow token. Version tags are mutable, so @v4 can change under you without any commit in your repository.

# mutable: the tag can be repointed at any time
- uses: some/action@v4

# immutable: pin to the commit SHA, with the version in a comment
- uses: some/action@e2b3f4a5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1  # v4.1.2

Key takeaways

• Expose filter outputs from a job, then gate downstream jobs.
• Ideal for monorepos to avoid building everything.
• Use list-files when you need the actual changed paths.

Frequently asked questions

Related guides

References

• GitHub Actions documentation