Forgeplane instances

An instance is Forgeplane’s managed deployment target. It binds one published registry template to one environment, tracks the desired template version, and provides the stable identity for runs, drift findings, and managed state.

Create the environment and publish the template version first, then create the instance. Move an instance to a different desired version deliberately; a later template publication does not silently change it.

Instance execution context

When a run is queued, the coordinator resolves and snapshots:

• the selected published template version and Git ref;
• environment defaults and explicit instance/run inputs;
• secret and connection bindings;
• worker-pool and tool requirements; and
• approval and feature-gate decisions used for the operation.

Inputs are validated against the selected template-version schema at run creation. A later template publication or environment edit does not mutate the historical snapshot.

Direct top-level schema properties marked x-forgeplane-secret: true are secret slots and must be satisfied through the secret catalog. The coordinator validates the binding and materializes the payload only for the scheduled execution bundle. Redaction-only annotations such as writeOnly and x-secret do not declare slots; see Input schema.

Operations by tool

Tool	Supported instance operations
Terraform / OpenTofu	Preview, apply, teardown, streamed logs, managed state, and plan-based drift.
Ansible	Execute and streamed logs. Preview, teardown, managed state, and plan-based drift are not supported.

Ansible instances are execute-only. Do not configure a Terraform/OpenTofu plan, managed-state, teardown, or drift workflow for them.

Run and state lineage

Runs carry an execution fingerprint over the resolved execution context. Approval and promotion flows use that lineage so a reviewed plan cannot silently become a different apply request.

With managed Terraform/OpenTofu state enabled, the instance is also the state ownership boundary. A missing or unreadable required state layer fails closed as recovery_required; review Managed state before enabling it in production.

See Environments for policy context, Runs for lifecycle states, and Template registry for published versions.