Run a Job on Project Events

Triggering a job run on changes in certain branches, directories, or files

The branchFilter and pathFilter methods of the gitPush trigger let you fine tune the trigger run conditions. Instead of running a job on any change in the project repository, you can configure the trigger so that it will run the job only on changes in particular repository branches, directories, and even files.

branchFilter lets you specify certain branches:

• The job will run if at least one branch matches the specified filter.

• The filter supports the include (+) and exclude (-) rules.

• You can use asterisk (*) wildcards, e.g. +"refs/heads/release-*".

• The filter supports Kotlin regular expressions (Regex), e.g. +Regex("\brelease\b").

• Exclude rules have priority over include rules.

• For example:

  job("Run on git push") { startOn { gitPush { branchFilter { // add 'main' +"refs/heads/main" // add all branches containing 'feature' +Regex("feature") // exclude 'test-feature' -"refs/heads/test-feature" } } } }

• If you have only one filter rule, you can use the branchFilter property instead of the function, e.g. branchFilter = "refs/heads/*". It accepts only include rules.

pathFilter lets you specify paths to certain directories and files:

• The job will run if at least one file matches the specified filter.

• The filter supports the include (+) and exclude (-) rules.

• You should specify path relative to the working directory.

• You can use asterisk (*) wildcards for matching the files only inside the current directory and double-asterisk (**) for a recursive match. For example, src/tests/* matches all files inside the tests directory. The src/tests/** matches all files inside tests and all its subdirectories.

• A more specific path has priority over less specific paths, e.g. +"src/tests/MyTests.kt" has priority over -"src/tests/**".

• For example:

  job("Run on git push") { startOn { gitPush { branchFilter { +"refs/heads/main" } pathFilter { // include all from 'targets' directory +"targets/**" // exclude 'targets/main' directory -"targets/main/**" // include all 'Main.kt' files in the project // As this rule is more specific, // 'Main.kt' will be included even if // it's located in 'targets/main' +"**/Main.kt" } } } }

• Automation will ignore the pathFilter and run the job in the following cases:

  • the push contains more than 250 commits,

  • more than 10000 files were changed,

  • the push contains commits with more than 1000 changed files.

Disabling job triggers in a particular repository

In some cases, you may need to disable automatic job triggers for a particular repository. For example, when you mirror a repository in another project: 'git push' will run Automation jobs not only in the main repository but in its mirror as well.