Environments, Gates & Approvals

## Two ways to represent a deployment target Almost every pipeline starts with the environment as a string. A job runs `./deploy.sh production`, and "production" is an argument plus a block of variables — a hostname, an API key, a cluster name. Nothing in the delivery platform distinguishes the job that deploys to a scratch sandbox from the job that deploys to the system customers use. Anyone who can edit the pipeline file, or who can persuade a job to run with the right variables in scope, can reach production. Modelling the environment as a **first-class object** moves that knowledge out of the script and into the platform. The environment becomes a named record the platform owns, and four capabilities hang off it. ## 1. Scoped configuration and credentials Secrets attach to the environment rather than to the repository or the pipeline as a whole. A job only receives production's deploy credential if the job declares that it is deploying to production — and, crucially, only after that environment's rules have passed. A pull-request job, a nightly lint job, or a staging deploy never has the value in its process at all. This is a containment property, not a secrecy property: the credential is not merely hidden from other jobs, it is never injected into them, so a compromised or malicious job in the same repository has nothing to steal. ## 2. Protection rules evaluated before the job starts The rules a platform typically supports are: required human approvers (and often, who may *not* approve — the author of the change); allowed sources, so only the default branch or a signed tag may deploy; a wait timer that forces a soak or a cooling-off period; and required upstream checks. The important word is *before*. A guard written as an `if` inside the deploy script runs on a machine that has already been allocated, with the repository already checked out and the secrets already injected. A platform-level protection rule holds the run in a pending state where nothing has started. The difference matters both for cost (no agent is tied up during a two-hour approval wait) and for security (the failure mode of the script guard is "the credential is on a box that decided not to use it"). ## 3. Deployment history and current state An environment object records deployments as events: which artifact, which commit, which run, which identity performed it, who approved it, when, and whether it succeeded. That single table answers the two questions teams cannot otherwise answer under pressure — *what is running in production right now?* and *who authorized it?* It is also what makes "roll back" a concrete operation: the previous successful record names an exact artifact to re-deploy, rather than someone reconstructing it from memory. This history is the audit trail auditors actually want. It is generated as a by-product of deploying, which is why it is trustworthy; evidence assembled afterwards from screenshots and chat messages is not. ## 4. Serialization and lifecycle Because the environment is an object, the platform can enforce one deployment at a time against it. Without that, two runs overlap and the *older* artifact can win simply by finishing last. Newer runs are typically queued or supersede the pending one. The object model also has to cope with two very different shapes: a small number of long-lived environments (dev, staging, production, plus per-region production instances), and a potentially unbounded number of ephemeral ones — one per pull request, created on open and destroyed on merge or after an idle timeout. Ephemeral environments are cheap to create precisely because the environment is a record with a lifecycle rather than hand-maintained infrastructure. ## What it does not give you An environment object is metadata about a target; it is not the target. The cluster, the database and the DNS entry still have to exist and are usually managed separately as infrastructure. It is also not a deployment strategy — how traffic moves onto the new version is a different concern entirely. And it is easy to have the form without the substance. An environment with no protection rules, whose secrets are duplicated at repository scope anyway, and which every branch may deploy to, is a variable group with a nicer name. The value comes from the rules and the record, not from the label.