Flow Control

A Flow Control policy defines the rules for how Stack Jobs execute. It controls whether jobs require manual approval, whether a preview step runs before every apply, and whether the system pauses between preview and apply to give you a chance to review the plan. Different environments need different levels of rigor — development should be fast, production should be careful — and Flow Control makes that distinction automatic.

Why Flow Control Exists

Without governance, every infrastructure change follows the same path: submit configuration, run the IaC operations, apply the result. That works for development, but production deserves more care. You want to see the plan before it runs. You want someone to approve destructive changes. You might want to skip the refresh step for resources where drift is not a concern and speed matters.

Flow Control policies encode these decisions into the platform. Define the rules once, attach them to the right scope, and every Stack Job in that scope automatically follows them. No per-deployment configuration, no manual steps to remember, no governance gaps.

The Five Controls

Every Flow Control policy consists of five settings. Each is a boolean toggle that modifies how Stack Jobs execute.

Manual Approval Required

When enabled, every Stack Job created in this scope pauses immediately after creation and waits for manual approval before any operations begin. Nothing executes until a human explicitly approves it.

This differs from "Pause After Preview" (below), which allows the preview to run automatically and only pauses before the apply step. Manual Approval Required pauses before any operation starts.

Lifecycle Events Disabled

When enabled, Stack Jobs are not automatically created when a Cloud Resource is created, updated, or deleted. You can still create Stack Jobs manually through the CLI or web console, but the automatic trigger from lifecycle events is suppressed.

This is useful for shared infrastructure that multiple teams depend on, where accidental changes could have wide impact. Only explicit, intentional Stack Jobs run.

Skip Refresh

When enabled, the refresh step is skipped during Stack Job execution. Refresh synchronizes the IaC state file with the actual cloud state, catching drift from manual changes. Skipping it saves time but means the job operates on potentially stale state.

Enable this only for resources managed exclusively through Planton with no manual cloud console access, where drift is not a concern.

Preview Before Apply

When enabled, a preview step always runs before update or destroy operations. The preview shows exactly what will change — resources to create, modify, or delete — before anything happens. This is enabled by default.

Disabling it removes the preview step, making Stack Jobs faster but removing the safety net of seeing the plan first. Only disable this for well-understood, low-risk resources in non-production environments.

Pause After Preview

When enabled (and Preview Before Apply is also enabled), the Stack Job pauses after the preview completes but before the apply or destroy runs. A team member must explicitly approve the previewed plan before the job continues.

This is the most common production governance pattern: let the preview run automatically so you can see the plan, then require a human to approve it before any changes are made to real infrastructure.

Policy Resolution Hierarchy

Flow Control policies are attached to a scope using a selector. The platform resolves which policy applies to a given Stack Job by checking four levels, from most specific to least:

1. Cloud Resource — A policy targeting a specific Cloud Resource by ID
2. Environment — A policy targeting all resources in a specific environment
3. Organization — A policy targeting all resources in the organization
4. Platform — A default policy for the entire platform

The first match wins. Policies are not merged across levels — if an environment-level policy exists, the organization and platform policies are ignored entirely for resources in that environment.

If no policy matches at any level, the platform default applies.

Common Patterns

Development: Fast Iteration

Optimize for speed. Let changes apply immediately without manual steps:

• Manual Approval Required: off
• Lifecycle Events Disabled: off
• Skip Refresh: off (keep drift detection)
• Preview Before Apply: on (the plan still appears in logs)
• Pause After Preview: off (no manual approval step)

Production: Full Control

Maximize safety. Require preview and manual approval before any change takes effect:

• Manual Approval Required: off (let the job start and preview automatically)
• Lifecycle Events Disabled: off
• Skip Refresh: off
• Preview Before Apply: on
• Pause After Preview: on (require human approval of the plan)

Shared Infrastructure: Explicit Only

For resources that multiple teams depend on, disable automatic triggers entirely:

• Manual Approval Required: on
• Lifecycle Events Disabled: on (no automatic Stack Jobs)
• Skip Refresh: off
• Preview Before Apply: on
• Pause After Preview: on

Using the Web Console

Flow Control settings are visible on the Stack Job detail page in the configuration tab. The display shows each of the five controls with an enabled/disabled indicator, reflecting the resolved policy for that specific job.

To create or update Flow Control policies, use the CLI (below). Policy management through the web console is planned.

Using the CLI

Flow Control policies are managed through the standard resource commands:

# Create or update a Flow Control policy from a YAML manifest
planton apply -f flow-control-policy.yaml

# Get a Flow Control policy by ID
planton get flow-control-policy <policy-id>

# Delete a Flow Control policy
planton delete flow-control-policy <policy-id>

To check which Flow Control policy applies to a given resource type and environment, use the Stack Job preflight check:

planton stack-job preflight-checks --cloud-resource-kind <kind>

The preflight report includes the resolved policy and its settings.

Related Documentation

• Stack Jobs — The execution units that Flow Control governs
• Cloud Resources — The resources whose deployments are controlled
• Infra Pipelines — Pipeline-level approval gates for multi-resource deployments