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:
gitBranchDeleted
: a particular branch is deleted from the repository.codeReviewOpened
: someone creates a code review in the project.codeReviewClosed
: someone closes a code review in the project.schedule
: run a job regularly at the specified time (UTC).
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:
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 thetests
directory. Thesrc/tests/**
matches all files insidetests
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.
On the project sidebar menu, choose
.In Repositories with enabled job triggers, disable triggers for the required repository.