CI/CD automation

The CLI is designed for unattended use in CI pipelines. The recommended pattern is:

1. Create an Automation Key scoped to a single application or server.
2. Store it as a CI secret (e.g. REOCLO_AUTOMATION_KEY).
3. Run reoclo directly without reoclo login on the runner.

Authentication for CI

Automation keys begin with the rca_ prefix. The CLI reads them from environment variables in this order:

1. --token <key> flag (not recommended in CI; appears in process tables and logs)
2. REOCLO_AUTOMATION_KEY (preferred)
3. REOCLO_API_KEY
4. The active stored profile (only if logged in)

Automation keys can run a restricted set of commands:

Command	Purpose
apps deploy	Deploy an application
apps restart	Restart an application
exec	Run a command on a server
shell	Open a non-interactive shell on a server
checkout	Clone or update a repo on a server
registry login / registry logout	Authenticate to a container registry on a server
deploy sync	Sync proxy routes after a deploy
run	Resolve granted secrets and inject them into a local command

Every other command is rejected with exit code 4. Run those from an interactive reoclo login session instead.

Exit codes

Scripts and pipelines can branch on the CLI’s exit code:

Code	Meaning
0	Success
1	Generic error (network, server-side failure, validation)
2	Misuse (bad arguments, unknown command)
3	Authentication or authorization failure
4	Command not allowed for the current key type
5	Resource not found

GitHub Actions

name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Reoclo CLI
        run: curl -sSL https://get.reoclo.com/cli | bash
      - name: Deploy
        env:
          REOCLO_AUTOMATION_KEY: ${{ secrets.REOCLO_AUTOMATION_KEY }}
        run: reoclo apps deploy my-app --ref ${{ github.sha }}

For GitHub-hosted runners that ship Node.js, the npm install path is also fine:

      - run: npm i -g @reoclo/cli

Woodpecker

steps:
  deploy:
    image: oven/bun:1
    secrets: [reoclo_automation_key]
    commands:
      - curl -sSL https://get.reoclo.com/cli | bash
      - REOCLO_AUTOMATION_KEY=$REOCLO_AUTOMATION_KEY reoclo apps deploy my-app --ref ${CI_COMMIT_SHA}
    when:
      branch: main
      event: push

GitLab CI

deploy:
  stage: deploy
  image: alpine:3
  before_script:
    - apk add --no-cache curl bash
    - curl -sSL https://get.reoclo.com/cli | bash
  script:
    - reoclo apps deploy my-app --ref $CI_COMMIT_SHA
  only:
    - main

Set REOCLO_AUTOMATION_KEY as a masked variable in the project’s CI/CD settings.

Gitea Actions

Gitea’s act_runner is GitHub-Actions-compatible, so the CLI behaves identically — the same REOCLO_AUTOMATION_KEY secret and the same commands work unchanged. The runner also sets GITHUB_SHA and GITHUB_RUN_ID, so audit-trail attribution works out of the box.

name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Install Reoclo CLI
        run: curl -sSL https://get.reoclo.com/cli | bash
      - name: Deploy
        env:
          REOCLO_AUTOMATION_KEY: ${{ secrets.REOCLO_AUTOMATION_KEY }}
        run: reoclo apps deploy my-app --ref ${{ github.sha }}

The runner must be able to reach get.reoclo.com to install the CLI. For the packaged reoclo/checkout, reoclo/run, and reoclo/docker-auth actions on Gitea, see Reoclo in CI.

Injecting Secrets Manager values

reoclo run resolves the Secrets Manager values your automation key is granted, injects them into a child process as environment variables, and runs it. Values are never written to disk or printed, and the child’s exit code is passed through. This is how you consume managed secrets in any CI system, including Gitea.

reoclo run requires an automation key — a tenant or reoclo login token is rejected with exit code 4.

      - name: Run migrations with injected secrets
        env:
          REOCLO_AUTOMATION_KEY: ${{ secrets.REOCLO_AUTOMATION_KEY }}
        run: reoclo run -- ./migrate.sh

• Grant the key read on the target secret project(s) first — a tenant admin does this from the project’s Access tab (see Granting access). Without a grant, resolution fails with exit code 1 and the child process does not run.
• -p, --project <name> limits injection to specific projects and is repeatable; omit it to inject every project the key can read.
• --commit <sha> records a commit in the audit trail. GITHUB_SHA and GITHUB_RUN_ID are picked up automatically on GitHub and Gitea runners.

Values injected this way come from Reoclo, not from your CI provider’s secret store, so your CI provider does not mask them — never echo an injected value. See Injecting secrets into CI for a full walkthrough and reoclo run for the command reference.

Output formats for scripting

Pass -o json (or -o yaml) on any read command for stable, machine-readable output:

LATEST=$(reoclo deployments ls --limit 1 -o json | jq -r '.[0].id')
reoclo deployments get "$LATEST" -o json

The text output is intended for humans and may change between releases without notice. JSON and YAML output is part of the CLI’s public contract.

Secrets hygiene

• Never echo $REOCLO_AUTOMATION_KEY in CI logs.
• Use the CI provider’s secret-masking feature.
• Rotate Automation Keys when team members leave or runners are decommissioned.
• Prefer per-application keys over per-tenant keys.