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

# Deploy from GitHub Actions with an API token

> Ship every push to main from GitHub Actions: store a scoped deploy token, cut the release and print its plan in one job, then approve that exact plan in the next.

By the end of this guide, every push to `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](https://docs.reliantlabs.io/forge/deploy/releases-and-promotion.md)).

## Before you begin

* A forge project with an environment bound to [Reliant hosting](https://docs.reliantlabs.io/hosting/overview.md), committed to a GitHub repository. [Deploy a static site to a CDN](https://docs.reliantlabs.io/guides/forge/deploy-static-site-cdn.md) creates one. This guide deploys `prod`.
* `forge_version` in `forge.yaml` naming 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:

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

```text terminal theme={null}
PLAN (approved — recording and publishing follow): promote env "prod" → release 20261120.114929-fb51b7ffafd6
  direction INITIAL  FIRST PROMOTE — this environment has never been bound to a release, so there is nothing to move from
  url web: https://iron-vicuna.sites.reliantlabs.dev (served through the CDN edge)
Rollout of 20261120.114929-fb51b7ffafd6 to prod: SUCCEEDED
```

**2. Create a deploy token and store it**

In the web app, open [Settings → API tokens](https://forge.reliantlabs.io/settings/tokens) with your organization active. Create a token with three scopes: `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:

```bash terminal theme={null}
gh secret set FORGE_CONTROL_PLANE_TOKEN
```

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: `reliant forge cloud token create` refuses a CLI sign-in.

**3. Add the workflow**

```yaml .github/workflows/deploy.yml theme={null}
name: deploy
on:
  push:
    branches: [main]
  workflow_dispatch:
concurrency:
  group: deploy-prod
  cancel-in-progress: false
permissions:
  contents: read
jobs:
  plan:
    runs-on: ubuntu-latest
    env:
      FORGE_CONTROL_PLANE_TOKEN: ${{ secrets.FORGE_CONTROL_PLANE_TOKEN }}
    outputs:
      release: ${{ steps.plan.outputs.release }}
      digest: ${{ steps.plan.outputs.digest }}
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v5
        with:
          node-version: 22
      - name: Install the forge this project pins
        run: |
          npm install -g "@reliantlabs/forge@$(sed -n 's/^forge_version: v//p' forge.yaml)"
      - id: plan
        name: Build, cut the release and print the plan
        run: |
          forge env deploy prod --plan-only --json > "$RUNNER_TEMP/plan.json"
          echo "release=$(jq -r .target.release "$RUNNER_TEMP/plan.json")" >> "$GITHUB_OUTPUT"
          echo "digest=$(jq -r .deploy_plan.digest "$RUNNER_TEMP/plan.json")" >> "$GITHUB_OUTPUT"
  deploy:
    needs: plan
    runs-on: ubuntu-latest
    environment: production
    env:
      FORGE_CONTROL_PLANE_TOKEN: ${{ secrets.FORGE_CONTROL_PLANE_TOKEN }}
      RELEASE: ${{ needs.plan.outputs.release }}
      DIGEST: ${{ needs.plan.outputs.digest }}
    steps:
      - uses: actions/checkout@v5
      - name: Install the forge this project pins
        run: |
          npm install -g "@reliantlabs/forge@$(sed -n 's/^forge_version: v//p' forge.yaml)"
      - name: Deploy exactly the plan that was printed
        run: forge env deploy prod "$RELEASE" --approve "$DIGEST"
      - name: Prove the release good
        run: |
          code=0
          forge obs check prod --wait --json > "$RUNNER_TEMP/check.json" || code=$?
          case $code in
            0) echo "release is good" ;;
            2) echo "::warning::not proven good: $(jq -r .reason_code "$RUNNER_TEMP/check.json")" ;;
            8) echo "::warning::the check window is still open; run forge obs check prod later" ;;
            *) exit "$code" ;;
          esac
```

