Forgeplane infrastructure templates

A Forgeplane template is the versioned contract for one reusable infrastructure unit. It connects source code, tool type, input validation, optional pre-run resolution, worker requirements, and execution metadata to the runs created from its published versions.

Use a template when multiple environments or instances should consume the same infrastructure definition without changing the reviewed execution contract.

Registry entry and published version

The registry entry identifies the reusable unit:

Field	Purpose
Name and description	Identify the infrastructure unit.
Source	Locate the Git repository containing the code.
Tool type	Select terraform, tofu/opentofu, or ansible.
Default worker pool	Route runs when the caller does not choose a pool.

Publishing creates an immutable version. A version records:

• the Git ref and source path;
• the JSON Schema input contract;
• the optional v2 pre-run resolver specification;
• the provider-lock artifact for reproducible Terraform/OpenTofu execution; and
• the optional managed-state backend override.

Instances select a desired published version. Assembly versions reference published template versions, so the execution graph does not change underneath an active run.

Worker and tool boundaries

The template’s tool type is a scheduling requirement. It is not proof that a worker contains the required binary or provider tooling. A run is eligible only for a worker that advertises the matching capability and can execute the requested tool.

Terraform and OpenTofu versions support preview, apply, teardown, streamed logs, and managed state. Ansible uses the governed execution and log path, but it is execute-only: it does not use Terraform-style plan/apply promotion, teardown, managed state, or plan-based drift.

Input contract

The root input schema is an object. Top-level fields can be edited in the guided authoring view; nested or advanced JSON Schema belongs in the raw editor.

{
  "type": "object",
  "properties": {
    "region": {
      "type": "string",
      "description": "AWS region",
      "default": "eu-central-1",
      "minLength": 1
    },
    "token": {
      "type": "string",
      "x-forgeplane-secret": true
    }
  },
  "required": ["region"]
}

Use x-forgeplane-secret: true on a direct top-level input property for a catalog-bound secret slot. Forgeplane satisfies these slots through project or environment bindings and rejects inline values. Nested slot declarations are not supported.

Redaction-only annotations such as writeOnly and x-secret do not create slots. All known sensitivity flags must be booleans. The guided editor emits the canonical slot marker; use the raw editor for redaction-only or advanced schemas.

See Input schema for supported constraints and Secret management for binding behavior.

Pre-run resolvers

A published v2 resolver specification can derive inputs or generate files immediately before execution. Current actions are:

Action	Purpose
connection.config	Read an allowed value from a saved connection selected for the run.
literal.value	Emit a controlled literal value.
http.request	Request a value from an HTTP endpoint, optionally using a saved connection for authentication.

Resolvers target derived_inputs or a generated file. They are part of the published version and run through the governed execution path; they are not JSON Schema annotations.

A specification may declare at most 16 resolvers; publishing a version with more is rejected. The worker runs them in order within a two-minute budget shared by all resolvers of a run. Cancelling the run stops the resolver in progress, and exceeding the budget fails the run as timed out.

Template workflow

1. Register the source and choose the tool type.
2. Define the input schema and secret markers.
3. Add any approved pre-run resolver specification.
4. Publish an immutable version.
5. Bind the version to an environment through an instance.
6. Create a run and review its resolved execution context before execution.