Forgeplane configuration reference

Forgeplane reads FORGEPLANE_* environment variables, Helm-rendered deployment values, and coordinator system settings. Use this page to choose the correct configuration layer, understand precedence, and review security-sensitive defaults. It is a curated operator reference, not an exhaustive copy of every setting.

Sources of truth and precedence

Use the source that matches how Forgeplane is running:

Source	Authority
charts/forgeplane/values.yaml and the chart README	Supported values, Secret wiring, and deployment defaults for the packaged Helm release
internal/config/config.go	Process environment names, parsing, validation, and built-in defaults
/admin/settings and System Settings	Runtime-tunable settings stored by the coordinator

At runtime, precedence is:

1. A supported database-backed system setting, where one exists
2. An explicitly supplied FORGEPLANE_* environment variable
3. The built-in process default

Do not copy a process default into deployment automation without checking the installed Helm chart and release-specific configuration. A value that is safe for local development may not be a production recommendation.

Helm values are not a fourth runtime layer: the chart renders values and Kubernetes Secrets into process configuration. The chart can intentionally choose production defaults that differ from the bare process defaults, so deployed Helm behavior must be read from the chart version you install.

For workers, use workerDefaults.* for shared chart configuration and workerPools.<name>.* for named pool overrides.

Required security material

Supply secrets through your platform’s secret store. Do not commit them to values files or container images.

Variable	Requirement
FORGEPLANE_JWT_SECRET	Required by the coordinator for session signing; empty and known development defaults are rejected
FORGEPLANE_SECRET_KEY	Required 32-byte key for encryption of sensitive coordinator data
FORGEPLANE_WORKER_ENROLLMENT_TOKEN	Shared enrollment authority used when workers register
FORGEPLANE_REAPER_AUTH_KEY	Optional dedicated, restart-stable key for workspace/spool ownership manifests; otherwise deployment-held secret material is used
FORGEPLANE_NATS_RELAY_SIGNING_SECRET	Optional HMAC key for logs.run.* relay messages
FORGEPLANE_NATS_RUN_EVENT_SIGNING_SECRET	Optional HMAC key for runs.status messages

Rotating encryption or managed-state keys requires the matching rotation procedure. Replacing a key without preserving referenced key IDs can make encrypted data unrecoverable.

Important process defaults

These are the current bare-process defaults. They are useful for detecting accidental configuration drift; they are not production recommendations.

Coordinator and PostgreSQL

Variable	Default	Operator note
FORGEPLANE_HTTP_PORT	8080	Product API and UI listener
FORGEPLANE_ADMIN_HTTP_PORT	8082	Dedicated admin/health listener
FORGEPLANE_GRPC_PORT	9090	Worker-facing coordinator listener
FORGEPLANE_GRPC_ALLOW_INSECURE	false	A server certificate is required unless insecure mode is explicitly enabled
FORGEPLANE_GRPC_REQUIRE_CLIENT_CERT	false	The production Helm chart enables worker mTLS
FORGEPLANE_GRPC_REFLECTION_ENABLED	false	Enables gRPC server reflection for debugging
FORGEPLANE_HTTP_SUCCESS_LOG_SAMPLE_RATE	0.1	Clamped to 0.0..1.0
FORGEPLANE_URL	empty	Required when mail delivery needs absolute application links
FORGEPLANE_DB_HOST	localhost
FORGEPLANE_DB_PORT	5432
FORGEPLANE_DB_NAME	forgeplane
FORGEPLANE_DB_SSLMODE	disable	Local default; use verified TLS in production
FORGEPLANE_DB_MAX_OPEN_CONNS	25	Budget across the maximum coordinator replica count
FORGEPLANE_DB_MAX_IDLE_CONNS	10	Must not exceed max open connections
FORGEPLANE_DB_CONN_MAX_LIFETIME	5m
FORGEPLANE_DB_CONN_MAX_IDLE_TIME	1m

NATS and transport

Variable	Default
FORGEPLANE_NATS_URL	nats://localhost:4222
FORGEPLANE_NATS_TLS_ENABLED	true
FORGEPLANE_NATS_AUTH_MODE	userpass
FORGEPLANE_NATS_CONSUMER_ACK_WAIT	30s
FORGEPLANE_NATS_CONSUMER_MAX_ACK_PENDING	200
FORGEPLANE_NATS_CONSUMER_MAX_DELIVER	10

The optional FORGEPLANE_NATS_RELAY_* group inherits the primary connection unless a relay value is set. TLS certificate/key pairs must be supplied together. Coordinator gRPC secure mode requires a server certificate; worker mTLS additionally requires the client CA and client certificate configuration selected by the chart.

The NATS server’s max_payload is not a FORGEPLANE_* process setting. Set it to at least 4194304 on every server. This accommodates the 2 MiB structured-output limit plus its signed execution-outcome envelope. An observed-limit error identifies the configured and required sizes; raise the server limit rather than dropping required evidence.

Worker runtime