The runner needs no `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 `main`. The `plan` job builds the site, cuts a release and prints what will change, without writing anything:

```text plan job theme={null}
[deploy] cutting new release 20261120.151748-253f56eccbcf because no release in https://admin.reliantapi.com records this checkout's tree (253f56eccbcf)
[build] Cut release 20261120.151748-253f56eccbcf (1 image(s), 0 package(s), 0 file(s)): …/guides-sandbox-ghactions/web/static.v1, web.sourcemaps
  plan digest: sha256:3afdea413ed549f6ea018fe3586d16229a387a2ed16c00a0abf1d3cb03b9972e
PLAN (dry run — nothing was written): promote env "prod" → release 20261120.151748-253f56eccbcf
  direction AHEAD  FORWARD — 20261120.151748-253f56eccbcf is 1 release(s) NEWER than 20261120.150135-cc2656a33c4f (by cut time)
```

The `deploy` job installs forge again, builds nothing, and promotes that release only if the plan still has that digest:

```text deploy job theme={null}
PLAN (approved — recording and publishing follow): promote env "prod" → release 20261120.151748-253f56eccbcf
  expected  1d1d0df6-0644-406f-a767-e3f833915515  (compare-and-set: the write is refused if the env moved since)
  url web: https://iron-vicuna.sites.reliantlabs.dev (served through the CDN edge)
Rollout of 20261120.151748-253f56eccbcf to prod: SUCCEEDED
Promoted env "prod": 20261120.150135-cc2656a33c4f → 20261120.151748-253f56eccbcf
```

**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**

```bash terminal theme={null}
curl -s https://iron-vicuna.sites.reliantlabs.dev/ | grep -o '<title>[^<]*'
reliant forge env releases list prod
```

```text terminal theme={null}
<title>guides-sandbox-ghactions (deployed from GitHub Actions, run 2)
AT                    RELEASE                              WHAT                                      WHO                       ROLLOUT
2026-11-20 16:05:45Z  20261120.151748-253f56eccbcf (live)  promote (from 20261120.150135-cc2656a33…  you@example.com via ci    succeeded 5s
2026-11-20 15:02:40Z  20261120.150135-cc2656a33c4f         promote (from 20261120.114929-fb51b7ffa…  you@example.com via ci    succeeded 5s
2026-11-20 11:50:36Z  20261120.114929-fb51b7ffafd6         first promote                             you@example.com via cli   succeeded 5s
```

The page carries the change you pushed, and the release CI cut is `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:

```text deploy job theme={null}
Error: release 20261120.163752-74106d5d60af: INCONCLUSIVE — no request telemetry: no service sent a single server span in either window, no request reached one through the platform's ingress, and no page sent browser telemetry, …
Warning: not proven good: no_request_telemetry
```

## Exit codes to handle

`forge env deploy` uses its exit code to say what happened, and the workflow fails on anything other than `0`:

| Code | Meaning in CI |
| - | - |
| `0` | Deployed and healthy, already on this release, or `--plan-only` printed the plan |
| `3` | Production moved since the plan was read. Stop and look; do not retry blindly |
| `4` | Another rollout is in flight, or a health gate has no verdict yet. Nothing was lost; retry later |
| `5` | No `--yes` or `--approve`, so nothing was promoted |
| `7` | Queued on billing. Recorded, and goes live by itself once billing is set up |
| `8` | Still applying when the wait ran out. Nothing failed; check `forge env status prod --wait` |

`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](https://docs.reliantlabs.io/guides/hosting/recover-from-bad-deploy.md)).

## Troubleshooting

> [accordion] no control-plane credential for [https://admin.reliantapi.com](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.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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

> [card] [Run a Reliant workflow from GitHub Actions](https://docs.reliantlabs.io/guides/workflows/run-workflow-from-github-actions.md)
>
> Start a workflow from the same pipeline and fail the job when it fails.

> [card] [Preview every pull request](https://docs.reliantlabs.io/guides/hosting/preview-environment-every-pull-request.md)
>
> Give each pull request its own hosted copy from Actions.

> [card] [Gate production on release health](https://docs.reliantlabs.io/guides/hosting/gate-production-deploy-release-health.md)
>
> Refuse a promotion until staging proves the release good.

> [card] [Scripting and CI](https://docs.reliantlabs.io/cli/scripting.md)
>
> Tokens, JSON output and exit codes for every CLI command.


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