How to Control Preview Environments to Prevent PRs from Using One or limited Workers

Context

In setups where execution resources are limited—such as when only one worker is available—you may want to prevent users from opening Pull Requests that unnecessarily trigger preview environments. These previews can block the worker, delay critical deployments, and increase operational friction.

To mitigate this, you can create a policy that disables preview environments unless the changes in a PR are clearly relevant to a specific stack.

Solution: Use a Push Policy to Restrict Previews

Spacelift supports custom push policies that let you tightly control when preview environments are generated. By inspecting the files changed in a PR and comparing them to the stack's scope, you can skip previews unless the changes warrant it.

Example Push Policy

package spacelift

track {
  affected
  input.push.branch == input.stack.branch
}

propose := false

ignore {
  not affected
  not affected_pr
}

ignore {
  input.push.tag != ""
}

affected {
  filepath := input.push.affected_files[_]
  startswith(normalize_path(filepath), normalize_path(input.stack.project_root))
}

affected {
  filepath := input.push.affected_files[_]
  glob_pattern := input.stack.additional_project_globs[_]
  glob.match(glob_pattern, ["/"], normalize_path(filepath))
}

affected_pr {
  filepath := input.pull_request.diff[_]
  startswith(normalize_path(filepath), normalize_path(input.stack.project_root))
}

affected_pr {
  filepath := input.pull_request.diff[_]
  glob_pattern := input.stack.additional_project_globs[_]
  glob.match(glob_pattern, ["/"], normalize_path(filepath))
}

# Helper function to normalize paths
normalize_path(path) = trim(path, "/")

Why This Works

• propose := false: Disables preview environments by default.

• File-based Logic: The policy checks if PR changes are related to the stack.

• Avoid Worker Contention: Unnecessary PR previews are skipped, preserving the worker for actual deployments or relevant stack changes.

• Efficient Debugging: Use sample { true } to capture input data and validate policy behavior before rollout.