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

# Run a Reliant workflow from GitHub Actions

> Start a Reliant workflow from a GitHub Actions job, stream its progress into the job log, and fail the job when the run fails, using an API token secret.

By the end of this guide, a GitHub Actions job starts a Reliant workflow, streams its progress into the job log, and passes or fails with the run. The workflow can be an agent that investigates a failed build or a plain check; this guide uses a check that needs no model.

The runner only starts and watches the run. The workflow itself runs on one of your [machines](https://docs.reliantlabs.io/machines/overview.md), against a project checked out there, so it has that machine's tools and files rather than the runner's.

## Before you begin

* The `reliant` CLI on your own computer, signed in ([Sign in and tokens](https://docs.reliantlabs.io/cli/sign-in.md)).
* A machine that is online and holds the project the workflow belongs to. Runs go to the project's machine, by default your default machine.
* Admin access to the GitHub repository, to add a secret, a variable and a workflow.

**1. Add the workflow to the project**

On the machine, add a workflow to the project's `.reliant/workflows/`. This one fetches a URL and ends the run as a failure unless the fetch succeeds:

```yaml .reliant/workflows/smoke-check.yaml theme={null}
name: smoke-check
description: Fetch a deployed URL from a Reliant machine, and fail the run unless it answers
inputs:
  url:
    type: string
    required: true
    description: The URL to fetch
entry: [fetch]
nodes:
  - id: fetch
    type: run
    timeout: 2m
    args:
      command: 'curl -fsS -o /dev/null -w "%{http_code}\n" "{{ inputs.url }}"'
  - id: down
    type: save_message
    condition: "nodes.fetch.exit_code != 0"
    outcome: failure
    args:
      role: assistant
      content: "{{ inputs.url }} did not answer: curl exited {{ nodes.fetch.exit_code }}."
edges:
  - from: fetch
    default: down
```

Check it, and print the project's ID. `project create` is idempotent, so on an existing project it only prints the ID:

```bash terminal theme={null}
reliant workflow validate
reliant project create --path .
```

```text terminal theme={null}
  ✓ smoke-check.yaml (smoke-check)
7ca62f97-039c-…
```

**2. Try it from your terminal**

```bash terminal theme={null}
reliant workflow run smoke-check --project-id <project-id> \
  --input url=https://example.com/ --follow --timeout 3m
```

```text terminal theme={null}
Workflow "smoke-check" triggered
  Chat/Execution ID: fd164242-…
{"event":"node_completed",…,"node_id":"fetch",…,"new_state":"completed",…,"exit_code":0}
{"event":"node_skipped",…,"node_id":"down",…,"new_state":"skipped",…}
{"event":"workflow_completed",…,"workflow_name":"smoke-check",…,"new_state":"completed",…}
```

`--follow` prints the run's IDs, then one JSON event per line until the run ends, and exits with its result. The run is listed under **Runs** in the app.

A run that reports the workflow is not synced yet has started before the machine picked up the new file. Wait a few seconds and run it again.

**3. Create an API token and store it**

On your own computer, mint an API token and pipe it straight into the repository secret, so it is never shown. Save the project's ID as a variable:

```bash terminal theme={null}
reliant auth token create --name github-actions \
  | grep -o 'rlat_[A-Za-z0-9]*' | gh secret set RELIANT_TOKEN
gh variable set RELIANT_PROJECT_ID --body <project-id>
```

You approve it in the browser, or with a device code (`--device`). The token acts as you, lasts 90 days, and covers the whole API (`reliant:api`). `reliant workflow run` needs that scope: a token narrowed with `--scope runs:start` is refused with `this credential lacks the reliant:api scope`.

**4. Add the Actions workflow**

```yaml .github/workflows/smoke-check.yml theme={null}
name: smoke-check
on:
  workflow_dispatch:
    inputs:
      url:
        description: The URL to check
        required: true
permissions:
  contents: read
jobs:
  smoke:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    env:
      RELIANT_TOKEN: ${{ secrets.RELIANT_TOKEN }}
    steps:
      - uses: actions/setup-go@v6
        with:
          go-version: stable
          cache: false
      - id: cli-cache
        uses: actions/cache@v4
        with:
          path: ~/go/bin/reliant
          key: reliant-cli-v1.21.3-${{ runner.os }}-${{ runner.arch }}
      - name: Install the Reliant CLI
        if: steps.cli-cache.outputs.cache-hit != 'true'
        run: go install github.com/reliant-labs/reliant/cmd/reliant@v1.21.3
      - name: Run smoke-check and wait for its verdict
        env:
          PROJECT_ID: ${{ vars.RELIANT_PROJECT_ID }}
          URL: ${{ inputs.url }}
        run: |
          reliant workflow run smoke-check --project-id "$PROJECT_ID" \
            --input url="$URL" --title "smoke-check · ${GITHUB_SHA::7}" \
            --follow --timeout 15m \
            --hook "on=node_failed cmd=echo ::error::Reliant step \$RELIANT_EVENT_NODE_ID failed in run \$RELIANT_EVENT_EXECUTION_ID"
```

The job builds the CLI with `go install`, pinned to the version you run locally (`reliant version`). The first build takes about seven minutes; the cache saves the binary when the job succeeds, so later runs skip it. From v1.24.0 you can download the release's prebuilt CLI archive instead of building it; see [CLI only](https://docs.reliantlabs.io/getting-started/installation.md#cli-only-headless-linux-ci-runners).

`--hook` runs a command for each step that fails, here an error annotation. It hooks `node_failed` because a run that ends at an `outcome: failure` node finishes as `workflow_completed` with `"outcome":"failure"`, so `workflow_failed` does not fire for it.

**5. Run it and read the result**

Start it from the **Actions** tab, or with `gh workflow run smoke-check.yml -f url=https://your-site.example/`.

The step's log shows the run starting on your machine and each step's result:

```text smoke job theme={null}
Workflow "smoke-check" triggered
  Chat/Execution ID: 57a178a0-d667-42fa-8706-506998a803b1
{"event":"node_completed",…,"node_id":"fetch",…,"new_state":"completed",…,"exit_code":0}
{"event":"node_skipped",…,"node_id":"down",…,"new_state":"skipped",…}
{"event":"workflow_completed",…,"workflow_name":"smoke-check",…,"new_state":"completed",…}
```

The step exits `0` and the job passes. The run took four seconds; the job's first run spent eight minutes, almost all of it building the CLI.

**6. See a failing run fail the job**

Run it again with a URL that does not exist. `curl` exits `22`, the hook writes an annotation, the run ends at `down`, which declares `outcome: failure`, and `--follow` exits `1`:

```text smoke job theme={null}
{"event":"node_failed",…,"node_id":"fetch",…,"new_state":"failed",…,"exit_code":22}
Error: Reliant step fetch failed in run b15e7f0d-a445-48d3-b3fa-52045e26f0c6
{"event":"node_completed",…,"node_id":"down",…,"new_state":"completed",…}
{"event":"workflow_completed",…,"workflow_name":"smoke-check",…,"new_state":"completed",…,"outcome":"failure"}
Error: Process completed with exit code 1.
```

The error appears as an annotation on the job's summary page, with the run's ID to open it under **Runs**.

**7. Revoke the token when you are done**

The token is stored under the name `reliant-cli@github-actions`, and `revoke` takes that full name or the ID from `reliant auth token list`:

```bash terminal theme={null}
reliant auth token revoke reliant-cli@github-actions
gh secret delete RELIANT_TOKEN
```

## Exit codes the job sees

`reliant workflow run --follow` exits with the run's result, so the step needs no parsing:

| Code | Meaning |
| - | - |
| `0` | The run completed and passed |
| `1` | The run failed, was cancelled or expired, or ended at a node with `outcome: failure` |
| `2` | `--timeout` elapsed before the run finished. The run keeps going |
| `3` | With `--exit-on-gate`, a question or approval opened |

A workflow that asks a person something waits for an answer in the Inbox. For a job that should stop there instead, add `--exit-on-gate`, or use `reliant workflow wait-for-gate <execution-id>`, which exits `3` with the open gate. [Scripting and CI](https://docs.reliantlabs.io/cli/scripting.md#exit-codes) has every command's codes.

## What this does not do

* **The runner does not run the workflow.** It runs on the project's machine, from the workflow file in that checkout. A workflow file changed in the pull request is not what runs until the machine's checkout has it.
* **In an organization, runs started with a token spend only the organization's AI accounts.** A workflow with an agent step needs an organization AI account that can run its model; a run-only workflow like this one needs none.
* **No short-lived or narrow credential.** There is no OIDC login from GitHub Actions to Reliant. The token lasts 90 days and can do anything you can through the API, so keep it to repositories you trust, and revoke it when you rotate it.
* **Actions is optional for GitHub events.** A workflow can declare its own GitHub trigger and post its own check run ([A GitHub check](https://docs.reliantlabs.io/workflows/patterns.md#a-github-check-check)).

## Troubleshooting

> [accordion] starting workflow: permission\_denied: this credential lacks the reliant:api scope
>
> The token in `RELIANT_TOKEN` was created with `--scope`. `reliant workflow run` needs the whole API: create the token again without `--scope`, under the same `--name` to replace it.

> [accordion] not logged in to [https://api.reliantapi.com](https://api.reliantapi.com) … — run 'reliant auth login', or set RELIANT\_TOKEN
>
> The job has no `RELIANT_TOKEN`. Check the secret's name and that the job's `env:` passes it. Workflows run from forks get no secrets.

> [accordion] rendered empty, so its command was not run
>
> The run started with an empty input. Reliant refuses to run a shell command with an empty value in it. Check that the variable or input you pass to `--input` is set.

## Next steps

> [card] [Deploy from GitHub Actions](https://docs.reliantlabs.io/guides/hosting/deploy-from-github-actions.md)
>
> Deploy to Reliant hosting from the same pipeline.

> [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] [Scripting and CI](https://docs.reliantlabs.io/cli/scripting.md)
>
> Tokens, JSON output, exit codes and event hooks.

> [card] [Test workflows with scenarios](https://docs.reliantlabs.io/guides/workflows/test-workflows-with-scenarios.md)
>
> Check a workflow's paths on every pull request without running it.


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