Forgeplane provider connections

A connection stores reusable provider configuration and, when its identity profile requires it, encrypted secret material inside a project. A template declares the connection input it needs; an environment or run binds that input to a saved connection at the intended scope.

Connections keep provider settings separate from secret management, which governs logical secrets and their source bindings. A connection can contain credential material, but its metadata and lifecycle remain separately governed.

Supported connection types

Type	Configuration examples
aws	Region, explicit auth method, role, account, or Secrets Manager endpoint
azure	Subscription, tenant, client, resource group, or cloud
gcp	Project, region, or explicit auth method
github	Owner, repository, token or App metadata, and API base URL
vault	Address, mount, namespace, and token or AppRole metadata
custom	Provider-specific key/value configuration

The create form separates non-secret configuration from the secret payload. Read and list responses expose connection metadata, such as the current secret version, but not the plaintext secret. Metadata reads do not decrypt the stored credential.

Create and validate a connection

1. Open the project’s connections area.
2. Choose a connection type and enter its required non-secret configuration.
3. Save the required credential, or leave it empty for explicit GCP workload-identity as described below.
4. Run Check saved settings to validate the saved record’s shape and required secret material.
5. Bind the connection in the template’s pre-run resolver and the target environment or run.

Check saved settings does not contact the remote provider. A successful result confirms that Forgeplane can use the saved record structurally. It does not prove that the credentials are accepted or that the provider endpoint is reachable from a worker. The displayed last-check result and timestamp are historical, not a fresh credential-availability check.

AWS Secrets Manager identity

AWS secret validation, health checks, version resolution, and materialization use only the credential stored on the secret’s project-scoped AWS connection. Coordinator environment credentials, shared profiles, token files, and instance/container metadata are never credential sources.

Set region. auth_method accepts these exact values; omitting it selects access-key:

auth_method	Stored credential JSON fields	Additional configuration
access-key	Required strings access_key_id, secret_access_key; optional string session_token	No role_arn
iam-role	The same access-key/session fields, used as the source identity for STS AssumeRole	Required role_arn, an IAM role ARN
web-identity	Required string web_identity_token, used for STS AssumeRoleWithWebIdentity	Required role_arn, an IAM role ARN

Credential JSON must be one object with only the fields for the selected method. Duplicate fields, null/non-string or empty values, leading/trailing string whitespace, mixed schemas, and trailing JSON are rejected. Explicit empty or unknown auth methods and profile are unsupported.

STS uses the configured region and AWS’s regional endpoint. The optional connection endpoint overrides Secrets Manager only, not STS. The stored source identity and role trust policy must authorize assume-role; the role’s OIDC trust policy must authorize web identity. Rejection or expiry fails explicitly, without trying another identity. Rotate stored session credentials or web-identity tokens before expiry; Forgeplane does not refresh them from coordinator files or environment variables.

Pinned version resolution validates configuration and credential shape locally without contacting AWS. It does not prove that AWS accepts the identity; health checks and materialization make provider requests.

Hard cutover: Existing AWS sources that relied on coordinator credentials stop working. Set the explicit method and required role, remove profile and incompatible role settings through Raw JSON when necessary, then replace the credential with the matching JSON. Configuration changes clear the old credential. Revalidate affected secret sources and bindings before admitting new runs. There is no automatic data migration or ambient-identity compatibility mode.

GCP Secret Manager identity

Set project_id on the GCP connection. Secret Manager accepts these exact, case-sensitive identity profiles:

auth_method	Stored credential	Identity source
service-account, omitted, or empty	Inline service_account key JSON	This connection’s encrypted key
workload-identity	Empty	Operator-configured ADC in the coordinator runtime

Service-account JSON must contain type: "service_account", client_email, and private_key, and only standard downloaded key fields. The token_uri may be https://oauth2.googleapis.com/token or the legacy https://accounts.google.com/o/oauth2/token; omitted or empty selects the former. Only the googleapis.com universe is supported.

Connection-supplied federation, user credentials, and impersonation JSON are unsupported, including file, URL, and executable credential-source selectors. Custom token endpoints are rejected. The connection fields endpoint, impersonate_service_account, and workload_identity_provider must be absent or empty. Explicit key parsing or token-exchange failure never falls back to ADC; an empty credential without explicit workload-identity fails.

Before selecting workload-identity, the runtime operator must approve and provision the coordinator’s ADC identity, source locations, and endpoints. Operator-owned ADC may use workload federation under Google’s SDK contract; connection users cannot supply that federation JSON. An empty stored credential is intentional for this profile, not a missing required key. Secret validation and acquisition allow it only for GCP Secret Manager sources.

