Deploy from GitHub Actions

Use rigbox-dev/deploy-action to deploy on a push. The Action exchanges GitHub’s OpenID Connect identity for a short-lived Rigbox credential scoped to one existing workspace. You do not store a Rigbox API key or register an SSH key on the runner. This v0.13 preview requires a compatible deploy Action revision and Rigbox CLI v0.13.0 or newer. Verify the Action release supports your target CLI before enabling the workflow. GitHub OIDC deployments must be enabled for your Rigbox account. For automatic deployments without a workflow, connect a repository through the workspace creation page or the workspace’s GitHub deployment settings. Automatic pull-request preview environments are not yet supported.

Prerequisites

Install the CLI on your machine and run rig --version. Use v0.13.0 or newer.
Have an existing target workspace and a GitHub repository where you can add workflows.
Enable GitHub OIDC deployments for your Rigbox account.
Prepare a working app with known install/start commands, port, and health path.

For automatic deployments managed in the console, use Deploy from GitHub. Continue here when deployment belongs in your own GitHub Actions workflow.

1. Prepare the manifest

Every app deployed from CI must declare source.kind: git and the HTTPS URL of the workflow’s repository. Local source deployments are rejected before deployment starts. For incremental deployment, declare workspace.deployment.strategy: incremental. Private Git source is supported by the v0.13 incremental path using the job token. For image deployment, set reproducible: true on every app. Add the source settings to your existing rig.yaml:

name: web
port: 3000
source:
  kind: git
  repo: https://github.com/YOUR_ORG/YOUR_REPO
  branch: main
workspace:
  deployment: { strategy: incremental }
install: npm ci
start: npm start
health:
  path: /healthz
  timeoutSeconds: 60
visibility: public

Replace the repository URL, commands, port, and health path with your app’s values. In a multi-app manifest, put source in each app definition and strategy in the root workspace block. See Deploying with rig deploy for manifest shapes. The deployed source is the exact GITHUB_SHA from the workflow. The CLI records that SHA in source provenance. Incremental deployment prepares managed app releases; image deployment uses a frozen build whose inputs include the revision. Neither path should silently deploy an uncommitted runner checkout instead of the verified commit.

2. Link the repository

From your project directory on your machine, authenticate with your full Rigbox account credential and link an existing workspace:

rig login
rig ci link --repo YOUR_ORG/YOUR_REPO --workspace production
rig ci status --repo YOUR_ORG/YOUR_REPO

The current rig ci link --private preflight still requires reproducible: true for each app. For a private incremental project, keep that field to pass linking and also declare workspace.deployment.strategy: incremental explicitly so it overrides the reproducible default. Then link with --private:

rig ci link --repo YOUR_ORG/YOUR_REPO --workspace production --private

--workspace accepts a name or ID. --from <directory> selects another project directory for manifest validation. The Action takes its target from this binding, so a fresh checkout without .rig.lock deploys to the same workspace. The new binding is pending for 24 hours. The first claim relies on control of the configured repository name during this window; verify the name before linking. Its first successful OIDC exchange claims it and makes it active. If the window expires, rerun the same link command and then run the workflow. Repeating the command for an active binding preserves its identity. Once claimed, the binding stores GitHub’s immutable repository and owner IDs. A deleted-and-recreated repository cannot inherit access by taking the same name. Repository ownership transfers require the Rigbox account owner to unlink and link again; the old owner ID is rejected.

rig ci unlink --repo YOUR_ORG/YOUR_REPO --workspace production

Unlinking removes the binding and revokes credentials issued through it. Run rig ci status without --repo to list your bindings. These setup commands require an account credential; a deployment credential cannot manage bindings.

3. Add the workflow

Create .github/workflows/deploy.yml in the linked repository:

name: Deploy
on:
  push:
    branches: [main]
  workflow_dispatch:
permissions:
  contents: read
  id-token: write
concurrency:
  group: rigbox-production
  cancel-in-progress: false
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          persist-credentials: false
      - uses: rigbox-dev/deploy-action@v1
        id: deploy
        with:
          cli-version: v0.13.0

Use your deployment branch instead of main if needed. Keep changes to the deployment workflow under the repository’s normal review controls. You can pin the Action to a reviewed commit rather than a moving major-version tag. The Action requests the audience https://api.rigbox.dev, validates the exchanged repository and commit, then runs rig deploy --workspace <bound-id> --output json. Both identity and deploy credentials are masked immediately. For private source, it supplies the job’s ephemeral github.token for authenticated source retrieval; no token is stored in the manifest or build record. Public source is fetched anonymously. CI does not create or register an account SSH key.

First image deployment to an existing workspace

