Paths Filter
A GitHub Action that conditionally runs workflow steps and jobs based on changed files in PRs, feature branches, or pushes.
What is Paths Filter?
Paths Changes Filter is a GitHub Action that conditionally executes workflow steps or jobs based on which files have been modified in a pull request, feature branch, or push. It solves the problem of running slow tasks like integration tests or deployments only for changed components, saving time and resources, especially in monorepo setups where GitHub's built-in path filters are insufficient.
Developers and DevOps engineers managing CI/CD pipelines on GitHub, particularly those working with monorepos or complex projects where selective testing and deployment are needed.
It provides granular control over workflow execution beyond GitHub's native path filters, supports multiple Git workflows, and integrates seamlessly with existing actions to optimize CI/CD efficiency and reduce costs.
Overview
Conditionally run actions based on files modified by PR, feature branch or pushed commits
Use Cases
Best For
- Optimizing CI/CD pipelines in monorepos by running tests only for changed packages
- Conditionally deploying services based on modified directories
- Running linters or formatters only on relevant changed files
- Reducing GitHub Actions minutes by skipping unnecessary jobs
- Configuring matrix jobs to build and test only modified components
- Detecting changes in feature branches against a base branch for selective testing
Not Ideal For
- Projects using CI/CD platforms other than GitHub Actions, such as GitLab CI or Jenkins
- Simple repositories with flat directory structures where all changes uniformly impact the codebase
- Workflows requiring detection of changes in untracked or Git-ignored files, as it only considers committed changes
Pros & Cons
Pros
Allows defining filters with picomatch glob patterns and file change types (added/modified/deleted), enabling precise control over workflow steps. Evidence from README's filter syntax and advanced options examples.
Supports pull requests, feature branches, merge queues, and long-lived branches with tailored detection methods. Evidence from the 'Supported workflows' section detailing different event configurations.
Outputs matching files as CSV, JSON, or shell-escaped lists via the list-files option, facilitating downstream processing. Evidence from parameter descriptions and custom processing examples.
Integrates with matrix jobs to run only for changed folders using the changes JSON output, reducing resource waste in monorepos. Evidence from examples showing matrix job configuration.
Cons
Exclusively designed for GitHub Actions, making it unusable for teams on other CI/CD platforms like GitLab or Jenkins, limiting portability.
Requires careful setup of base, ref, and filter parameters across different Git events, which can be error-prone and steep to learn. Evidence from detailed usage notes and multiple scenario examples.
Major releases, such as v4's update to Node 24, introduce breaking changes that necessitate workflow adjustments, as noted in the 'What's New' section.
Frequently Asked Questions
Related Projects
action-tmateDebug your GitHub Actions via SSH by using tmate to get access to the runner system itself.
Setup ssh-agentGitHub Action to setup `ssh-agent` with a private key
GitHub Actions to compile LaTeX documents:octocat: GitHub Action to compile LaTeX documents
Run your job on another architecture: arm32, aarch64 and othersA Github Action that executes jobs/commands on non-x86 cpu architectures (ARMv6, ARMv7, aarch64, s390x, ppc64le, riscv64) via QEMU
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.