Skip to main content
You can adopt forge’s releases without replacing the tool that deploys today. A workload bound to forge.OnExternal is built, released and promoted by forge, then shipped by your own Helm chart, Fly.io app, Cloud Run service, ECS task or Argo CD, through up to four hooks you write. Forge renders no manifests for it. The binding is per environment: staging can stay on hosting or your own cluster while prod keeps its Helm chart. Environments covers bindings.

Before you begin

  • A forge project with an API workload (reliant forge project new <name> --service <name>), or an existing app adopted in place.
  • Your deploy tool installed and signed in on the machine that runs reliant forge env deploy. Hooks inherit that machine’s environment, so KUBECONFIG, flyctl and gcloud credentials work as they do today.
  • Forge v1.6.1 or later (reliant forge --version inside the project).
1

Bind the workload to your tool

Each hook is an argv list run with no shell. Forge replaces $FORGE_IMAGE inside an element with the image to run, pinned by digest. Write it unbraced: KCL interpolates ${...} itself.
deploy/kcl/prod/main.k
config_secrets = [] says forge doesn’t deliver the API’s secrets here: your chart does, as it does today. Every hook is optional. With none, the binding is record-only: forge builds and records the release and the promotion, and leaves running it to your CI or Argo CD.
2

Write the status and plan hooks

status prints one JSON object with the digest that is running. plan is a dry run that exits 0 for no change and 2 for changes, like helm diff --detailed-exitcode.
deploy/hooks/helm-status.sh
deploy/hooks/helm-plan.sh
Forge shows the plan hook’s output and never parses it.
3

Check what forge records

terminal
The workload is part of the environment’s shape, which every release records, and renders zero objects: the manifests are your chart’s.
4

Verify against what is running

env verify runs your status and plan hooks and changes nothing. Before forge has cut a release, name the expected image with --image:
terminal
Against a cluster where the chart hadn’t been installed, it exits 1:
After the chart deployed that image, it exits 0:
When every row says MATCH, forge’s first deploy changes nothing.
5

Deploy through forge

terminal
Forge builds and pushes the image, cuts the release and prints the plan for you to confirm. It then runs status (its digest is passed on as FORGE_PREVIOUS_DIGEST), deploy and, once deploy exits 0, health. A hook still running after timeout (900 seconds by default) is killed and the step fails. From here, releases, promotion by digest with --from staging, --plan-only and --approve, and rollback floors work as they do for any environment.
Other tools fit the same hooks. Fly.io: deploy = ["fly", "deploy", "--image", "$FORGE_IMAGE"]. Cloud Run: deploy = ["gcloud", "run", "deploy", "api", "--image", "$FORGE_IMAGE", "--region", "us-central1"]. Hooks also get FORGE_ENV, FORGE_WORKLOAD, FORGE_DIGEST, FORGE_VERSION and FORGE_RELEASE; env adds your own variables, and pass_env = True hands them the workload’s env and secrets.

What this does not do

  • Forge doesn’t run or watch the workload. It runs your hooks when you deploy or verify; between those, your tool owns it. A missing status or plan hook makes env verify report UNVERIFIED, never “no diff”.
  • No automatic rollback. A failed deploy or health hook fails the deploy. Recovery is deploying an earlier release, as in Recover from a bad deploy.
  • Release health needs telemetry. reliant forge obs check judges a release from the telemetry the workload sends. A workload on your own platform sends it once it exports OpenTelemetry (Send OpenTelemetry from any app).

Next steps

Detect configuration drift

env verify, env diff and env status together.

Promote to production

Move a release staging runs to prod by digest.

Escape hatches

Helm charts, raw manifests and other ways out of the defaults.

env verify reference

Every flag and exit code of env verify.