Check out Source Code

A job checks out project source code automatically, you don't have to specify this step explicitly in your Automation script. By default, the checked-out Git repository contains only the actual revision – the one with the currently running .space.kts script.

Where is project source code stored

When running a job, Automation checks out the Git repository to the working directory on the host machine: .../work/{git-repo-name}. Here {git-repo-name} is the project's Git repository name.
The exact location of the working directory depends on the host machine environment. Follow these links to get information on
- how project data is stored in a Docker container
- how project data is stored in a worker
You can always get the full path to the working directory using the JB_SPACE_WORK_DIR_PATH environment variable.
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, your Automation script can check out additional project repositories.
If your script requires Git repositories from other projects in Space, it can check them out as well.

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

Check out other repositories within a project

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

Suppose 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 = "amazoncorretto:17-alpine") {
        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 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).

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

Check out repositories from other projects

An Automation script in one project can check out Git repositories from other projects in Space. To do this:

Attach the required Git repository from another project to your current project. Learn more
Use the git item to reference the required repository in a job. You can work with the attached repository as with any other repository in your project (as described in the previous chapter).
job("Example") { // repo-from-another-project must be attached to the current project git("repo-from-another-project") container(displayName = "Run script", image = "ubuntu") { // here goes your script } }

Configure Git checkout with environment variables

In some cases, you might want to make changes into how Git checks out the project sources. For example, you might want to disable the Git LFS smudge (replacing large files with actual content), if particular large files are not required for the build.

To configure Git checkout, set Git environment variables using job.git.env. For example:

job("Example") {
    git {
        // Do not download large files
        env["GIT_LFS_SKIP_SMUDGE"] = "1"
    }

    // here go job steps
    // ...
}

Note that Automation also uses some of the Git environment variables for Git configuration, for example, GIT_SSH_COMMAND. In case of the conflict, variables provided in job.git.env override the default ones.

Disable 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 clone = false. For example:

job("Example") {
    git {
        clone = false
    }
}

This will reduce the job run time.

Last modified: 15 December 2023