This section applies only when the manifest selects image strategy. Do not enable re-image for an incremental deployment. A workspace that is not already image-pinned may require explicit consent before its first reproducible deployment. Re-imaging replaces the workspace filesystem and discards files stored there. Back up data you need to keep, then set this input for that setup deployment:

      - uses: rigbox-dev/deploy-action@v1
        with:
          cli-version: v0.13.0
          reimage: "true"

Remove reimage after setup. It defaults to false; the Action never enables disk replacement automatically. Keep durable data in persistent volumes.

4. Run and verify

Commit the manifest and workflow, then push to the configured branch or run the workflow manually from GitHub’s Actions tab. Open the deployment job and inspect its result. Use rig ci status --repo YOUR_ORG/YOUR_REPO to confirm the binding is active after the first successful identity exchange. Check the job’s success, app outcomes, and URL; a successful identity exchange alone does not mean the app deployed successfully. See Results and failures if the job fails.

Inputs and runner support

Input	Default	Purpose
`cli-version`	`latest`	Stable CLI version, at least v0.13.0. Pin a release for repeatability.
`working-directory`	`.`	Directory containing `rig.yaml`.
`api-url`	`https://api.rigbox.dev`	HTTPS API base URL.
`audience`	`https://api.rigbox.dev`	OIDC audience accepted by that server.
`reimage`	`false`	`true` explicitly allows workspace filesystem replacement.

Linux x64 and macOS Intel/Apple Silicon are supported. The installer verifies the release asset’s SHA256 digest before executing it. Linux ARM fails explicitly while no rigbox-linux-arm64 asset is published. Runners need Bash and Python 3.9 or newer.

Application environment values

Workflow env: supplies values for the manifest’s existing secrets declarations:

      - uses: rigbox-dev/deploy-action@v1
        env:
          APP_TOKEN: ${{ secrets.APP_TOKEN }}
        with:
          cli-version: v0.13.0

secrets:
  - name: APP_TOKEN

Application values are separate from the Action’s short-lived deployment credential. Rigbox currently stores app environment values as plaintext metadata. Authorized callers can read them through GET /apps, rig app env ls --reveal, or JSON environment output. The manifest’s secrets field reads values without committing them to rig.yaml; it is not an encrypted Rigbox secrets store. Encryption at rest and restricted readback remain separate work.

Results and failures

The Action reads the CLI’s terminal deploy_finished event, including partial failures. It exposes workspace-id, url (the first app URL), apps (JSON app outcomes), success, failures, duration-ms, result (the full event), and exit-code. A failed app fails the job even when other apps succeeded. The CLI’s nonzero exit code is preserved. If deployment fails before its terminal event, only the workspace ID, failure status, and exit code are available. Use if: always() on a follow-up step when reading failure outputs.

Problem	Next step
OIDC request variables missing	Add `permissions: id-token: write` to the workflow or job.
No permitted binding	Check `rig ci status`, the repository URL, and the workspace owner. Renew an expired pending binding.
GitHub OIDC deployments disabled	Enable the capability for your Rigbox account before retrying.
Repository transferred or recreated	Review the new ownership, then unlink and link again.
Private source refused	Use a compatible v0.13 CLI/Action, keep `source.kind: git`, and grant `contents: read`. Image strategy also requires reproducible app settings.
Re-image consent required	Review the filesystem replacement above before explicitly setting `reimage: "true"`.
CLI too old or ARM asset missing	Use a supported release and runner architecture.

Deployment credentials expire after 60 minutes and cannot be reused to manage the account or another workspace. Each GitHub identity token can be exchanged once; rerun the workflow to request a new identity instead of replaying a captured token.

Deploy from an example README

For a browser-based flow without a local CLI or workflow file, use Deploy to Rigbox buttons. Each workspace gets a deployment branch, so one fork can serve several independent targets.

Start here

Deploy applications

Configure applications

Workspaces and storage

AI and tools

Operate and troubleshoot

Examples

CLI reference

Build on Rigbox

Deploy from GitHub Actions

Prerequisites

1. Prepare the manifest

2. Link the repository

3. Add the workflow

First image deployment to an existing workspace

4. Run and verify

Inputs and runner support

Application environment values

Results and failures

Deploy from an example README

​Prerequisites

​1. Prepare the manifest

​2. Link the repository

​3. Add the workflow

​First image deployment to an existing workspace

​4. Run and verify

​Inputs and runner support

​Application environment values

​Results and failures

​Deploy from an example README

Prerequisites

1. Prepare the manifest

2. Link the repository

3. Add the workflow

First image deployment to an existing workspace

4. Run and verify

Inputs and runner support

Application environment values

Results and failures

Deploy from an example README