Trigger Job Run

Automation supports the following job triggers:

Trigger	Description
`gitPush`	Enabled by default. Run a job 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, tags, 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.
`gitBranchDeleted`	Run a job after a particular branch is deleted from the repository.
`codeReviewOpened`	Run a job after a code review is created in the project. Works only in the project's default branch (`main`).
`codeReviewClosed`	Run a job after a code review is closed in the project. Works only in the project's default branch (`main`).
`schedule`	Run a job regularly at the specified time (UTC). Works only in the project's default branch (`main`).

Set job triggers

To set triggers, you should use the job's startOn block.

Important: Once you add any trigger to the job, the default gitPush trigger will be disabled. To enable it back, you must explicitly specify 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("openjdk:11", "build")
            }
        

gitPush. Track branches, directories, files, and tags

Instead of running a job on any change in the project repository, you can configure the gitPush trigger so that it will run the job:

On changes in particular repository branches (gitPush.branchFilter).
On tagging a commit with particular tags (gitPush.tagFilter).
On changes in particular directories and files (gitPush.pathFilter).

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").
The filter supports all reference types. For example, with +"refs/merge/*" you can run a job every time a merge request has updates.
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 tag

tagFilter lets you specify certain Git tags. For example, the job below will run only if someone pushes a commit tag that starts with release/, e.g. release/v1.0:

                job("Run only with release tags") {
                    startOn {
                        gitPush {
                            // run only if there's a release tag
                            // e.g., release/v1.0.0
                            tagFilter {
                                +"release/*"
                            }
                        }
                    }

                    // here go job steps...
                }
            

tagFilter supports the following filtering rules:

The job will run if at least one tag matches the specified filter.
The filter supports the include (+) and exclude (-) rules.
You can use asterisk (*) wildcards, e.g. +"version*".
The filter supports Kotlin regular expressions (Regex), e.g. +Regex("\bversion\b").
Exclude rules have priority over include rules.
For example:
job("Run on git push") { startOn { gitPush { tagFilter { // add all tags starting with 'version1.' +"version1.*" // exclude tags containing 'beta' // e.g. 'version1.0-beta' will be excluded -Regex("beta") } } } // here go job steps... }

Filter by path

pathFilter lets you specify paths to certain directories and files. For example, the job below will run only if there is a change in the Main.kt file:

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

                    // here go job steps...
                }
            

You can use pathFilter to fine-tune branchFilter or tagFilter: Automation first checks if there's a change in a particular branch or if a particular tag is applied and only then it applies a pathFilter. If branchFilter is not specified, pathFilter works only within the current branch (the one with the committed changes).

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 { // run only on changes in 'main' branchFilter { +"refs/heads/main" } pathFilter { // include all from 'targets' dir +"targets/**" // exclude 'targets/main' dir -"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" // include all '.java' files from the 'common' dir +"common/**/*.java" } } } // 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.

gitPush. Track changes in other project repositories

Sometimes, you might 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.

View 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.

Disable job triggers in a particular repository

In some cases, you might 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.
Open the Jobs page and click Settings.
In Job Triggers, disable triggers for the required repository.

Last modified: 23 September 2022