Reusable CircleCI command to halt if no changed target files

I want to skip unnecessary CircleCI jobs with GitHub, when I change nothing in source code. For instance, consider if we modify only README documentation in a pull request. Do we need to run all unit tests? I don’t think so. Actually, CircleCI provides conditional steps, but it doesn’t work with such a dynamical condition. So, in this article, I describe a way to halt CircleCI jobs if target files are not changed. We will follow the three steps.

1. Implement a bash script to find changed files
2. Implement a reusable CircleCI command to find changed files
3. Call the CircleCI command in CircleCI jobs

First, we implement a bash script to find changed files based on the github commits. The script receives an argument for a regular expression pattern. We can select files with it. By doing that, we can identify if target files are changed or not. For instance, when patterns is ^src/ , the script enables us to select only changed files in ./src directory.

ci/get_change_files.sh

Second, we implement a reusable CircleCI command. It enables us to easily add steps to halt if target files are not changed in GitHub. If you are not familiar with executors and commands of CircleCI, the official documentation would be helpful.

The code below is a part of CircleCI config which is located at .circleci/config.yml . We implement a reusable CircleCI command whose name is check-diff-files-to-halt . In the command, parameters.pattern is a variable to specify a regular expression as string. The value is passed to the bash script we implemented above with << parameters.pattern >>. Moreover, if no files whose name match the pattern exist, it halts a CircleCI job. circleci step halt enables us to stop a CircleCI job with success status.

Parts of CircleCI config

Third, as you can see the bottom of the gist above, we can call check-diff-files-to-halt as a step of a CircleCI job. Just two lines! When we have a multiple CircleCI jobs and we don’t want to consume time with unnecessary unit tests and so on, the reusable command would be very useful.