Checkout Job Items

Writes the files that the job's changesets touch into the job directory, one file at a time, and records the revisions they came from against the job.

This is the narrow checkout: only the items that changed, at the revision the changeset points at. Its companion Checkout Job Environment writes the full contents of the environment instead. Rules that deploy a delta run the environment checkout first and this op second, so the changed files land on top of an otherwise complete tree.

No configuration

The op has no form. Opening it gives you a free-form YAML editor in its place, and whatever you type there is stored with the op and then never read, because the op takes nothing from its own configuration. Everything it does comes from what earlier ops left in the stash.

Load Job Items into Stash is what fills that in. Without it there are no items, the op writes nothing, reports success and logs a checkout of zero items. That is the single most common reason a rule produces an empty job directory.

The op creates every directory it writes into, so it runs perfectly well without Init Job Home ahead of it. What that op contributes is an emptied job directory, which is what stops anything left by an earlier run from sitting underneath the files written here.

Where the files land

Each file is written under the job directory, to a path built from the project name, the repository's Relative path and the path the file has inside the repository:

<job_dir>/<project name>/<relative path>/<path inside the repository>

A repository resource created through its form carries / in Relative path, and that middle part then collapses to nothing, so the files land directly under the project folder and the repository name appears nowhere:

/opt/clarive/jobs/PROD-234/myapp/src/foo.java

Put a folder name in Relative path and it becomes a level of its own, which is how you keep two repositories in the same project from writing over each other. Leave the field completely empty and the repository resource's name is used instead.

Intermediate directories are created as needed, and each file is given the permission bits it carries in the repository. A file held as a symbolic link is restored as a link rather than copied as content. The repository's .git directory is never written.

Files attached to the changeset topic come out here as well, under the project name and the Checkout directory set on the field holding them. They are not repository content, so no revision is recorded for them and they never appear as deletions.

Deleted items are deleted

An item the changeset marks as deleted does not produce a file. It removes the file at that path from the job directory instead.

The removal only matters when something put the file there first. Run this op after Checkout Job Environment and the job directory ends up holding exactly what the environment will look like once the changeset is applied, deletions included. Run it on its own and the delete has nothing to remove and quietly does nothing.

Unlike the environment checkout

The environment checkout empties its destination folder before writing. This op does not. It writes and deletes file by file, leaving everything else in the job directory alone, which is what makes the two safe to run one after the other in that order.

Reversing the order wipes out the item checkout.

What the job log shows

One entry per run: Checked out N item(s) to the job directory, ending with a sha: list in brackets. Read that list as the repositories the items came from, not as commits. It holds the ids of the repository resources involved, one per repository, whatever the label says.

Attached to the entry is a list with one line per file, each prefixed with its change status and followed by its version, in the form (A) /myapp/src/foo.java (1). A version shown as (1 {PROD}) is an environment-specific variant of the file.

A file whose content cannot be found in the repository logs a warning and the op continues, leaving that one file missing from the job directory. Anything else that goes wrong stops the job, part way through, with the files written up to that point still on disk.

Revisions recorded on the job

Once the last file is written, every commit that contributed one is registered against the job. Only items that came out of a repository count, and only those carrying a commit of their own. That record is what the environment tagging ops read later, and what the job detail screen shows as the revisions deployed.

The registration happens at the end rather than file by file, so a failure part way through leaves files on disk with no revisions recorded against the job at all.

Rollback

The op has no rollback behaviour of its own. On a rollback pass it runs again and writes whatever items are in the stash at that point, which for a straightforward rule is the same set of files it wrote going forward. That is usually harmless, because the job directory is scratch space. Clear Run Rollback on the op's Options tab if you would rather it did not.

Combining with other ops

The standard deployment sequence is Init Job Home, Load Job Items into Stash, Checkout Job Environment, then this op.

Follow it with Rename Environment Items and Files when your repositories carry environment markers in file names, then Load Nature Items to classify what was checked out, then Replace Strings to fill in environment values, then Ship File Remotely to move the result onto the nodes.

When you want the repository itself rather than the files, including its history, use Checkout a git revision.

To act only when there is something to deploy, test the item list with IF var condition THEN before this op runs.

Example

A minimal item-only deployment. The op needs nothing configured; the ops around it do the work.

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