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.

Bind secrets to templates

A template input becomes a secret slot only when its schema marks it explicitly. Forgeplane accepts these annotations:

• x-forgeplane-secret: true
• x-secret: true
• writeOnly: true

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, trust state, and required secret material;
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 binding or trust check is not satisfied.

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.

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.