The path-filtering orb is a very versatile orb that allows you to continue a pipeline based on the paths of changed files.
This article is to help show some examples of what can be achieved using the path filtering orb using some examples with links to each of the projects which have their own explanation of how they have been configured.
Example 1
This is a simple example showing how to use path filtering to pass a parameter to choose which jobs to run on the continuation config.
config.yml
version: 2.1setup: trueorbs:
path-filtering: circleci/path-filtering@0.0.2workflows:
setup-workflow:
jobs:
- path-filtering/filter:
base-revision: main
config-path: .circleci/continue-config.yml
mapping: |
project1/.* project-one true
project2/.* project-two true
project3/.* project-three true
shared-things/.* run-them-all truecontinue-config.yml
version: 2.1executors:
base:
docker:
- image: cimg/base:stableparameters:
project-one:
type: boolean
default: false
project-two:
type: boolean
default: false
project-three:
type: boolean
default: false
run-them-all:
type: boolean
default: false
jobs:
project_one:
executor: base
steps:
- run:
command: |
echo "project one"
project_two:
executor: base
steps:
- run:
command: |
echo "project two"
project_three:
executor: base
steps:
- run:
command: |
echo "project three"
all_projects:
executor: base
steps:
- run:
command: |
echo "all"
workflows:
build-1:
when:
or:
- << pipeline.parameters.project-one >>
- << pipeline.parameters.run-them-all >>
jobs:
- project_one
build-2:
when:
or:
- << pipeline.parameters.project-two >>
- << pipeline.parameters.run-them-all >>
jobs:
- project_two
build-3:
when:
or:
- << pipeline.parameters.project-three >>
- << pipeline.parameters.run-them-all >>
jobs:
- project_three
build-shared-other:
when: << pipeline.parameters.run-them-all >>
jobs:
- all_projectsThis example only uses two files and only allows you to choose which workflows to run based on the parameters that are set to true on the first config.yml. These are then checked when using the orb to run the continued config from the second config file.
Example 2
This second example uses mapping to allow multiple different continuation files to be used.
In this sample project's.circleci/config.yml, we "break" the path-filtering/filter job down, and add a step in the middle to choose the right continued config.
Based on the files which are changed only the matching continue-XXX.yml will run as it will be passed in as the config key.
Example 3
The final example implements both path filtering and config splitting.
The final example uses a list of directories, to detect which subdirectories (herein modules) have changed.
It will then fetch the path-to-module/.circleci/config.yml for each module to build, and merge all the fetched config.yml along with the config defining common resources, i.e., .circleci/config.yml and finally execute the merged config.
Other Considerations
It's important to note that base-revision dictates the branch by which the code changes are compared against. These changes are cumulative, so in a scenario where a branch with base-revision: main has had many commits and changes, you may find that more workflows are triggered than desired. If you want to see workflows triggered for new changes, consider setting base-revision: << pipeline.git.branch >> so that the branch pipeline compares the changes to itself.