Template registry

The Forgeplane template registry is the catalog of reusable infrastructure definitions. A registry entry owns the template identity and metadata; each published version owns the exact source, input contract, execution requirements, and runtime policy used by later runs.

Projects consume a published version through an instance or an assembly node. They do not copy a mutable template record into the project.

Registry entry versus published version

Keep these two lifecycle objects separate:

Object	Changes	Used for
Registry entry	Name, description, source repository, tool type, tags, and default worker pool	Catalog identity and scheduling defaults
Published version	Semantic version, Git ref, source overrides, input schema, resolver specification, provider lock, state policy, and impact notes	Reproducible execution contract

Updating registry metadata does not rewrite a published version. Publish a new version when the source, schema, resolver behavior, provider lock, or managed-state policy changes.

Create a registry entry

A registry entry requires a unique name, a supported tool type, and a normalized source repository URL. You can also set a description, tags, and a default worker pool.

The tool type is a scheduling requirement, not proof that every worker can execute the template. A run needs a worker pool and worker that advertise the required capability and contain the requested tool binary. See Workers for the execution boundary.

Registry writes require registry:manage. Registry reads and validation require registry:read; organization, team, project, and feature-gate checks can still deny a request after the registry permission passes. See Permissions and roles.

Publish a version

Use a valid semantic version such as 1.2.0. A published version records the inputs needed to reproduce its execution contract:

• Git ref and source path;
• optional source URL override;
• tool type and derived execution variables;
• JSON Schema input contract;
• optional v2 pre-run resolver specification;
• provider-lock artifact and hash for Terraform/OpenTofu;
• optional managed-state backend override; and
• impact notes for operators.

Published versions are immutable records. If a version needs a different source, schema, resolver, provider lock, or state policy, add another version instead of editing the existing one. Instances and assembly versions can then move to the new desired version deliberately.

Validate the version contract

The input schema must be a JSON object schema. Forgeplane compiles the schema before publishing and validates run variables against the selected version. The validation endpoint is explicit about the version; it does not validate against an unspecified future or “latest” schema.

Use the input schema reference for defaults, required fields, constraints, nested schemas, and secret markers. Use the guided editor for common top-level fields and the raw editor for advanced JSON Schema. Do not put connection declarations in schema annotations: declare them in the version’s pre-run resolver specification.

A resolver can derive an input or generate a file immediately before execution. The resolved context must still satisfy the published version’s schema. Bind saved connections at the environment or run boundary; keep connection behavior separate from schema authoring. See Provider connections.

Use a published version

A normal delivery path is:

1. create the registry entry;
2. publish a version with its source, schema, resolver, and execution policy;
3. bind the desired version to an environment through an instance;
4. validate the intended variables against that exact version;
5. create a run and review the resolved execution context; and
6. execute through the governed run operations flow.

A direct registry run returns 202 Accepted when the run is admitted. Accepted means the run was created for execution; it does not mean that the tool operation has completed successfully.

API operations

The deployed coordinator OpenAPI document is the source of truth for request and response schemas. The registry resource currently exposes these operation families:

Operation	Endpoint
List or create entries	GET or POST /api/v1/registry/templates
Read, update, or soft-delete an entry	GET, PUT, or DELETE /api/v1/registry/templates/{id}
List or publish versions	GET or POST /api/v1/registry/templates/{id}/versions
Read one version	GET /api/v1/registry/templates/{id}/versions/{version}
Validate variables	POST /api/v1/registry/templates/{id}/validate
Trigger a run	POST /api/v1/registry/templates/{id}/run

Use the Coordinator API reference to discover the deployed OpenAPI document. Generate clients from /api/openapi.yaml for the Forgeplane release you deploy instead of copying a hand-maintained route list.

Safe changes and failure modes

• Duplicate entry names return a conflict instead of creating a second active identity.
• Invalid semantic versions, non-object root schemas, malformed JSON, and unsupported tool capabilities fail before publication.
• A stale registry metadata update is rejected by optimistic concurrency rather than overwriting another operator’s change.
• Deleting an entry is a soft-delete operation. Published versions referenced by instances or assembly versions remain operational history, not disposable build artifacts.
• A run can be accepted only when its environment, inputs, requested operation, and worker admission satisfy the applicable delivery checks.

For the data model, see Infrastructure templates. For authorization failures, check the principal’s permission, organization and team scope, resource state, feature gate, and approval policy before granting a broader role.