blackroad-operating-system/docs/os/monorepo-sync.md

BlackRoad OS Monorepo Sync

BlackRoad-Operating-System is the single source of truth for every service, app, and docs site under the BlackRoad OS umbrella. All satellite repositories are read-only mirrors. If it cannot be automated from this monorepo, it does not exist.

Philosophy

• Edit code only in this repository.
• Each satellite repository maps to exactly one directory in the monorepo (see the mapping table below).
• GitHub Actions sync the relevant directory to its target repository after every change—no manual merges.

Layout and Ownership

• services/core-api → BlackRoad-OS/blackroad-os-core
• services/public-api → BlackRoad-OS/blackroad-os-api
• services/operator → BlackRoad-OS/blackroad-os-operator
• apps/prism-console → BlackRoad-OS/blackroad-os-prism-console
• apps/web → BlackRoad-OS/blackroad-os-web
• docs/site → BlackRoad-OS/blackroad-os-docs

The authoritative mapping is codified in infra/github/sync-config.yml.

How Sync Works

1. A push to main that touches a mapped path triggers its sync workflow.
2. The workflow checks out the monorepo, exports only the mapped directory, and clones the target repository using ${{ secrets.BR_OS_SYNC_TOKEN }}.
3. The target repository is wiped (except .git), refreshed with the exported files, committed with the source SHA, and pushed (default is a force-push because the satellite is a mirror).
4. A sync-status.md file in the satellite captures the source SHA and workflow URL for traceability.
5. If there are no changes, the workflow exits cleanly.

Onboarding a New Service

1. Add an entry to infra/github/sync-config.yml with monorepo_path, target_repo, target_branch, and optionally force_push.
2. Create the corresponding directory (for example services/new-service/) and populate it with code.
3. Add a new workflow in .github/workflows/ (copy an existing sync workflow) that sets SERVICE_KEY to the new entry and sets the path filter to the new directory.
4. (Optional) Add a deploy workflow for the service that builds, tests, and deploys to Railway. Reference infra/railway/ENVIRONMENT_GUIDE.md for required env vars.

Troubleshooting

• Non-fast-forward errors: set force_push: true for the service (default) or configure branch protection to allow the automation user to force-push.
• Missing secrets: ensure ${{ secrets.BR_OS_SYNC_TOKEN }} is available to sync workflows and ${{ secrets.RAILWAY_TOKEN }} to deploy workflows.
• Path not syncing: confirm the workflow on.push.paths matches the directory and that the monorepo_path in sync-config.yml is correct.

Repository Guards for Mirrors

• Each mirror README should include a “Managed by Monorepo” banner (see docs/os/satellite-readmes/README.blackroad-os-core.md).
• Recommended branch protection on mirrors:
  • Require the automation user to be the only actor allowed to force-push to main.
  • Optionally block direct pushes and auto-close PRs with a comment pointing contributors to the monorepo path that owns the code.

See Also

• infra/github/sync-config.yml for the canonical mapping.
• docs/os/satellite-readmes/README.blackroad-os-core.md for the managed-by-monorepo banner template.
• infra/railway/ENVIRONMENT_GUIDE.md for deployment expectations.