Skip to content

Checkout Job Environment (all repos)

Exports the current state of the job's environment from every repository attached to the job's projects, whether or not this job changes anything in them.

Checkout Job Environment covers only the repositories the job's changesets touch. Reach for this one when the deployment needs more than that: an application whose configuration lives in a second repository, a build that needs a shared library tree, anything where a partial checkout would produce something that does not run.

The cost is time and disk. A project with a dozen repositories exports all twelve on every job, even when the changeset touched one file in one of them.

repositories attached to the project changed untouched untouched wrong environment filter this op: every repository scoped to the environment three of the four above Checkout Job Environment: changed only one of the four above both empty each destination folder before writing into it

No configuration

The op has no form. Opening it shows an empty data editor and nothing you type there is read.

Load Job Items into Stash has to run first. That op reads the job's changesets and works out which projects they belong to, and this op then takes every repository attached to those projects. Without it, or on a job that carries no changesets, the op logs a checkout for zero projects, reports success and writes nothing.

The op creates each destination folder itself, so the job home does not have to be there in advance. Init Job Home still belongs ahead of it: that op wipes the job home when it runs, and would throw this export away.

Which repositories are included

Every repository attached to a project the job involves, filtered on the repository's Environments field: a repository is exported when that field names the job's environment or is left at *. A repository restricted to environments this job is not running against is left out with no message.

The environment test is a partial one. The job's environment name is looked for anywhere inside the repository's environment list, so a repository scoped to PREPROD is also picked up by a job running in PRE. Environment names that are prefixes of one another catch people out here.

That filter is the only one. Change history plays no part.

Which tag is exported

One tag per repository, decided by the job's environment and the repository's Tags Mode setting:

Tags Mode Tag used
Only environment the environment name, for example PROD
Release + environment the release version, a dash, then the environment, 1.4.0-PROD, but only when the job carries exactly one release; with none or several, the plain environment name
Project + environment the plain environment name. The project prefix is not applied, here or on Checkout Job Environment

Both fallbacks are silent. You get a checkout from the PROD tag where you expected 1.4.0-PROD, and nothing in the log says a prefix was dropped, so check what a prefixed repository actually produced before building a rule on top of it.

Because this op reaches repositories the changesets never touched, a repository that was added to the project but never had its environment tags created stops the job with a message naming both the missing tag and the repository. That is the most common failure when switching a rule from the plain environment checkout to this one.

A tag that exists but holds no files is noted in the log and skipped, and that repository's destination folder is left exactly as it was.

Where the files land

One folder per repository, under the job directory:

<job_dir>/<project name>/<repository Relative path>

Relative path is the field on the repository resource, and a new repository starts with / in it. Left at / or emptied, that repository's contents go straight into <job_dir>/<project name> with no folder of their own.

With many repositories in one project, that matters more here than anywhere else. Two repositories both left at / resolve to the same destination, and since each export empties its destination before writing, the later one erases the earlier one. Give every repository in a project its own Relative path before using this op.

The .git directory is not copied. What you get is a plain file tree.

The destination is emptied first

Each destination folder is deleted and recreated before its repository is written into it. The empty-tag case above is the exception, and nothing is deleted there. Run this op before Checkout Job Items, never after, or the changed files are wiped out.

What the job log shows

Checking out environment for N project(s), then three entries per repository: one naming the tag, the project, the repository and the destination, one recording the git checkout into that destination, and Environment checkout of N item(s) completed with the file listing attached. The listings are readable from the job log in the monitor screen.

Rollback

No rollback behaviour of its own. On a rollback pass it runs again and rebuilds the same tree. Clear Run Rollback in the op properties if that is wasteful for your job.

Combining with other ops

Use it in place of Checkout Job Environment, not alongside it. Running both means the repositories with changes are exported twice.

The order around it is the same: Init Job Home, Load Job Items into Stash, this op, then Checkout Job Items for the changed files.

Afterwards, Rename Environment Items and Files resolves environment-marked names and Replace Strings fills in environment values. Then Ship File Remotely sends the tree.

When only one extra repository is needed rather than all of them, Checkout a git revision pulls a single one at a named reference and costs far less.

Example

A project whose runnable artifact needs both its own code and a shared configuration repository that this job never changes.

Init Job Home
Load Job Items into Stash
Checkout Job Environment (all repos)
Checkout Job Items
Replace Strings      Path ${job_dir}/myapp
Ship File Remotely   from ${job_dir}/myapp  to /opt/myapp