> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reliantlabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Keep Helm, Fly.io or Cloud Run and still get releases and gates

> Bind a workload to forge.OnExternal so forge builds, releases and checks it while your own Helm chart, Fly.io app or Cloud Run service keeps deploying it.

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](https://docs.reliantlabs.io/guides/hosting/deploy-to-your-own-kubernetes.md) while prod keeps its Helm chart. [Environments](https://docs.reliantlabs.io/forge/deploy/environments.md) 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](https://docs.reliantlabs.io/guides/forge/bring-existing-app-any-language.md).
* 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.

```kcl deploy/kcl/prod/main.k theme={null}
# Your Helm chart deploys the API; forge builds, releases and gates it.
_helm = forge.OnExternal {
    status = ["deploy/hooks/helm-status.sh"]
    plan = ["deploy/hooks/helm-plan.sh"]
    deploy = ["helm", "upgrade", "--install", "api", "deploy/helm/api", "--set", "image=$FORGE_IMAGE", "--wait"]
    health = ["kubectl", "rollout", "status", "deployment/api", "--timeout", "120s"]
}

_workloads = [
    _api | {runtime = _helm, config_secrets = []}
]
```

`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`.

```bash deploy/hooks/helm-status.sh theme={null}
#!/usr/bin/env bash
set -euo pipefail
image_id=$(kubectl get pods -l app=api -o jsonpath='{.items[0].status.containerStatuses[0].imageID}' 2>/dev/null || true)
if [ -z "$image_id" ]; then
  echo '{"health": "absent"}'
  exit 0
fi
echo "{\"digest\": \"${image_id##*@}\", \"health\": \"healthy\"}"
```

```bash deploy/hooks/helm-plan.sh theme={null}
#!/usr/bin/env bash
set -uo pipefail
helm template api deploy/helm/api --set image="$FORGE_IMAGE" | kubectl diff -f -
case $? in
  0) exit 0 ;;
  1) exit 2 ;;
  *) exit 1 ;;
esac
```

Forge shows the plan hook's output and never parses it.

**3. Check what forge records**

```bash terminal theme={null}
reliant forge env shape prod
```

```text theme={null}
env prod (project shop): self_managed
  clusters:  (none declared)
  workloads: 1
    api (external)
  objects:   0
```

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`:

```bash terminal theme={null}
reliant forge env verify prod --image api=ghcr.io/stefanprodan/podinfo@sha256:862ca45e61b32392f7941a1bdfdbe5ff8b6899070135f1bdca1c287d0057fc94
```

Against a cluster where the chart hadn't been installed, it exits `1`:

```text theme={null}
WORKLOAD  RUNTIME   IMAGE       CONFIG  RESULT
api       external  unverified  drift   DRIFT

api:
  image  unverified: the status hook reported no digest
  config drift: the plan hook reports changes (exit 2)
```

After the chart deployed that image, it exits `0`:

```text theme={null}
WORKLOAD  RUNTIME   IMAGE  CONFIG  RESULT
api       external  match  match   MATCH

1 match, 0 drift, 0 unverified, 0 error, 0 skipped
```

When every row says `MATCH`, forge's first deploy changes nothing.

**5. Deploy through forge**

```bash terminal theme={null}
reliant forge env deploy prod
```

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](https://docs.reliantlabs.io/forge/deploy/release-gates.md#rollback-floors) work as they do for any environment.

> [!TIP]
>
> 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](https://docs.reliantlabs.io/guides/hosting/recover-from-bad-deploy.md).
* **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](https://docs.reliantlabs.io/guides/observability/send-opentelemetry-from-any-app.md)).

## Next steps

> [card] [Detect configuration drift](https://docs.reliantlabs.io/guides/hosting/detect-config-drift.md)
>
> `env verify`, `env diff` and `env status` together.

> [card] [Promote to production](https://docs.reliantlabs.io/guides/hosting/promote-release-staging-to-production.md)
>
> Move a release staging runs to prod by digest.

> [card] [Escape hatches](https://docs.reliantlabs.io/forge/deploy/escape-hatches.md)
>
> Helm charts, raw manifests and other ways out of the defaults.

> [card] [env verify reference](https://docs.reliantlabs.io/reference/cli.md#reliant-forge-env-verify)
>
> Every flag and exit code of `env verify`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.