main deploys your forge project to Reliant hosting from GitHub Actions. One job builds the site, cuts a release and prints the plan. A second job deploys exactly that plan, and can wait for a reviewer first.
Splitting the two works because a forge release is cut once and promoted by digest: the deploy job builds nothing, and an approval bound to the plan’s digest is refused if production moved in between (Releases and promotion).
Before you begin
- A forge project with an environment bound to Reliant hosting, committed to a GitHub repository. Deploy a static site to a CDN creates one. This guide deploys
prod. forge_versioninforge.yamlnaming a published forge release, v1.6.1 or later. The runner installs exactly that version.- Admin access to the repository, to add a secret, a workflow and an environment.
1
Deploy once from your own machine
The first promotion of an environment has nothing to diff against, so it has no plan digest to approve. Do it by hand, signed in:
terminal
terminal
2
Create a deploy token and store it
In the web app, open Settings → API tokens with your organization active. Create a token with three scopes: The token acts as you, limited to its scopes and to what you hold in the organization. On Reliant cloud, CI tokens come from the web app:
deploy:read and deploy:write to cut and promote releases, and obs:read to read release health. Pick the shortest expiry, 30 days. Store it as the repository secret forge reads:terminal
reliant forge cloud token create refuses a CLI sign-in.3
Add the workflow
.github/workflows/deploy.yml
reliant CLI: npm install -g @reliantlabs/forge@<version> installs forge at the version forge.yaml pins. Install exactly that version, because any other forge hands the command to the pinned one by building it with Go.Write the plan to $RUNNER_TEMP, not the checkout: an untracked file makes the tree dirty, and forge then cuts a DIRTY TREE release that matches no commit.4
Push and read the run
Push to The
main. The plan job builds the site, cuts a release and prints what will change, without writing anything:plan job
deploy job installs forge again, builds nothing, and promotes that release only if the plan still has that digest:deploy job
5
Require a reviewer before production
In the repository, open Settings → Environments → production and add Required reviewers. The
deploy job then waits after plan has printed what will change, and runs only when a reviewer approves. Because the approval is bound to the digest, a deploy that landed while the job waited makes it fail with exit 3 (plan_stale) instead of shipping a change nobody reviewed.6
Check that production serves the new release
terminal
terminal
live. via ci marks promotions written from Actions, under the token’s owner.The last step waits for the release’s after window to close, about six minutes, then reads its health. A site nobody has visited yet has nothing to judge, so the check exits 2 and the step leaves a warning rather than failing the job:deploy job
Exit codes to handle
forge env deploy uses its exit code to say what happened, and the workflow fails on anything other than 0:
reliant forge env deploy --help lists every code. forge obs check has its own: 0 good, 1 regressed, 2 not proven good, 8 the window is still open.
What this does not do
- No short-lived credential. There is no OIDC or other federated login from GitHub Actions to Reliant. The token is stored in GitHub and lasts at least 30 days, so revoke it in Settings → API tokens when you rotate it.
- Not an organization token. A web-app token acts as the person who made it. If that person loses deploy access, deploys from CI stop.
- No automatic rollback. A release that fails its check stays live until you deploy another one (Recover from a bad deploy).
Troubleshooting
no control-plane credential for https://admin.reliantapi.com
no control-plane credential for https://admin.reliantapi.com
The job has no
FORGE_CONTROL_PLANE_TOKEN. Check that the secret exists with that exact name and that the job’s env: passes it. Secrets are not given to workflows run from forks.machine credentials cannot manage machine credentials
machine credentials cannot manage machine credentials
reliant forge cloud token create was run with a CLI or machine sign-in. Create the token in the web app instead, as in step 2.promote refused (rollout_in_flight)
promote refused (rollout_in_flight)
Exit
4: the control plane still counts the previous promotion as rolling out, so it refused this one and wrote nothing. Wait for it with reliant forge env status prod --wait, then re-run the failed job: it approves the same digest and builds nothing. --supersede replaces the unfinished rollout on purpose, and is recorded.Process completed with exit code 5
Process completed with exit code 5
The deploy step had neither
--yes nor --approve. With no terminal to prompt on, forge cut the release and promoted nothing.Next steps
Run a Reliant workflow from GitHub Actions
Start a workflow from the same pipeline and fail the job when it fails.
Preview every pull request
Give each pull request its own hosted copy from Actions.
Gate production on release health
Refuse a promotion until staging proves the release good.
Scripting and CI
Tokens, JSON output and exit codes for every CLI command.