Variable	Default	Operator note
FORGEPLANE_COORDINATOR_ADDR	localhost:9090	Coordinator gRPC address
FORGEPLANE_WORKER_POOL_NAME	default	Pool advertised during registration
FORGEPLANE_WORKER_CAPABILITIES	none ([])	The base worker bundles no IaC tools; use a tool-enabled image and advertise only its real capabilities
FORGEPLANE_WORKER_GIT_ALLOW_HOSTS	empty	Startup-only, comma-separated exact ASCII hosts or IP addresses; a host exception trusts all its DNS answers
FORGEPLANE_WORKER_GIT_ALLOW_PRIVATE_CIDRS	empty	Startup-only, comma-separated IPv4/IPv6 CIDRs; an exact host or matching CIDR permits a restricted Git destination
FORGEPLANE_WORKER_HEARTBEAT_INTERVAL	5s
FORGEPLANE_WORKER_HEALTH_PORT	8081	Health listener is enabled by default
FORGEPLANE_WORKER_HEALTH_BIND_ADDRESS	empty	Binds the listener without a loopback-only restriction
FORGEPLANE_MAX_CONCURRENT_JOBS	1	Coordinator: initial value of the worker_max_concurrent_jobs system setting. Workers currently run one job at a time regardless
FORGEPLANE_JOB_TIMEOUT_DEFAULT	30m
FORGEPLANE_JOB_TIMEOUT_MAX	2h
FORGEPLANE_WORKSPACE_SIZE_LIMIT_MB	2048	Per run, including cloned source and downloaded providers. Checked about once a second; a run that exceeds it fails.
FORGEPLANE_ARTIFACT_SIZE_LIMIT_MB	512	Per plan file; a larger plan fails before upload.
FORGEPLANE_HTTP_RESOLVER_TIMEOUT	10s
FORGEPLANE_HTTP_RESOLVER_MAX_RESPONSE_BYTES	1048576	1 MiB

Worker capability names are scheduling claims, not tool installers. A worker image must actually contain the binary and supporting runtime it advertises.

Git source destinations

Public/unrestricted HTTPS, SSH URL and SCP-style Git destinations are allowed by default. Direct private, loopback, link-local, multicast, unspecified and restricted special-purpose addresses require an exact host or CIDR exception on each worker or pool:

FORGEPLANE_WORKER_GIT_ALLOW_HOSTS=git.corp.example
FORGEPLANE_WORKER_GIT_ALLOW_PRIVATE_CIDRS=10.20.0.0/16,fd20::/48

Both lists are not required. Empty settings mean no exceptions; malformed or empty CSV entries fail worker startup. Hosts cannot contain schemes, ports, paths or wildcards. Whitespace around entries is allowed, hostname case and a final DNS dot are normalized, and CIDRs are normalized to their network address. Use IPv4 CIDRs for IPv4-mapped addresses.

Hard cutover: existing private Git sources without matching exceptions fail on upgraded workers. Configure intended exceptions during the worker rollout; there is no grandfathering, stored-source migration, bypass flag or hot reload. In Helm, use existing workerDefaults.extraEnv or pool extraEnv; replacing a list must retain the IaC UID/GID entries. The packaged Compose OpenTofu worker permits only its fixture-git hostname by default.

An exception can authorize any restricted address, including metadata and loopback. Catch-all CIDRs can disable address restrictions. Scope exceptions to the intended Git origin, not every private network. This is clone destination protection, not an IaC execution egress sandbox or Git credential-delivery feature.

Direct connections reject empty/invalid DNS and any denied answer in a mixed result, then dial only validated numeric addresses. SSH HostName/Port rewriting is applied before authorizing the effective destination; an alias exception does not authorize a rewritten host. TLS certificates and SSH known_hosts remain checked. Only initial HTTPS discovery redirects are followed, with each target authorized separately; HTTP downgrades, userinfo and fragments are rejected before contact. A redirect query must be absent or contain exactly one service=git-upload-pack parameter, without other parameters or duplicates. Original source URLs still forbid queries and fragments.

Source	Existing proxy setting	Supported schemes
HTTPS	HTTPS_PROXY / https_proxy	http / https CONNECT, socks5, socks5h
SSH URL / SCP	ALL_PROXY / all_proxy	socks5, socks5h

The effective proxy environment itself declares operator trust; no extra trust flag or Git-specific proxy setting is required. HTTPS also retains HTTP proxy host[:port] shorthand. Proxy endpoints are exempt, but that exemption never authorizes a Git origin; restricted literal origins still need a local exception. For proxied hostname origins, the worker does not resolve or pin origin addresses or independently verify final enforcement: the operator-managed proxy must enforce equivalent-or-stricter hostname/address, all-answer DNS and re-resolution policy, with only the intended worker’s exceptions. A shared union of broader pool exceptions is not equivalent protection. Verify that policy against the actual proxy before relying on it.

NO_PROXY / no_proxy paths stay direct and worker-enforced. Invalid effective proxy configuration, refusal or connection failure never silently falls back direct; a generic proxy refusal is not proof of destination-policy denial. Clone errors do not retain raw response bodies, SSH stderr, redirect URLs or proxy credentials.

Storage and managed state

