paths-filter
paths-filter is a GitHub Action that conditionally runs workflow steps based on which files changed in a pull request or commit. It lets teams skip expensive operations like tests or deployments when irrelevant files are modified, saving CI/CD time especially in monorepos.
Key facts
Objective fields from the source. Values we can't verify are shown as “Unknown” rather than guessed.
| Field | Value |
|---|---|
| Repository | dorny/paths-filter |
| Owner | dorny |
| Primary language | TypeScript |
| License | MIT — OSI-approved |
| Stars | 3.2k |
| Forks | 377 |
| Open issues | 34 |
| Latest release | v4.0.2 (2026-07-02) |
| Last updated | 2026-07-03 |
| Source | https://github.com/dorny/paths-filter |
What paths-filter is
TypeScript-based GitHub Action that detects file changes using GitHub REST API (for PRs) or git commands (for branches), matches them against user-defined glob filters via picomatch, and exposes boolean and file-list outputs for conditional job/step execution. Supports pull_request, push, merge_group, and custom events.
Get the paths-filter source
Clone the repository and explore it locally.
git clone https://github.com/dorny/paths-filter.gitcd paths-filter# follow the project's README for install & configurationNeed it deployed, integrated, or customized instead? DEV.co ships production installs.
Best use cases
Implementation considerations
- Filters are specified as YAML glob expressions using picomatch; test glob patterns carefully, especially with dot files (enabled by default).
- Requires explicit `pull-requests: read` permission for PR workflows; git checkout must happen before the action runs for branch-based detection.
- Output is available as step outputs (e.g., `steps.changes.outputs.src`); use `id:` on the action step to reference them downstream.
- Git history may need to be fetched in shallow clones; initial fetch count is configurable and will auto-scale if merge-base not found.
- In container jobs, `git dubious ownership` errors are handled automatically; ensure safe.directory is set if using custom credential storage.
When to avoid it — and what to weigh
- Simple single-service repos — Overhead of defining and maintaining filters may outweigh benefit if your repository structure is flat or rarely skips work.
- Workflows already using native GitHub path filters — If you only need to skip entire workflow runs (not individual jobs/steps), GitHub's built-in `paths:` filter is simpler.
- Non-GitHub CI/CD systems — This is GitHub Actions–specific; GitLab CI, Jenkins, or other platforms require alternative solutions.
- Complex change detection logic — If your filter rules are highly interdependent or require custom scripting beyond glob matching, consider a bespoke solution.
License & commercial use
MIT License (MIT). Permissive open-source license allowing commercial use, modification, and distribution with attribution.
MIT is a standard permissive OSI license. Commercial use is permitted. No proprietary restrictions, though attribution is required per license terms. Review your legal/compliance policy for any internal governance requirements, but no licensing barrier exists.
DEV.co evaluation signals
Editorial assessment — not user reviews. Directional, with an explicit confidence level.
| Signal | Assessment |
|---|---|
| Maintenance | Active |
| Documentation | Strong |
| License clarity | Clear |
| Deployment complexity | Low |
| DEV.co fit | Good |
| Assessment confidence | High |
Action uses GitHub REST API (pull_request mode) or git commands (branch mode); requires appropriate token scope (`pull-requests: read` for PRs). No code execution in matched files. Glob matching is performed on file paths only, not file contents. Repository must be already checked out by upstream step. Automatic handling of git safe.directory in containers mitigates ownership-based attacks. No known vulnerabilities logged in data provided.
Alternatives to consider
GitHub's native `paths:` filter in `on:` triggers
Simpler for whole-workflow filtering; cannot conditionally skip individual jobs or steps; less granular but zero configuration.
Manual git diff scripting in workflow step
Full control over change detection logic; more verbose and error-prone; no pre-built reliability or edge-case handling.
Third-party CI/CD platforms (GitLab CI, CircleCI, Jenkins)
If locked into non-GitHub infrastructure; each has native change detection; requires retraining on platform-specific syntax.
Build on paths-filter with DEV.co software developers
Integrate paths-filter into your workflow to run only the jobs that matter for each commit. Start with a free setup consultation.
Talk to DEV.coRelated open-source tools
Surfaced by semantic similarity across the DEV.co open-source index.
Related on DEV.co
Explore the category and the services that help you build with it.
paths-filter FAQ
Does paths-filter work with pull_request_target?
Can I use paths-filter to conditionally run entire workflows, not just steps?
What glob syntax does paths-filter support?
Does the action work in shallow clones or with fetch-depth?
Custom software development services
From first prototype to production, DEV.co delivers software development services around tools like paths-filter. Our software development agency staffs experienced software developers and web developers for custom software development, web development, integrations, and ongoing support across open-source devops and beyond.
Reduce CI/CD runtime with intelligent file-based job triggers
Integrate paths-filter into your workflow to run only the jobs that matter for each commit. Start with a free setup consultation.