Add a skip option

[orien]

Context

Some Buildkite steps never read the codebase. Gates that only echo a message are the clearest case; so are steps whose whole job is done by another plugin, such as one that posts a deploy webhook. They still clone the repository first, and on an agent with no existing checkout that clone is the slowest part of the step. In envato/sso-server the two SOX gates have a median duration of 2.2s but a p90 of around 47s and a maximum of 78s, and the difference is whether the agent had to do a full clone.

The agent offers BUILDKITE_SKIP_CHECKOUT for this, but it only skips the git work: the job still runs in the agent's normal builds/<agent>/<org>/<pipeline> directory. That path is not branch-scoped, so a tree left behind by an earlier job remains, and the agent resolves repository-local hooks from it. A step that asked for no codebase can end up running .buildkite/hooks/pre-command from another branch, or from a partial clone, where a missing file makes the hook fail under set -e and takes the step with it.

Change

Adds a skip option that clears BUILDKITE_REPO. With no repository to clone the agent allocates a fresh temporary directory for the job, skips the checkout, and removes the directory afterwards. Two consequences follow, and both are the point:

• Any existing checkout on the agent is left alone, so the next job to land there still gets an incremental fetch rather than a full clone.
• The temporary directory contains no .buildkite/hooks, so the staleness problem above cannot arise.

skip takes precedence over preset, clone, fetch and clean, and logs a line when it ignores them. It accepts true, on and 1.

The hook's existing logic is unchanged, but moving it into the else branch reindents it — git diff -w shows the real change.

Considerations

This is the same mechanism docker-compose-buildkite-plugin uses for its own skip-checkout option, which is well proven in Envato pipelines. The agent supports it deliberately: CheckoutPhase comments that "environment and pre-checkout hooks can change BUILDKITE_REPO", applyEnvironmentChanges feeds hook env changes through ReadFromEnvironment back into the executor config, and BUILDKITE_REPO is marked mutableFromWithinJob in the agent's protected-env table precisely so hooks and plugins may set it.

A step's own env: cannot do this — that same table blocks job-level env and secrets from writing BUILDKITE_REPO — which is why it has to live in a plugin.

The alternative considered was pairing BUILDKITE_SKIP_CHECKOUT with BUILDKITE_CLEAN_CHECKOUT, which also yields an empty working directory. It was rejected because the clean discards the agent's cached checkout, so the next job to land on that agent pays the full clone the change was trying to avoid. This option moves the cost rather than relocating it.

The 23 bats tests pass, along with shellcheck and the plugin linter. v1.2.0 will need tagging after merge; envato/sso-server is the first intended consumer.