Checkout Job Environment

Exports the current state of the job's environment into the job directory, one folder per repository that the job's changesets touch. What you get is the tree as the environment has it right now, before this job changes anything.

Pair it with Checkout Job Items, which writes the changed files on top of that tree. The environment checkout gives you a complete deployable, the item checkout gives you the delta, and running the two in that order gives you a complete deployable with this job's changes folded in.

To pull in every repository attached to the project rather than only the ones with changes, use Checkout Job Environment (all repos).

No configuration

The op has no form. Opening it shows an empty data editor and nothing you type there is read. It works entirely from the job's environment and from what earlier ops left in the stash.

Load Job Items into Stash has to run first. It is what works out which projects and repositories the job involves. Without it the op logs a checkout for zero projects, reports success and writes nothing. A project that reached the stash with no repository changes attached to it is passed over without a line in the log.

The job needs a job directory, which is what Init Job Home is for. When ${job_dir} is empty the op stops the job before exporting anything.

Which tag is exported

The job runs against one environment, and that name is turned into a tag in each repository. How depends on the Tags Mode setting on the repository resource:

Tags Mode	Tag used
Only environment	the environment name on its own, for example PROD
Release + environment	the release version, a dash, then the environment: 1.4.0-PROD
Project + environment	the project name, a dash, then the environment: myapp-PROD

Only environment is the default on a new repository resource.

The tag has to exist. A repository whose tags were never created stops the job with an error naming the tag and the repository, which is the usual symptom of a repository that has not had its environment tags set up.

A tag that exists but holds no files is skipped. The job log records a completed checkout of zero items for that repository, and the destination folder is left exactly as it was, because the delete step described below only runs when there are files to write.

Where the files land

One folder per repository, under the job directory:

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

The Relative path here is the field on the repository resource. A new repository resource starts with / in that field, and both / and an empty value collapse to nothing, so the repository's contents go straight into <job_dir>/<project name> with no folder of their own.

That default catches people out. Two repositories in the same project, both left on /, resolve to the same destination, and because each export empties its destination first, the second one wipes the first. Give every repository in a project a distinct Relative path whenever the project has more than one.

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

The destination is emptied first

Once the tag is known to hold files, the destination folder is deleted and recreated before anything is written. Whatever was already sitting there, from an earlier op or an earlier checkout in the same job, is gone.

This is why the order matters: run the environment checkout first, then Checkout Job Items on top. Reverse them and the item checkout is erased.

What the job log shows

Checking out environment for N project(s) at the start. Then, for each repository, an entry naming the tag, the project, the repository and the destination folder, a git line recording the tag and the folder it was unpacked into, and Environment checkout of N item(s) completed with the full file listing attached. The listing is readable from the job log in the monitor screen.

The count in the last line is the number of entries in the tag, directories included, so it runs higher than the number of files you end up with.

Rollback

The op has no rollback behaviour of its own, and it does not mark the job as needing a rollback pass. If some other op triggers one, this op runs again and rebuilds the same tree, which is usually harmless since the job directory is scratch space. Clear Run Rollback on the op's Options tab to stop that.

Combining with other ops

The usual order is Init Job Home, Load Job Items into Stash, this op, then Checkout Job Items.

After the checkout, Rename Environment Items and Files resolves environment-marked file names, Replace Strings fills in environment values, and Ship File Remotely moves the tree onto the nodes.

Use Checkout Job Environment (all repos) instead when the deployment needs repositories that this job does not change. Use Checkout a git revision when you need a specific branch or commit rather than the environment.

Example

A full-tree deployment where the environment contents plus this job's changes are packaged and sent.

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