JetBrains Space Help

Run a Job on Project Events

The default job trigger is gitPush: a job will start after a user pushes a commit to the project repository. You can limit the scope of gitPush so that it triggers not on any change in the project repository but only on changes in particular branches, directories, or files .

You can also add other job triggers:

To set triggers, you should use the startOn block.

Important: Once you add a trigger to the job, the default gitPush trigger will be disabled. To enable it back, you should use the enabled flag. For example:

job("Run gradle build on gitpush and at 08:00 AM UTC") { startOn { gitPush { enabled = true } schedule { cron("0 8 * * *") } } gradlew("build") }

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.

  1. Open the required project.

  2. On the project sidebar menu, choose Project Settings → Automation.

  3. In Repositories with enabled job triggers, disable triggers for the required repository.

Last modified: 12 January 2021