Skip to content

Init Job Home

Makes the job's own working directory exist and start out empty. Everything a job writes to disk on the server goes under that directory, so this op belongs near the top of the rule, in the INIT step and ahead of any checkout.

The path is already in the stash as ${job_dir} from the moment the job starts, whether or not this op runs. What this op adds is the directory itself. On a forward run it wipes the contents of an existing directory so the job starts from a clean tree. On a rollback run it wipes nothing, because the rollback needs the files the forward run left behind.

job mode forward / rollback forward rollback missing: create it already there: empty it leave everything in place, fail if it is gone rest of the rule writes into ${job_dir}

Configuration

This op has no configuration form. Its config tab is a free-form YAML editor instead, and keys you put there are handed to the op and never read, so the editor is not a way to change any of the behaviour below.

The op does declare job_dir as a variable it provides, which is why later ops writing ${job_dir} are not flagged as using an unknown variable when the rule is checked.

Where the job directory lives

The directory is one folder per job, named after the job, inside the server's jobs root:

<jobs root>/<job name>

The jobs root comes from the job_dir setting in the configuration file. With that unset, CLARIVE_JOBDIR from the server environment is used, and with neither it is a jobs folder in the Clarive base directory. See environment variables for how the environment side is set.

The job name is whatever the job mask produced, PROD-123 with the default mask of environment plus job id. A mask that includes the prefix placeholder gets N for a promote or static job and B for a demote, which is where old-style names like N.PROD-0000000123 come from. See Config the job ID mask to change the shape of the name.

Because the name carries the job id, every job gets its own directory and reruns of the same job reuse it. That is the point of the clean-out: a rerun starts from an empty tree rather than from whatever the failed attempt left behind.

What the clean-out removes

Emptying the directory removes everything inside it, dot files and subdirectories included. The directory node itself stays, so permissions and ownership set on it survive.

The _backups folder that Ship File Remotely writes its pre-deploy copies into sits inside the job directory. Running this op wipes those backups with everything else. That is why the rollback guard exists, and it is why this op does not belong in the middle of a rule that has already shipped files.

There is a floor on the clean-out. When the job directory path is five characters or shorter, nothing is deleted and the job log gets a warning saying the path was too short to remove safely. You only hit that with a misconfigured jobs root.

Behaviour during rollback

On a rollback run the op creates nothing and deletes nothing. It writes an informational line saying directory creation was skipped, and moves on.

It does check that the directory is still there. If it was purged since the forward run, the op fails the job with a message saying the job directory does not exist for rollback and was probably removed after the job ran. A rollback cannot proceed without those files, so this is a hard stop rather than a warning.

What it reports back

Put a name in Return Key and you get back a value with two keys, init and job_dir. init is 1 on a forward run and 0 on a rollback run, which is the cheapest way to branch on "am I the forward pass". job_dir repeats the path, the same one already sitting in ${job_dir}.

Ordinary runs write only debug-level lines: the path being prepared, and whether the directory was created fresh or reset clean. Tick Debug in the job log filter to see them. The too-short warning, the rollback skip notice and both failures come through at their own levels and are visible without that filter.

Failure

Two conditions fail the job outright: the directory cannot be created, and the directory is absent on a rollback run. A failed delete during the clean-out also stops the op. Neither a retry nor an error trap helps with any of them, since they point at the filesystem or at the jobs root setting.

Combining with other ops

Place it before anything that reads or writes ${job_dir}. Checkout Job Items, Checkout Job Environment and Checkout Job Environment (all repos) all fail when the directory is missing, and Load Job Items into Stash has to come before them so there is something to check out.

Run command or local script and Ship File Remotely anchor their relative paths to the job directory, so they behave as written only after this op has run.

Wrap the op in IF ROLLBACK only when you want to skip it entirely on a rollback pass. Most rules do not need to, since the op already guards itself.

Examples

The standard opening of a deployment rule.

JOB STEP: INIT
  Init Job Home
  Load Job Items into Stash
  Checkout Job Items

Capture the flag so a later branch can tell a forward pass from a rollback pass.

Init Job Home
  Return Key: init_result

IF var condition THEN
  When: All
    init_result.init   IS TRUE