Worker-Side Initialization Policies vs. Server-Side Policies: What to Use and When

Overview

Spacelift offers both server-side policies (managed within Spacelift) and worker-side initialization policies (running on your own infrastructure). These serve different purposes and are not interchangeable replacements for one another.

Server-Side Policies

Server-side policies are managed directly in Spacelift, can be audited, and come with built-in samples. Use these to control the lifecycle of a run from the Spacelift side:

• Push policies — Control what triggers a run in the first place.

• Approval policies — Determine whether a run should proceed. These replaced the old server-side initialization policies.

• Plan policies — Define which changes can actually be applied.

Worker-Side Initialization Policies

Note: While worker-side initialization policies will work, Spacelift generally recommends approval policies instead.

Worker-side initialization policies run on your own infrastructure before a job starts. Because they execute at the worker pool level, they enforce rules regardless of what is configured on the Spacelift side. This makes them useful when you want the pool itself to control which stacks are allowed to run on it.

A common pattern is to have each pool mount its own Rego policy file that denies any run whose stack labels don't match that pool's designated service group or environment.

Setting Up Worker-Side Policies

For Kubernetes workers, worker-side initialization policies are configured via a ConfigMap. Mount the policy file and point the launcher to it using the environment variable:

SPACELIFT_LAUNCHER_RUN_INITIALIZATION_POLICY

Full setup instructions are available in the Kubernetes Workers — Initialization Policies documentation.

Examples and Reference

A real-world example can be found in the signed-run reference implementation. It demonstrates verifying a signed-run token at the worker and denying runs on stack or commit mismatch.

For ideas on what attributes to guard against (e.g., runner image, before_init commands, format checks, branch naming), the deprecated run initialization policy page serves as a useful catalogue of inspectable fields.

Summary: Which Policy Type Should I Use?