Roll it out across teams & environments

Getting from one engineer's laptop to an org-wide, always-current catalog is mostly about committing config and scheduling a re-scan — Regixo is a command you run, not a daemon you host. This page is that rollout as four steps, in order, then the branches a real estate hits: multiple repos and environments, an honest account of what multi-entity does not do yet, and the one failure — SYNC_UNAUTHORIZED — with its fix.

Roll one estate out, all the way through (the worked example)

Before the reference, take one estate from a laptop to a fed, hosted record. Aurelia Payments already has the committed regixo.yml from the last page, and Maija has claimed the record. Here is each step for it:

The four sections below are that same rollout, walked in full.

Step 1 · Commit the config

The move from a personal run to a repeatable org run is three commits:

1. Commit regixo.yml. With sources (by env-var name), intent, DORA scope and PII policy in the file, any machine — a colleague's or a CI runner — scans the same estate. Secrets stay in the environment.
2. Make it run headless. Off a TTY, in CI, or with --yes, every command runs non-interactively: it takes answers from flags, env and regixo.yml and never prompts. A committed config plus --yes is a fully unattended refresh.
3. Seed the shared standards. Commit a house glossary and PII policy once, then bring them in on each machine with regixo catalog import regixo-catalog.json (merge-only — it never downgrades a confirmed answer).

Step 2 · Make it re-scan without anyone remembering

The goal: the map refreshes on a schedule, whether or not your laptop is on. regixo watch is a one-shot re-scan you schedule — from cron or CI — not a hosted daemon that sits running. Each run re-scans, updates the map, appends the change-log, and flags any signed activity whose core fields moved for re-sign.

$ regixo watch --ci >> "$GITHUB_STEP_SUMMARY"

What your agent will do. It should write .github/workflows/regixo-watch.yml, wire the step to regixo watch --ci >> "$GITHUB_STEP_SUMMARY", and handle exit code 3 so a core-field change raises a build warning rather than failing the job. Check the file it writes against the step in the terminal recipe below.

A ready-made GitHub Actions workflow ships in the repo at examples/github-actions/regixo-watch.yml. The source is AGPL-3.0 but not public yet, so until it is, copy the step from the terminal recipe below. Set your source secrets as Actions secrets, and a scheduled run writes its summary to the job's step summary and raises a build warning (exit 3) on a core-field change — it does not fail the job, and it does not comment on pull requests.

How to check it worked. Trigger the workflow once by hand. A green run with a change summary in the job's step summary means the schedule works; exit 3 (shown as a warning, not a failure) means a core RoPA field moved and a signed activity needs re-signing. Confirm the exit code is wired as a warning, not a hard fail, so a real change never blocks a merge.

- name: Re-scan and summarise what changed
  env:
    DATABASE_URL: ${{ secrets.DATABASE_URL }}   # the env var(s) your regixo.yml names
  run: |
    set +e
    npx regixo watch --ci >> "$GITHUB_STEP_SUMMARY"
    code=$?
    set -e
    if [ "$code" -eq 3 ]; then
      echo "::warning::Core RoPA fields changed — review and re-sign if the record is sealed."
    elif [ "$code" -ne 0 ]; then
      exit "$code"
    fi

The re-sign side of a scheduled change is walked in Keep it current.

Step 3 · Feed the hosted record

Once a compliance lead has claimed a record on the portal, a paired regixo watch keeps it fed. Pairing is one thing: the engineer sets REGIXO_SYNC_TOKEN (the ingest-only token an admin minted, handed over the safe way — see Roles & governance, Step 5) in the machine's environment. The portal address defaults to app.regixo.com, so on the Regixo cloud the token alone is the whole pairing; point it elsewhere with REGIXO_PORTAL_URL. With the token set, the same scheduled run pushes the refreshed, metadata-only draft to the portal:

$ export REGIXO_SYNC_TOKEN='rgx_sync_…'
$ regixo watch --ci

The push goes to POST /api/v1/sync authenticated by the token. It carries metadata only, and the token can only ingest — never unlock, sign or export. The record's “what changed” feed updates so the compliance team sees the estate moved without anyone re-forwarding a draft.

That is the whole of step 3: one env var, and the scheduled run you already have does the rest. Step 4 is confirming it worked.

Step 4 · Prove the pipeline is really wired

The goal: evidence — not assumption — that the sources resolve and the portal pairing is live, before you trust tonight's scheduled run. regixo doctor checks the setup end to end and names the fix for anything wrong.

$ regixo doctor

✓ node: Node 24.4.0
✓ config: ./regixo.yml parsed, 4 source(s) · DORA scope ON
✓ source:app-db: connection from DATABASE_URL resolved · connects ✓
✗ source:stripe: the connection variable STRIPE_URL isn't set yet — there's nothing to read
    fix: Set it to your real connection string, then re-run:  export STRIPE_URL='<PASTE-YOUR-TOKEN-HERE>'
✗ source:snowflake-dwh: the connection variable SNOWFLAKE_URL isn't set yet — there's nothing to read
    fix: Set it to your real connection string, then re-run:  export SNOWFLAKE_URL='<PASTE-YOUR-TOKEN-HERE>'
✓ map: catalog present at ./index.db

regixo doctor: 2 issue(s) — see fixes above.

Once REGIXO_SYNC_TOKEN is set and the portal is reachable, doctor adds a portal-pairing check — ✓ portal-pairing: machine token accepted at https://app.regixo.com — pushes will update the claim. It authenticates the token itself, so a revoked or wrong-record token fails here rather than on tonight's scheduled push. That line, plus a fresh “last updated” time on the claim page after the next scheduled watch, is your proof the pairing works and the record is being fed.

Which paired state am I in — the walk

A machine is in exactly one of three states; the difference is only which env vars are set. doctor reports it, and the walk tells you what to do:

Branch · multiple repos, environments & networks

Real estates aren't one flat database. Three patterns:

• Multi-repo / multi-service — give each repo its own committed regixo.yml scoped to the sources that team owns. Each produces its own map; you decide whether to run them as separate records or merge the maps.
• Prod vs staging — keep them as distinct sources (distinct ids and connectionRefs). Scanning staging is a safe way to preview a schema change before it reaches production and trips a re-sign.
• Inside-network map-merge — when a database can't be reached from where you'd normally run, run regixo start on a machine inside that network and merge the maps. It's the same “bring Regixo inside” route the coverage meter points to in Architect your catalog.

Branch · honest limits: multi-entity is not built yet