GitHub Action that enables conditional execution of workflow steps and jobs, based on the files modified by pull request, on a feature branch, or by the recently pushed commits.
Run slow tasks like integration tests o 8000 r deployments only for changed components. It saves time and resources, especially in monorepo setups. GitHub workflows built-in path filters don't allow this because they don't work on a level of individual jobs or steps.
Real world usage examples:
- sentry.io - backend.yml
- GoogleChrome/web.dev - lint-workflow.yml
- blog post Configuring python linting to be part of CI/CD using GitHub actions - py_linter.yml
- Pull requests:
- Workflow triggered by pull_request or pull_request_target event
- Changes are detected against the pull request base branch
- Uses GitHub REST API to fetch a list of modified files
- Requires pull-requests: read permission
- Feature branches:
- Workflow triggered by push or any other event
- The
baseinput parameter must not be the same as the branch that triggered the workflow - Changes are detected against the merge-base with the configured base branch or the default branch
- Uses git commands to detect changes - repository must be already checked out
- Master, Release, or other long-lived branches:
- Workflow triggered by push event
when
baseinput parameter is the same as the branch that triggered the workflow:- Changes are detected against the most recent commit on the same branch before the push
- Workflow triggered by any other event
when
baseinput parameter is commit SHA:- Changes are detected against the provided
basecommit
- Changes are detected against the provided
- Workflow triggered by any other event
when
baseinput parameter is the same as the branch that triggered the workflow:- Changes are detected from the last commit
- Uses git commands to detect changes - repository must be already checked out
- Workflow triggered by push event
when
- Local changes
- Workflow triggered by any event when
baseinput parameter is set toHEAD - Changes are detected against the current HEAD
- Untracked files are ignored
- Workflow triggered by any event when
- uses: dorny/paths-filter@v2
id: changes
with:
filters: |
src:
- 'src/**'
# run only if some file in 'src' folder was changed
- if: steps.changes.outputs.src == 'true'
run: ...For more scenarios see examples section.
- Paths expressions are evaluated using picomatch library. Documentation for path expression format can be found on the project GitHub page.
- Picomatch dot option is set to true. Globbing will also match paths where file or folder name starts with a dot.
- It's recommended to quote your path expressions with
'or". Otherwise, you will get an error if it starts with*. - Local execution with act works only with alternative runner image. Default runner doesn't have
gitbinary.- Use:
act -P ubuntu-latest=nektos/act-environments-ubuntu:18.04
- Use:
- Add
refinput parameter - Add
list-files: csvformat - Configure matrix job to run for each folder with changes using
changesoutput - Improved listing of matching files with
list-files: shellandlist-files: escapeoptions - Paths expressions are now evaluated using picomatch library
For more information, see CHANGELOG
- uses: dorny/paths-filter@v2
with:
# Defines filters applied to detected changed files.
# Each filter has a name and a list of rules.
# Rule is a glob expression - paths of all changed
# files are matched against it.
# Rule can optionally specify if the file
# should be added, modified, or deleted.
# For each filter, there will be a corresponding output variable to
# indicate if there's a changed file matching any of the rules.
# Optionally, there can be a second output variable
# set to list of all files matching the filter.
# Filters can be provided inline as a string (containing valid YAML document),
# or as a relative path to a file (e.g.: .github/filters.yaml).
# Filters syntax is documented by example - see examples section.
filters: ''
# Branch, tag, or commit SHA against which the changes will be detected.
# If it references the same branch it was pushed to,
# changes are detected against the most recent commit before the push.
# Otherwise, it uses git merge-base to find the best common ancestor between
# current branch (HEAD) and base.
# When merge-base is found, it's used for change detection - only changes
# introduced by the current branch are considered.
# All files are considered as added if there is no common ancestor with
# base branch or no previous commit.
# This option is ignored if action is triggered by pull_request event.
# Default: repository default branch (e.g. master)
base: ''
# Git reference (e.g. branch name) from which the changes will be detected.
# Useful when workflow can be triggered only on the default branch (e.g. repository_dispatch event)
# but you want to get changes on a different branch.
# This option is ignored if action is triggered by pull_request event.
# default: ${{ github.ref }}
ref:
# How many commits are initially fetched from the 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 base branch (feature branch workflow).
# Default: 100
initial-fetch-depth: ''
# Enables 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' - File paths are formatted 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.
# Default: none
list-files: ''
# Relative path under $GITHUB_WORKSPACE where the repository was checked out.
working-directory: ''
# Personal access token used to fetch a list of changed files
# from GitHub REST API.
# It's only used if action is triggered by a pull request event.
# GitHub token from workflow context is used as default value.
# If an empty string is provided, the action falls back to detect
# changes using git commands.
# Default: ${{ github.token }}
token: ''- For each filter, it sets output variable named by the filter to the text:
'true'- if any of changed files matches any of filter rules'false'- if none of changed files matches any of filter rules
- For each filter, it sets an output variable with the name
${FILTER_NAME}_countto the count of matching files. - If enabled, for each filter it sets an output variable with the name
${FILTER_NAME}_files. It will contain a list of all files matching the filter. changes- JSON array with names of all filters matching any of the changed files.
Execute step in a workflow job only if some file in a subfolder is changed
jobs:
tests:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: dorny/paths-filter@v2
id: filter
with:
filters: |
backend:
- 'backend/**'
frontend:
- 'frontend/**'
# run only if 'backend' files were changed
- name: backend tests
if: steps.filter.outputs.backend == 'true'
run: ...
# run only if 'frontend' files were changed
- name: frontend tests
if: steps.filter.outputs.frontend == 'true'
run: ...
# run if 'backend' or 'frontend' files were changed
- name: e2e tests
if: steps.filter.outputs.backend == 'true' || steps.filter.outputs.frontend == 'true'
run: ...Execute job in a workflow only if some file in a subfolder is changed
jobs:
# JOB to run change detection
changes:
runs-on: ubuntu-latest
# Required permissions
permissions:
pull-requests: read
# Set job outputs to values from filter step
outputs:
backend: ${{ steps.filter.outputs.backend }}
frontend: ${{ steps.filter.outputs.frontend }}
steps:
# For pull requests it's not necessary to checkout the code
- uses: dorny/paths-filter@v2
id: filter
with:
filters: |
backend:
- 'backend/**'
frontend:
- 'frontend/**'
# JOB to build and test backend code
backend:
needs: changes
if: ${{ needs.changes.outputs.backend == 'true' }}
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- ...
# JOB to build and test frontend code
frontend:
needs: changes
if: ${{ needs.changes.outputs.frontend == 'true' }}
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- ...Use change detection to configure matrix job
jobs:
# JOB to run change detection
changes:
runs-on: ubuntu-latest
# Required permissions
permissions:
pull-requests: read
outputs:
# Expose matched filters as job 'packages' output variable
packages: ${{ steps.filter.outputs.changes }}
steps:
# For pull requests it's not necessary to checkout the code
- uses: dorny/paths-filter@v2
id: filter
with:
filters: |
package1: src/package1
package2: src/package2
# JOB to build and test each of modified packages
build:
needs: changes
strategy:
matrix:
# Parse JSON array containing names of all filters matching any of changed files
# e.g. ['package1', 'package2'] if both package folders contains changes
package: ${{ fromJSON(needs.changes.outputs.packages) }}
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- ...Pull requests: Detect changes against PR base branch
on:
pull_request:
branches: # PRs to the following branches will trigger the workflow
- master
- develop
jobs:
build:
runs-on: ubuntu-latest
# Required permissions
permissions:
pull-requests: read
steps:
- uses: actions/checkout@v3
- uses: dorny/paths-filter@v2
id: filter
with:
filters: ... # Configure your filtersFeature branch: Detect changes against configured base branch
on:
push:
branches: # Push to following branches will trigger the workflow
- feature/**
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
with:
# This may save additional git fetch roundtrip if
# merge-base is found within latest 20 commits
fetch-depth: 20
- uses: dorny/paths-filter@v2
id: filter
with:
base: develop # Change detection against merge-base with this branch
filters: ... # Configure your filtersLong lived branches: Detect changes against the most recent commit on the same branch before the push
on:
push:
branches: # Push to the following branches will trigger the workflow
- master
- develop
- release/**
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: dorny/paths-filter@v2
id: filter
with:
# Use context to get the branch where commits were pushed.
# If there is only one long-lived branch (e.g. master),
# you can specify it directly.
# If it's not configured, the repository default branch is used.
base: ${{ github.ref }}
filters: ... # Configure your filtersLocal changes: Detect staged and unstaged local changes
on:
push:
branches: # Push to following branches will trigger the workflow
- master
- develop
- release/**
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
# Some action that modifies files tracked by git (e.g. code linter)
- uses: johndoe/some-action@v1
# Filter to detect which files were modified
# Changes could be, for example, automatically committed
- uses: dorny/paths-filter@v2
id: filter
with:
base: HEAD
filters: ... # Configure your filtersDefine filter rules in own file
- uses: dorny/paths-filter@v2
id: filter
with:
# Path to file where filters are defined
filters: .github/filters.yamlUse YAML anchors to reuse path expression(s) inside another rule
- uses: dorny/paths-filter@v2
id: filter
with:
# &shared is YAML anchor,
# *shared references previously defined anchor
# src filter will match any path under common, config and src folders
filters: |
shared: &shared
- common/**
- config/**
src:
- *shared
- src/**Consider if file was added, modified or deleted
- uses: dorny/paths-filter@v2
id: filter
with:
# Changed file can be 'added', 'modified', or 'deleted'.
# By default, the type of change is not considered.
# Optionally, it's possible to specify it using nested
# dictionary, where the type of change composes the key.
# Multiple change types can be specified using `|` as the delimiter.
filters: |
shared: &shared
- common/**
- config/**
addedOrModified:
- added|modified: '**'
allChanges:
- added|deleted|modified: '**'
addedOrModifiedAnchors:
- added|modified: *sharedPassing list of modified files as command line args in Linux shell
- uses: dorny/paths-filter@v2
id: filter
with:
# Enable listing of files matching each filter.
# Paths to files will be available in `${FILTER_NAME}_files` output variable.
# Paths will be escaped and space-delimited.
# Output is usable as command-line argument list in Linux shell
list-files: shell
# In this example changed files will be checked by linter.
# It doesn't make sense to lint deleted files.
# Therefore we specify we are only interested in added or modified files.
filters: |
markdown:
- added|modified: '*.md'
- name: Lint Markdown
if: ${{ steps.filter.outputs.markdown == 'true' }}
run: npx textlint ${{ steps.filter.outputs.markdown_files }}Passing list of modified files as JSON array to another action
- uses: dorny/paths-filter@v2
id: filter
with:
# Enable listing of files matching each filter.
# Paths to files will be available in `${FILTER_NAME}_files` output variable.
# Paths will be formatted as JSON array
list-files: json
# In this example all changed files are passed to the following action to do
# some custom processing.
filters: |
changed:
- '**'
- name: Lint Markdown
uses: johndoe/some-action@v1
with:
files: ${{ steps.filter.outputs.changed_files }}- test-reporter - Displays test results from popular testing frameworks directly in GitHub
The scripts and documentation in this project are released under the MIT License