Docs
Menu

Documentation / Setup

Environments

Define your deploy targets as environments, and manage approvals, freezes, the supply chain policy and other rules on them.

What is an environment?#

An environment is the deploy target your workloads run on: a Kubernetes cluster or a Docker host. Agents register into an environment and run the jobs sent to it. A repository binding always deploys into an environment.

A typical setup has several environments, such as staging and production. A successful run can be moved from one to the other with Promote.

Create an environment#

  1. On Infrastructure > Environments, press New environment.
  2. Enter a unique Name, for example production. The name cannot contain :.
  3. Pick Kubernetes (K8S) or Docker as the Type.
  4. Press Create environment.
  5. Add an agent with Install agent on the environment page. See Installing an agent.

Tip: The Environment readiness card on the environment page checks agents, scanners, supply chain settings and preview settings, and shows anything missing as ok, warn or fail.

Settings#

You can manage these settings on the environment page:

Setting What it does
Jobs per agent How many deployments one agent in this environment may run at once. The agent has its own cap too (default 4); the lower one wins.
Cache max (GB) Upper limit of the cache space agents may use in this environment. Oldest entries are evicted when it is exceeded.
Production (count in DORA) Counts this environment as production in the DORA metrics (deploy frequency, lead time, change fail, MTTR).
Require manual approval for deployments Runs wait for approval in PENDING_APPROVAL.
Approvers Comma-separated usernames. Empty means any developer may approve; admins always can.
Freeze windows Stops new deploys on given days and times. Rollback and preview teardown still work.
Supply-chain policy Signed image, SBOM and critical vulnerability rules. See Supply chain security.
Step image policy Applies the signature and scan rules to the images of pack steps and SHELL steps with an image: Off, Warn or Enforce.
Allow host shell Lets SHELL steps without an image run directly on the agent host. Off for new environments.
Automatic SBOM and vulnerability scan Inherits the organization setting, or turns it on or off for this environment.
When prod fail-rate is high What happens when the production failure rate rises: notify only, freeze or rollback.
Deploy verification Prometheus and HTTP checks after a deploy. See Deploy verification and rollback.
Review Apps Per-PR preview namespaces on Kubernetes. See Preview apps.

Approval#

With Require manual approval for deployments on, every run into this environment waits until it is approved. With an empty approver list, anyone with the developer role may approve. Rollbacks need approval too.

Freeze windows#

Freeze windows are defined by days of the week, a start and end time and a timezone. Windows that cross midnight work too (for example Fri 17:00 → Mon 09:00). An active window stops commit, manual, schedule and promote runs; rollback keeps working. Use Freeze this environment to freeze it right away.

Host shell#

With Allow host shell off, a SHELL step without an image fails the deployment; give the step an image. In the same case, DOCKER_COMPOSE_UP steps and DOCKER_RUN steps whose arguments hand the container the host (--privileged, host path mounts, the Docker socket and similar) are refused too.

Warning: With host shell on, anyone who can edit a pipeline in this environment can reach the agent host as the agent's user. Turn it off once your steps run in an image.

Kubernetes environments#

  • K8S_DEPLOY, HELM_UPGRADE and similar steps deploy into the namespace the agent runs in, unless the step sets another namespace.
  • TRIVY_SCAN steps need Trivy in the cluster: press Install Trivy on the environment page. Trivy runs in separate Job pods, not inside the agent.
  • KANIKO_BUILD builds images inside the cluster without a Docker daemon.

Docker environments#

  • DOCKER_BUILD, DOCKER_RUN and DOCKER_COMPOSE_UP steps use the Docker daemon of the agent host.
  • PODMAN_BUILD runs podman build on the agent host instead, with no Docker daemon. The agent advertises the podman_build capability only when the podman binary is on its PATH; without it the run is refused with a clear error. The registry login uses a throwaway authfile that is deleted after the step. A Kubernetes agent refuses PODMAN_BUILD: use KANIKO_BUILD there. An image that is built but not pushed (no registry_id) lives in podman's own storage, which DOCKER_RUN (Docker daemon) cannot see: push it and deploy from the registry. Do not put secrets in build_args: they end up in the image history and in the command line.
  • SHELL steps with an image and pack steps run in their own containers.

Environment-scoped variables#

On Infrastructure > Variables you can define variables scoped to an environment. They override global and repository variables with the same key. See Secrets and variables.

Next steps#

Last updated: October 21, 2026