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 or 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:
base
input parameter must not be the same as the branch that triggered the workflowbase
input parameter is the same as the branch that triggered the workflow:base
input parameter is commit SHA:base
commitbase
input parameter is the same as the branch that triggered the workflow:base
input parameter is set to HEAD
- 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.
'
or "
. Otherwise, you will get an error if it starts with *
.git
binary.act -P ubuntu-latest=nektos/act-environments-ubuntu:18.04
ref
input parameterlist-files: csv
formatchanges
outputlist-files: shell
and list-files: escape
optionsFor 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: ''
'true'
- if any of changed files matches any of filter rules'false'
- if none of changed files matches any of filter rules${FILTER_NAME}_count
to the count of matching files.${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.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: ...
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 - ...
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 - ...
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 filters
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 filters
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 filters
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 filters
- uses: dorny/paths-filter@v2 id: filter with: # Path to file where filters are defined filters: .github/filters.yaml
- 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/**
- 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: *shared
- 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 }}
- 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 }}
The scripts and documentation in this project are released under the MIT License