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 (for example, 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 checks these in order:

1. --token <key> flag (not recommended in CI, because it appears in process tables and logs)
2. REOCLO_AUTOMATION_KEY environment variable
3. The active stored login profile (only if logged in)

REOCLO_MACHINE_TOKEN is checked between the --token flag and REOCLO_AUTOMATION_KEY. See Machine users below.

Legacy secret name

If you still call your CI secret REOCLO_API_KEY, keep passing it to the api_key input on the action. The CLI receives REOCLO_AUTOMATION_KEY.

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
secrets inject	Render an op:// template file and resolve the values from the Secrets Manager

Every other command is rejected with exit code 4. Run those from an interactive reoclo login session instead, or use a machine user.

Machine users

An automation key runs only a fixed set of commands. A pipeline or agent that needs more, such as servers, deployments, or secrets, needs a machine user instead. A machine user is a full organization member with a role, authenticated by a token instead of a browser. See Machine Users for the full comparison.

Variable	Credential
REOCLO_AUTOMATION_KEY	Automation key (rca_); the restricted command surface above
REOCLO_MACHINE_TOKEN	Machine user token (rk_m_); full command surface, tenant routing

Each variable holds one credential class. A token in the wrong variable makes the CLI exit with code 2.

Exit codes

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

Code	Meaning
0	Success
1	Generic error: server-side failure, validation, anything without a more specific code
2	Misuse (bad arguments, unknown command)
3	Authentication failure: the token is missing, invalid, or expired
4	Not permitted: the command is not allowed for this key type, or the API refused it
5	Resource not found
6	reoclo run could not resolve secrets, so the child never started
7	The control plane was unreachable: DNS failure, connection refused, or timeout

The line between 3 and 4 is who versus whether: 3 means Reoclo could not establish who you are, 4 means it could and the answer is no. Rotate or replace the key for 3. Ask for access for 4.

Codes 6 and 7 need CLI 0.55.0 or newer

Earlier versions report 1 for both an unresolvable reoclo run and an unreachable control plane. If you pin an older CLI, branch on 1 and read stderr instead.

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 credential 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 or a machine user token (CLI 0.68.0 or newer). An interactive reoclo login session 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 6 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.

Rendering a template file

Both reoclo run and reoclo secrets inject can render a template file of op:// references, resolving each value from the Secrets Manager. This is the drop-in for a pipeline that already keeps a .env template for 1Password’s op inject or op run. The values come from Reoclo, so the op command is not required.

reoclo run --env-file <file> injects the resolved values into a command:

      - name: Migrate with a template
        env:
          REOCLO_AUTOMATION_KEY: ${{ secrets.REOCLO_AUTOMATION_KEY }}
        run: reoclo run --env-file app.env.tpl -- ./migrate.sh

reoclo secrets inject -i <file> -o <file> writes the rendered file, for a step that needs a real .env on disk:

      - name: Render the .env file
        env:
          REOCLO_AUTOMATION_KEY: ${{ secrets.REOCLO_AUTOMATION_KEY }}
        run: reoclo secrets inject -i app.env.tpl -o .env

Each reference is op://<project>/<item>/<field>. Reoclo maps it to the secret <field> in the project <project> and ignores <item>. Grant the key read on each project the template names. See reoclo run and reoclo secrets inject.

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.