Zip local path

Packs a directory or a single file on the Clarive server into a zip archive. Two paths in, one archive out. Use it to turn a build output tree into one file you can then publish, ship or attach to a log.

The op runs on the server, inside a job. It reads and writes the job's own filesystem, so pointing it at a path on a deployment target does nothing useful. Fetch the files first with Retrieve a remote file, then pack them here.

Read the section on what the archive looks like inside first. The paths stored in the archive are not the ones the form suggests.

Fields

Local Dir

What to pack. Despite the label this takes a single file as happily as a directory. A directory is walked all the way down.

${var} placeholders expand against the stash, so ${job_dir}/${project}/dist is the usual shape.

The box is several lines tall, which invites a list of paths. It is not one. The whole content is read as a single path, newlines and all, so a second line produces a path that cannot exist. One path per op. To pack several separate trees, put the op inside FOREACH file/item and write one archive per pass, or copy them into a common directory first.

A source that does not exist fails the op with an error naming the path. That check happens after the destination has already been created, which is the trap described below.

Files the job cannot read are left out of the archive with no error and no log line. A tree packed by one account and written by another can come out short.

The form lets you save the op with this box empty. A blank path behaves like a path that does not exist, so the op fails at run time.

Zip File Path

Where to write the archive, including the file name. ${var} placeholders expand.

The parent directory has to exist already. The op does not create it, and a missing directory fails with a file creation error naming the path.

An existing file at that path is destroyed. Not overwritten at the end, destroyed at the start: the op truncates the destination to zero bytes as its first action, before it has looked at the source at all. A run whose source path is wrong therefore leaves a zero-byte file exactly where the good archive used to be. Write to a fresh name, or to a name carrying the job id, when a previous archive matters.

The form lets you save the op with this box empty. A blank path fails on the first action of the op, before the source is looked at.

What the archive looks like inside

Entries are stored under the full path of the source, with the leading slash dropped. Packing /opt/foo/out gives you an archive whose members are opt/foo/out/bar.txt and opt/foo/out/sub/baz.txt, not bar.txt and sub/baz.txt. A single file is stored under its full path in the same way.

Anyone unpacking the archive therefore rebuilds the whole source path as nested directories with the files at the bottom, and a process that expects the files at the top of the archive will not find them. Two ways around it, both outside this op. Change directory into the source and pack from there with Run command or local script, or write the file layout you want into a staging directory first and pack that. Choosing a short staging path keeps the prefix small when you cannot get rid of it.

When the source is a single file, the op asks the server what kind of file it is and stores it uncompressed if the answer names it as compressed data, which covers gz, bz2 and xz. A zip and the common image formats do not answer that way, so they are deflated a second time for nothing. Directory sources are compressed throughout, whatever they hold.

Log, result and rollback

One line lands in the job log at info level, naming the source and the destination after variable expansion. The resolved settings are attached to that line, so opening it shows exactly what the placeholders became. There is no way to change the wording or to suppress the line.

The op returns the path of the archive it wrote. Put a name in the op's Return Key property to capture it, and the next op can take the path from there instead of repeating the expression.

Nothing is undone on rollback, and the archive stays where it was written. A zero-byte file left behind by a failed run is not cleaned up either.

Failures stop the rule. Wrap the op in TRY statement with CATCH statement when a packaging failure should not end the job.

Combining with other ops

Build the contents first with Run command or local script or Write local file.

Then do something with the archive. Publish local file to log attaches it to the job log for download, Publish files to the artifacts repository gives it a permanent URL, and Ship File Remotely sends it to a node.

Clean up afterwards with Delete Local Directory on the staging tree once the archive exists.

Examples

Pack a build output directory and publish the result.

Local Dir       ${job_dir}/${project}/dist
Zip File Path   ${job_dir}/${project}-${version}.zip

Pack a single generated file, capturing the path for the next op.

Local Dir       ${job_dir}/reports/coverage.html
Zip File Path   ${job_dir}/coverage-${job_name}.zip
Return Key      foo_archive

One archive per item in a stash list, written into a directory that already exists.

FOREACH file/item   over ${modules}   as foo_module
  Local Dir       ${job_dir}/build/${foo_module}
  Zip File Path   ${job_dir}/out/${foo_module}.zip