Authorized connection users can select the runtime identity. ADC is not project-isolated and Forgeplane cannot narrow its Google IAM rights. Scope the runtime identity appropriately, use separate coordinator runtimes, or choose a project-scoped service-account key. A source’s project override still requires Google IAM authorization.

Pinned GCP version resolution is metadata-only and does not certify credentials. Latest source/binding checks and value acquisition reach the credential boundary, including acquisition with still-fresh pre-cutover trust evidence. Check saved settings is not live Google credential qualification.

Hard cutover: Existing connection-supplied federation/user/impersonation credentials and implicit ADC stop working when Secret Manager reaches this boundary. Select a supported profile and remove incompatible fields. Settings changes clear the old credential: replace it with a service-account key, or leave it empty only for operator-approved workload-identity. Revalidate affected secret sources and bindings before admitting new runs. There is no automatic JSON conversion or implicit-ADC compatibility fallback.

Unavailable connection credentials

An unreadable credential does not hide authorized connection metadata or prevent metadata updates, deactivation, deletion, or credential replacement. Replace the credential without first decrypting the old value. Saved-connection choices represent authorized, active metadata, not proof that credentials are usable. Saved-settings checks and protected execution resolve credentials and fail explicitly when they are unavailable.

An inactive or inaccessible bound connection is shown as Bound connection unavailable. When editing its environment, Keep existing binding (unavailable) is selected by default. Saving other environment fields preserves that binding. You can explicitly replace or remove it. Preserving a binding does not make it eligible for execution.

The Connection list response contains only the connections array; the former per-credential errors array is removed. Unauthorized connections remain private. Database, authorization-evaluation, and genuine metadata failures fail the request; credential-codec configuration does not govern metadata reads.

Edit connection settings

Changing a connection’s type or any of its configuration, such as a Vault address or namespace, clears the stored credential and increments the secret version. Forgeplane never sends the previous credential to the changed settings. Replace any required credential before the connection is used again; until then, saved-settings checks and protected execution fail because the required secret is missing. Explicit GCP workload-identity intentionally leaves the credential empty and requires operator-owned ADC instead. Renaming, moving to another project, or activating and deactivating a connection keeps the stored credential.

Rotate credentials

When provider credentials change:

1. create or save the new secret version;
2. confirm that the connection remains structurally valid;
3. update the consuming binding only if the connection identity changes; and
4. run a controlled plan or execute operation with the intended worker and environment.

New runs resolve the current usable secret version. Historical run records retain their execution evidence; they do not expose the plaintext credential.

Use a connection in a template

Declare the requirement in the template version’s v2 pre-run resolver specification:

• connection.config reads an allowed configuration value;
• http.request can use a saved connection as its authentication input; and
• resolvers can produce derived inputs or generated files for the execution bundle.

Bind the declared input to a concrete project connection at the environment or run boundary. Forgeplane checks scope and permission before packaging material for the worker.

HTTP runtime auth recipients

An http.request resolver that uses connection runtime auth requires an explicit recipient policy in the connection’s config. Set it through the connection create/update API or the connection form’s Raw JSON mode:

{
  "resolver_http_auth": {
    "origins": ["https://api.example.com"],
    "headers": ["Authorization", "X-Api-Key"]
  }
}

Only a principal authorized to create or update that connection can set the policy. Templates cannot supply it. Both lists must be nonempty:

• origins contains exact canonical HTTPS origins: lowercase ASCII hosts, compressed bracketed IPv6 addresses, no userinfo, path, query, or fragment, and no explicit default :443. Nondefault ports must be decimal TCP ports.
• headers contains canonical HTTP field names. Bearer and basic auth require Authorization; custom-header auth requires its selected header in this list.

Forgeplane checks the current policy at run admission and execution-bundle hydration. The worker checks the delivered policy before using the credential. Missing or invalid policies fail closed. Every runtime-auth request rejects redirects, including same-origin redirects and auth_mode=none. The policy does not override the worker’s address-safety restrictions.

Hard cutover: existing connections without this policy cannot serve HTTP runtime auth. Add the policy, then replace the credential: any config change clears the stored credential under the existing connection lifecycle. Roll out the coordinator and workers together; older workers do not enforce this contract. Already-issued execution bundles retain their policy snapshot, so a connection update does not revoke an issued bundle.

Permissions and audit

Connection management, validation, and runtime use are different capabilities. Consult Permissions and roles for the current permission names.

Create, update, rotate, test, activate, deactivate, and delete operations are recorded in the audit log. Keep connection secrets out of template source, ordinary input defaults, and generated documentation. See Audit logging for audit records and Run operations for the execution context.