Forgeplane secret management

Forgeplane treats secrets as governed project resources, not as free-form run inputs. The model separates three concerns:

1. a logical secret that has a stable name, classification, policy, and lifecycle;
2. a secret source that defines where the value is resolved; and
3. a template binding that connects a declared secret input to the logical secret.

This separation lets teams change a source or binding without changing the template’s input contract. Secret values stay out of ordinary environment variables, template source, and normal API or UI resource fields.

Logical secrets

A logical secret is the stable object you govern over time. Its key properties include:

Property	Values
Lifecycle state	draft, active, degraded, blocked, archived
Classification	low, medium, high, critical
Value contract	opaque_string, json_string, pem_certificate
Policy severity	none, warn, block

Use classification and policy to express how the secret should be handled. A logical secret is not the same thing as the provider record that supplies its current value.

Secret sources

A source points to the backend from which Forgeplane resolves a value. Supported source kinds include:

• builtin_stored_value
• vault
• aws_secrets_manager
• gcp_secret_manager
• azure_key_vault

Source behavior also records:

• selector mode: fixed or floating;
• ownership mode: referenced or managed; and
• health status: unknown, healthy, degraded, or unhealthy.

A managed source is operated through Forgeplane’s governed lifecycle. A referenced source remains owned by its external system. Keep the source’s credentials and backend policy in the deployment’s secret-management boundary.

AWS Secrets Manager sources use only the explicit AWS Connection credential. Stored keys/session credentials, stored-key assume-role, and stored-token web identity are supported; coordinator profiles and ambient credentials are not. Malformed credentials fail local validation even for a pinned version. Provider rejection fails checks and materialization without falling back to another identity. Existing ambient-dependent connections require correction and fresh source/binding validation under the hard-cutover procedure.

GCP Secret Manager sources use the explicit GCP Connection identity: an inline service-account key or explicitly selected operator-owned workload ADC. Connection-supplied federation/user/impersonation JSON and custom endpoints are unsupported; explicit credential failures never fall back to ADC. Pinned GCP version resolution is metadata-only, not credential qualification. Latest source/binding checks and value acquisition enforce the boundary. Correct unsupported profiles and revalidate affected sources and bindings before admitting new runs under the hard-cutover procedure.

Bind secrets to templates

A template input becomes a secret slot only when a direct top-level input property has the boolean annotation x-forgeplane-secret: true. The guided editor’s Bind through secret catalog option emits this marker. Root, nested-object, array-item, and conditional-branch slot declarations are rejected. Ordinary nested inputs remain valid.

Sensitivity does not imply secret binding. The boolean flags sensitive, secret, writeOnly, x-sensitive, x-secret, and x-forgeplane-secret control redaction, but only x-forgeplane-secret: true creates a catalog-bound slot and rejects inline values. x-secret and writeOnly are redaction-only annotations. Non-boolean known flags are rejected.

Bindings connect a marked template slot to a logical secret at either project or environment scope. A binding is either bound or disabled.

Use Environments for deployment-specific bindings and policy. Do not place secret values in environment variables or ordinary input defaults.

Runtime flow

For a scheduled run:

1. the coordinator validates the template schema, binding scope, and trust state for required and configured optional slots;
2. the coordinator resolves the source and materializes the payload for the execution bundle;
3. the worker validates the bundle’s trust metadata before tool execution; and
4. the run fails closed when a required or configured optional secret is not eligible.

An optional slot is omitted only when it is unconfigured or explicitly disabled. A configured optional slot with a missing, unhealthy, expired, or policy-blocked source blocks readiness and execution. Infrastructure and credential-resolution failures are explicit errors, not ordinary stale-validation blockers.

Readiness evaluates recorded trust evidence and connection metadata; it does not resolve connection credentials or prove they remain usable. Source validation and protected materialization still resolve credentials under current authority and fail explicitly if they are unavailable.

Resolved plaintext is used for tool execution. It is not returned as an ordinary API or UI field. See Connections for non-secret provider configuration and encrypted connection credentials.

Retry established selections

Successful materialization establishes the run’s Secret, source, version, and any omitted slots. Requeue keeps those selections: replacing, removing, or disabling the current binding affects new runs, not an already established pin. A failed fetch or confirmed rollback establishes no new selection. An unconfirmed commit returns an error and no values, but may have persisted the selection; retry reads the existing evidence. Missing or inconsistent selection evidence fails explicitly rather than falling back to today’s binding.

Retries still recheck current Secret/source availability, connection state, dependency trust, and the platform-wide floating-selector disable policy. A newer floating version or its acknowledgment requirement does not replace an otherwise eligible older pin.

Trust expires at the earliest applicable source or original-binding deadline, including validation TTLs, and the worker independently enforces it. Existing authorized validation can renew only the unchanged original context, not a replacement binding or another version. If that context cannot be renewed, repair and validate the current binding and start a new run.

Rollback compensation of newly fetched dynamic leases is best effort: process loss, a lost provider response, or failed revocation still requires lease maintenance or provider expiry.

Managed actions and approval

Destructive managed-source operations use a dedicated approval workflow rather than an immediate mutation. For example, delete_source uses these approval states:

• pending
• approved
• rejected
• applied

Timeouts and defaults are controlled by secret_approval_* system settings. Approval authorizes the specific managed action; it does not expose the secret value.

Governance settings

Secret governance defaults include:

• secret_approval_self_approval_default_enabled
• secret_approval_pending_timeout_minutes
• secret_approval_maintenance_*
• secret_floating_behavior_mode
• secret_floating_drift_default_reaction
• secret_floating_require_ack
• secret_approval_independent_min_classification

See System settings for exact defaults and valid ranges. Use the Permissions and roles reference to check which identities may manage, use, or approve secret-related operations.