Automate registration with CI

Use this pattern for GitHub Actions, GitLab CI, or any runner that can SSH to (or run on) the agent VM.

Design principles

Service account token, not a human OAuth session
Least-privilege role (service accounts guide)
Secrets in your CI secret store — never in the repository
--yes for non-interactive confirmations
Prefer a stable --name so retries resume cleanly

Required secrets

Secret	Purpose
`NR_API_TOKEN`	Service account JWT
`NR_ORGANIZATION_ID`	Provider organization UUID (or pass `--org-id`)
`PROXMOX_URL` / `PROXMOX_USERNAME` / `PROXMOX_TOKEN_ID` / `PROXMOX_TOKEN_SECRET`	Operator install (omit if `--skip-operator-install`)

Metrics remote_write uses a Bearer token. Prefer leaving MIMIR_BEARER_TOKEN unset so register issues or rotates a credential through the API. Only set MIMIR_BEARER_TOKEN in CI if you intentionally manage that secret yourself.

Pin the nr binary version in CI (download a specific GitHub Release tag) so runners do not float unexpectedly.

Example: register on the agent host

set -euo pipefail

export NR_API_TOKEN="..."
export NR_ORGANIZATION_ID="<org-uuid>"
# export PROXMOX_* when installing the operator
# leave MIMIR_BEARER_TOKEN unset unless you manage the write token yourself

nr cluster register \
  --name "${AGENT_NAME}" \
  --agent-ip "${AGENT_IP}" \
  --gateway-region AMS01 \
  --org-id "${NR_ORGANIZATION_ID}" \
  --yes \
  --output json

On failure, re-run with the same name:

nr cluster register --resume --name "${AGENT_NAME}" --org-id "${NR_ORGANIZATION_ID}" --yes

Example: GitHub Actions sketch

# Illustrative only — run on a self-hosted runner that is the agent VM,
# or SSH into the agent VM as a step.
jobs:
  register:
    runs-on: [self-hosted, noderings-agent]
    steps:
      - name: Install nr
        run: |
          # Pin a release tag and archive name from github.com/noderings/cli/releases
          curl -fsSL -o nr.tgz \
            "https://github.com/noderings/cli/releases/download/vX.Y.Z/nr_X.Y.Z_linux_amd64.tar.gz"
          tar -xzf nr.tgz
          sudo install -m 0755 nr /usr/local/bin/nr

      - name: Register agent
        env:
          NR_API_TOKEN: ${{ secrets.NR_API_TOKEN }}
          NR_ORGANIZATION_ID: ${{ secrets.NR_ORGANIZATION_ID }}
          PROXMOX_URL: ${{ secrets.PROXMOX_URL }}
          PROXMOX_USERNAME: ${{ secrets.PROXMOX_USERNAME }}
          PROXMOX_TOKEN_ID: ${{ secrets.PROXMOX_TOKEN_ID }}
          PROXMOX_TOKEN_SECRET: ${{ secrets.PROXMOX_TOKEN_SECRET }}
          AGENT_NAME: edge-ams-01
          AGENT_IP: ${{ vars.AGENT_IP }}
        run: |
          nr cluster register \
            --name "$AGENT_NAME" \
            --agent-ip "$AGENT_IP" \
            --gateway-region AMS01 \
            --org-id "$NR_ORGANIZATION_ID" \
            --yes
          nr cluster verify --name "$AGENT_NAME" --output json

IP allowlists

If the service account has --allowed-ips, ensure the runner’s egress address is included. Otherwise API calls fail even with a valid JWT.

Exit codes for scripts

Code	Meaning
`0`	Success
`1`	Runtime / operational failure
`2`	Invalid usage (missing flags, bad arguments)

See Exit codes and output.