Forgeplane feature gates

Feature gates control the rollout of capabilities independently from software deployment. A gate definition declares its assignment scope and default; an assignment overrides that default for one resource.

Do not assume that every gate can be assigned at every scope. The feature-gate service supports environment, project, run, and worker targets, but each definition is valid only for its declared target.

Treat a gate change as an operational change. Record the target, reason, approver, and rollback condition, then validate the resulting behavior in one canary scope before widening the assignment.

Assign a gate safely

Before changing a gate:

1. confirm the gate name and its declared scope;
2. confirm the target resource and the current effective value;
3. verify dependent approvals, backups, permissions, and observability; and
4. define how to disable new work without assuming that an existing run will be canceled.

Project creation and gate assignments

Project creation and editing save the Project fields and submitted gate choices in one transaction. A rejected gate change does not leave a partially saved Project.

• With update permission for the new Project, every submitted gate value becomes an explicit assignment, including a value equal to the catalog default. Later default changes do not replace that assignment.
• With create permission only, submitted values must match the current catalog defaults. Forgeplane creates no assignment rows. A custom value, or an old default that no longer matches the catalog, rejects the whole submission. Reload and review the defaults before retrying.
• An omitted gate on creation has no explicit assignment. Omission while editing leaves the existing assignment unchanged.

No assignment means the gate’s existing fallback policy applies. In particular, the self-approval gates below fall back to their system settings, not the catalog checkbox value. Creation-time validation does not change that policy or grant approval authority.

See saving and retrying workload forms when a response is lost.

Current gates

Gate	Scope	Default	Purpose
approvals.enabled	Environment	true	Require governed approval before apply operations
drift_monitoring.enabled	Environment	false	Allow scheduled, instance-bound drift monitoring
drift_convergence.revert.enabled	Environment	false	Allow revert-live convergence requests
drift_convergence.accept.enabled	Environment	false	Reserve the accept-live request path; execution is not implemented
drift_convergence.codify.enabled	Environment	false	Reserve the codify-live export path; execution is not implemented
drift_convergence.destructive.enabled	Environment	false	Allow convergence execution that can destroy resources
drift_action.atomic.enabled	Environment	true	Enforce atomic drift-action transitions
drift_lineage.enforced.enabled	Environment	true	Enforce drift lineage requirements
selective_undo.preview.enabled	Environment	false	Allow read-only eligibility and fresh current-state evidence checks
selective_undo.create.enabled	Environment	false	Allow baseline/candidate work and explicit promotion of a removal change
run.approvals.self_approval.enabled	Project	false	Override the system-default run self-approval policy for one project; explicit confirmation remains required
secret.approvals.self_approval.enabled	Project	false	Override the system-default managed-secret self-approval policy for one project; explicit confirmation remains required

Selective Undo rollout

Selective Undo is evidence-first: it creates fresh plans and enters the normal approval path. It is not state rollback and never applies automatically.

Before enabling either gate:

• verify a current managed-state backup and restore procedure
• verify immutable source, tool, schema, and provider-lock provenance
• keep approvals.enabled enabled
• ensure a distinct authorized approver can review promoted changes
• confirm operators can inspect attempts, evidence, state generation, and audit events

Enable the gates in this order:

1. Leave both disabled while validating backups, permissions, and observability.
2. Enable selective_undo.preview.enabled for one controlled environment.
3. Review successful, blocked, stale, and failed evidence checks. Preview does not create an approval or start an apply.
4. Enable selective_undo.create.enabled only after the preview results and operating controls are acceptable.
5. Expand to additional environments one at a time.

To stop new work, disable selective_undo.create.enabled first, then disable selective_undo.preview.enabled if read-only checks must also stop. Changing a gate does not cancel an ordinary approval or apply that was already created; stop that workflow through its normal controls.

Self-approval uses an effective policy plus confirmation

An explicit project assignment overrides the matching system default. When no project assignment exists, the system setting supplies the fallback. In either case, a request must also satisfy the product’s explicit confirmation requirements.

• Run approvals fall back to run_approval_self_approval_default_enabled.
• Managed-secret approvals fall back to secret_approval_self_approval_default_enabled.

Both system defaults are false. A project assignment can explicitly enable or disable self-approval for that project. See System Settings.

Operational guidance

• Record who changed a gate, the target, the reason, and the rollback condition.
• Prefer a single environment or project canary before widening an assignment.
• Treat a disabled dependency, stale lineage, or managed-state recovery condition as a stop signal.
• Use the runtime feature-gate UI to inspect the installed definitions; this page is a product overview, while the running coordinator owns those definitions.