Check out Source Code

A job checks out project source code automatically – you do not have to specify this step explicitly in your Automation scripts.

The file system of a container that runs a particular job step has the following structure:

        /
        ├─── mnt
        │ └─── space
        │   ├─── share              // file share
        │   ├─── system             // non-user system files
        │   └─── work
        │     ├─── {git-repo-name}  // cloned git repository (working directory)
        │     ├─── ...              // other project repos (only if specified in the script)
        │     └─── ...
        ...
    

Before running user jobs, Automation runs a hidden "bootstrap" job that:

creates a disk volume,
clones the project sources from the Git server to the volume,
mounts the volume to the container. By default, the volume is mounted to /mnt/space:
- You can change the default location with the mountDir variable.
- Inside the mountDir, Automation creates the work directory – the parent directory for storing project sources (the default full path is /mnt/space/work).
- By default, the project sources location is /mnt/space/work/{git-repo-name}. Here {git-repo-name} stands for the project's Git repository name. It is also the container's default working directory. You can change the default path to the working directory using workDir.
- Automation checks out only the current repository revision – the one with the currently running .space.kts file. If needed, you can also fetch other branches and revisions from this repository.
- If you have a multi-repository project, you can set up Automation to check out other repositories as well.
- The volume also contains $mountDir/share: external storage used for file sharing.

Fetching other branches and revisions

When a script is started, Automation checks out only the actual repository revision – the one that contains the currently running .space.kts script. If your script requires other branches or revisions for its work, you can fetch them using the git item.

For example, we have a script that runs in the main branch and want to additionally fetch the release branch and git tags:

            job("Example") {
                git {
                    // fetch 'release' and tags to local history
                    refSpec {
                        +"refs/heads/release"
                        +"refs/tags/*:refs/tags/*"
                    }

                    // get the entire commit history
                    depth = UNLIMITED_DEPTH
                }
            }
        

refSpec tells Automation which repository branch or revision you want to fetch. You can use the Git refSpec map format, for example, refSpec = "refs/*:refs/*", specify the exact branch, for example, refSpec = "refs/heads/my-new-branch" or the exact revision, for example, refSpec = "aa47aa1261b43732".
depth specifies the depth of the repository commit history (the number of the last commits). The UNLIMITED_DEPTH value means that the checked-out repository will contain the entire commits history. The default depth is 1 – by default, the checked-out repository contains only the latest commit. The value larger than 1 specifies the exact number of last commits that must be fetched.

Checking out additional project repositories

If your project contains multiple project repositories and your Automation script requires them during run, you can check out these repositories as well. To do this, you should use the git item.

For example, let's assume your project has the main-repo repository with the .space.kts file and two other repos repo-2 and repo-3 that are required during the build. This is how we can check out these additional repositories:

            job("Example") {
                // check out repo-2 to /mnt/space/work/repo-2
                git("repo-2")

                // check out repo-3 to /mnt/space/work/thirdRepo
                git("repo-3") {
                    cloneDir = "thirdRepo"
                }

                container(displayName = "Show dirs", image = "openjdk:latest") {
                    shellScript {
                        content = """
                            echo Directory structure
                            ls -R /mnt
                            echo Working dir is
                            pwd
                        """
                    }
                }
                // Working dir is /mnt/space/work/main-repo
            }
        

git(...) tells Automation that we want to check out not only the main project repository (the one that contains the currently running .space.kts script file) but also another Git repository from the project. Note that the git item is specified on the job level. This means that all containers running inside this job will get the additional Git repository.
cloneDir specifies the checkout directory: Either an absolute path or a path relative to /mnt/space/work. By default, the checkout directory is /mnt/space/work/${repo-name}.
In our example, the /mnt/space/work directory will contain three sub-directories:
- /mnt/space/work/main-repo with the content of the main repository (the one with the currently running .space.kts).
- /mnt/space/work/repo-2 with the content of repo-2.
- /mnt/space/work/thirdRepo with the content of repo-3.
The working directory is /mnt/space/work/main-repo.

Checkout rules for additional repositories

Automation applies the following rules when checking out additional repositories:

Automation will try to check out the branch with the same name as the branch the running script belongs to. For example, you have two repositories: main-repo and repo-2. Both have two branches: main and my-feature. If you run the script in main-repo/my-feature, the job will check out the my-feature branch from the repo-2 (the latest revision). If you run the job in main-repo/main, it will check out repo-2/main.
If a branch with the same name is not found in the additional repository, the job will check out the main branch. For example, you have two repositories: main-repo with the main and my-feature branches and repo-2 with just the main branch. If you run the script in main-repo/my-feature, the job will check out the main branch from repo-2 (the last revision).

Fetching content of additional repositories

To fetch other branches or revisions of additional repositories, use refSpec:

                job("Example") {
                    git("repo-2") {
                        // fetch my-new-branch
                        refSpec = "refs/heads/my-new-branch"
                        // fetch the entire commit history
                        depth = UNLIMITED_DEPTH
                    }

                    // Here go job steps...
                }
            

refSpec tells Automation which repository branch or revision you want to fetch. You can use the Git refspec map format, for example, refSpec = "refs/*:refs/*", specify the exact branch, for example, refSpec = "refs/heads/my-new-branch" or the exact revision, for example, refSpec = "aa47aa1261b43732"
depth specifies the depth of the repository commit history (the number of the last commits). The UNLIMITED_DEPTH value means that the checked-out repository will contain the entire commits history. The default depth is 1 – by default, the checked-out repository contains only the latest commit. The value larger than 1 specifies the exact number of last commits that must be fetched.

Disabling checkout of source code

If a job is not supposed to anyhow work with the project code, you can disable cloning the project sources by setting cloneRepository = false. For example:

            job("Example") {
                cloneRepository = false
            }
        

This will reduce the job run time.

Last modified: 08 June 2021