Variable	Default
FORGEPLANE_STORAGE_BACKEND	local
FORGEPLANE_ARTIFACTS_DIR	./data/blobs
FORGEPLANE_S3_REGION	us-east-1
FORGEPLANE_S3_FORCE_PATH_STYLE	false
FORGEPLANE_MANAGED_STATE_PLAINTEXT_LIMIT_MB	64
FORGEPLANE_MANAGED_STATE_TRANSFER_MAX_CONCURRENT	2
FORGEPLANE_MANAGED_STATE_TRANSFER_PER_WORKER	1
FORGEPLANE_MANAGED_STATE_RETENTION_DRY_RUN	true
FORGEPLANE_MANAGED_STATE_RETENTION_MIN_GENERATIONS	10
FORGEPLANE_MANAGED_STATE_RETENTION_MIN_AGE	8760h (365 days)
FORGEPLANE_MANAGED_STATE_RETENTION_TOMBSTONE_DELAY	720h (30 days)
FORGEPLANE_MANAGED_STATE_RETENTION_BATCH_SIZE	100
FORGEPLANE_MANAGED_STATE_RETENTION_INTERVAL	24h

The transfer limits apply to all coordinator downloads, both managed state and plan artifacts: MAX_CONCURRENT caps simultaneous downloads per coordinator and PER_WORKER caps them per worker. Each download is staged in coordinator temporary storage to verify its checksum. Plan artifacts are capped at 512 MiB. | FORGEPLANE_MANAGED_STATE_ENVELOPE_WRITE_VERSION | 1 |

Envelope versions 1 and 2 are accepted; any other value falls back to 1. Change the write version only as part of the documented envelope rollout. PostgreSQL metadata, encrypted object-storage blobs, and all referenced decrypt keys must be backed up and restored as one recovery set.

Observability

Variable	Default
FORGEPLANE_OTEL_ENABLED	false
FORGEPLANE_OTEL_TRACES_ENABLED	true
FORGEPLANE_OTEL_METRICS_ENABLED	false
FORGEPLANE_OTEL_LOGS_ENABLED	false
FORGEPLANE_OTEL_ENDPOINT	empty
FORGEPLANE_OTEL_SAMPLING_RATE	0.10
FORGEPLANE_OTEL_TRACE_CONTINUATION_MAX_AGE	15m
FORGEPLANE_OTEL_SERVICE_NAME	empty
FORGEPLANE_DEPLOYMENT_ENVIRONMENT	empty
FORGEPLANE_OTEL_INSECURE	false
FORGEPLANE_PROMETHEUS_METRICS_ENABLED	true
FORGEPLANE_METRICS_AUTH_ENABLED	false
FORGEPLANE_PROFILING_ENABLED	false

The trace, metric, and log switches only take effect when the relevant exporter is enabled. Production validation rejects insecure OTel transport unless FORGEPLANE_OTEL_ALLOW_INSECURE_IN_PROD=true.

Email

Mail delivery is unconfigured while FORGEPLANE_MAIL_SMTP_HOST is empty. When it is configured, FORGEPLANE_MAIL_FROM_ADDRESS is required.

Variable	Default
FORGEPLANE_MAIL_SMTP_PORT	587
FORGEPLANE_MAIL_SMTP_AUTH_MODE	plain
FORGEPLANE_MAIL_SMTP_SECURITY_MODE	starttls_required
FORGEPLANE_MAIL_SMTP_ALLOW_INSECURE_PLAINTEXT	false
FORGEPLANE_MAIL_FROM_NAME	Forgeplane
FORGEPLANE_MAIL_MAX_ATTEMPTS	3
FORGEPLANE_MAIL_RETRY_BACKOFF	0s,5s,30s

Configuration groups

Use the implementation or chart reference for the complete set within each group:

• FORGEPLANE_DB_*: PostgreSQL address, credentials, TLS mode, and pool limits
• FORGEPLANE_NATS_*: primary and relay connections, TLS, authentication, delivery, and message signing
• FORGEPLANE_GRPC_* and FORGEPLANE_WORKER_GRPC_*: coordinator server TLS and worker client TLS
• FORGEPLANE_STORAGE_*, FORGEPLANE_S3_*, and FORGEPLANE_MANAGED_STATE_*: artifact and managed-state persistence
• FORGEPLANE_OTEL_*, FORGEPLANE_PROMETHEUS_*, FORGEPLANE_METRICS_*, and FORGEPLANE_PROFILING_*: telemetry export and scrape protection
• FORGEPLANE_MAIL_*: SMTP transport and retry policy
• FORGEPLANE_WEBHOOK_*: explicit private-target allowlists

Production guardrails

• Prefer the chart’s coordinator.existingSecret and external secret integration over plaintext values.
• Use PostgreSQL verify-full where the certificate and hostname support it.
• Keep coordinator-worker gRPC encrypted; use worker client certificates for production mTLS.
• Restrict the admin listener, worker health listeners, readiness detail, and metrics to trusted networks.
• Keep managed-state retention in dry-run until backups, restore drills, key escrow, and deletion review are in place.
• Check the chart values and internal/config/config.go when configuring the installation; this curated page deliberately omits low-level and release-specific knobs.