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, soKUBECONFIG,flyctlandgcloudcredentials work as they do today. - Forge v1.6.1 or later (
reliant forge --versioninside 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
3
Check what forge records
terminal
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
1:0:MATCH, forge’s first deploy changes nothing.5
Deploy through forge
terminal
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.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
statusorplanhook makesenv verifyreportUNVERIFIED, never “no diff”. - No automatic rollback. A failed
deployorhealthhook fails the deploy. Recovery is deploying an earlier release, as in Recover from a bad deploy. - Release health needs telemetry.
reliant forge obs checkjudges 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.