Trigger Job Run

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. If you have a multi-repository project, you can set up the gitPush trigger to run a job on changes in a particular repository.

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:

        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.

Filter by branch

By default, when a commit is pushed to the repository, Automation tries to run a job from the .space.kts file in the same branch where the changes were committed. For example, if you push changes to the cool-feature branch, Automation will try running a job from the .space.kts file in this revision in the cool-feature branch.

branchFilter lets you specify the list of branches where Automation should run the script. For example, the following job will run only on changes in the my-feature branch:

                job("Run only in my-feature") {
                    startOn {
                        gitPush {
                            branchFilter {
                                +"refs/heads/my-feature"
                            }
                        }
                    }

                    // here go job steps...
                }
            

If a change is pushed to the my-feature branch, this job will start in the my-feature but not in the main or any other branch.

If a change is pushed to the main branch, none of the jobs will start – Automation will try to run the script in the main branch, but it has the branchFilter that prevents this.

branchFilter supports the following filtering rules:

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" } } } // here go job steps... }
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.

Filter by path

pathFilter lets you specify paths to certain directories and files. As well as the branchFilter, pathFilter works only within the current branch (the one with the committed changes). For example, you have a repository with main and my-feature branches. Both branches have the same .space.kts:

                job("Run on change in Main.kt") {
                    startOn {
                        gitPush {
                            pathFilter {
                                +"Main.kt"
                            }
                        }
                    }

                    // here go job steps...
                }
            

In this case, a change in Main.kt in the my-feature branch, will trigger job run in the my-feature branch but not in the main branch and vice versa.

pathFilter supports the following filtering rules:

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" } } } // here go job steps... }
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.

Triggering a job run on changes in certain project repositories

Sometimes, you may need to configure complex builds that use source code from several project repositories. For example, you can even create a separate repository that will contain all build scripts while other repositories will have no .space.kts files at all.

The repository property of the gitPush trigger lets you specify the repository where a job should track changes. For example, you have a project with two repositories: first-repository and second-repository. The .space.kts script is located in first-repository and you want Automation to trigger the script on changes in second-repository:

            job("Run on change in second-repository") {
                startOn {
                    gitPush {
                        repository = "second-repository"
                    }

                    // if you also want to run the job
                    // on changes in the current repo (first-repository)
                    // add the following line
                    gitPush {}
                }

                // check out the content of second-repo
                // as this won't happen automatically
                git("second-repository")

                // here go job steps...
            }
        

But in which branch of first-repository will the .space.kts script run when a commit is pushed to some branch of second-repository? In this case, Automation will try to match branches – Automation will search first-repository for the branch that has the same name as the one where the commit was pushed. For example, the second-repository gets a commit to the my-feature branch. If first-repository has the my-feature branch with the .space.kts script in it, this script will be started.

Similarly, if second-repository gets a commit to the main branch, the script from the first-repository/main branch will be started.

If second-repository gets a new branch that does not exist in the first-repository, Automation will try running the script from the first-repository/main branch. So, the main branch works as some kind of a fall-back branch.

If you don't want the main branch to work as a fall-back branch or want Automation to run scripts only in particular branches, you can add a branchFilter (or a pathFilter for tracking changes by particular path). For example, to run jobs only on commits to the main repository:

            job("Run on change in second-repository / main branch") {
                startOn {
                    gitPush {
                        repository = "second-repository"
                        branchFilter = "refs/heads/main"
                    }
                }

                git("second-repository")

                // here go job steps...
            }
        

What if a commit is pushed to the second-repository/my-feature branch but the first-repository/my-feature branch doesn't have the .space.kts script (or the script doesn't have the repository="second-repository" trigger)? Then, Automation will not trigger any job runs as there is nothing to run.

Viewing multi-repository builds in the Jobs page

The jobs that reference other repositories are called cross-referenced jobs. If you open the Jobs page for the repository that contains cross-referenced jobs, you will see no difference between cross-referenced and "regular" jobs.

But if you switch the Jobs to the repository that was referenced by a job from other repository, you will see the list of Cross-referenced jobs.

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.

Open the required project.
On the project sidebar menu, choose Project Settings → Automation.
In Enable/disable job triggers for project repositories, disable triggers for the required repository.

Last modified: 15 March 2021