#How to register a repo

There are two registries and they do different jobs. The catalog lists every engineering repo and links out to GitLab. The aggregation manifest copies the docs/ of a few repos into the portal.

Every repo goes in the catalog. Aggregation is opt-in and deliberate: it is reserved for Tier-1 services, where the stability risk lives. An aggregated repo also appears in the catalog, with an extra link to its docs.

#Add a repo to the catalog

1. Open repos-inventory.json and add an entry to its discipline group. The groups are frontend, backend, qa, infra and platform.

   {
     "url": "https://gitlab.com/crehana-team/platform/platform-radar",
     "name": "platform-radar",
     "product": "Engineering Platform",
     "module": "initiative-hub",
     "owner": "platform"
   }

2. Fill in the fields. All are required except module.

   Field	What it is
   url	The project URL in GitLab, with https://
   name	The name shown in the table
   product	The product the repo serves
   module	Optional. The module inside the product
   owner	The owning squad or team

3. Regenerate the catalog and validate:

   pnpm run build

   You should see the updated count:

   ✓ catalog: 3 repos, 0 registered for aggregation

The /repos/ page is generated from this file on every build. Never edit it by hand. Malformed JSON or an entry missing a required field breaks the build, naming the offending entry.

#Add a repo's docs to the portal

Before registering a repo in the manifest, that repo needs:

• A docs/ directory with at least one .md or .mdx page
• A CODEOWNERS covering that directory, so its docs go through review

Then:

1. Add an entry to docs-manifest.yaml:

   repos:
     - slug: checkout-service
       name: checkout-service
       gitlab_path: crehana-team/backend/checkout-service
       docs_path: docs
       owner: squad-payments

2. Choose the slug carefully. It defines the URL at /repos/<slug>/ and never changes, not even when the repo moves inside GitLab. If the repo moves, update gitlab_path and keep the slug: the portal URLs keep working.

3. If the repo is private, export a read token before aggregating:

   export AGGREGATION_TOKEN=<GitLab read token>

4. Pull the docs and build:

   pnpm run aggregate
   pnpm run build

#Verification

pnpm run aggregate rebuilds all of docs/<locale>/repos/<slug>/ from scratch, so the portal is always reproducible from the manifest and the source repos. You should see:

  checkout-service: 3 page(s) from crehana-team/backend/checkout-service@main (a1b2c3d)
✓ aggregate: 1 repo(s) pulled into es + en

Open /repos/checkout-service/ and confirm every page shows its provenance header with the repo, the commit, the date and the owner. An aggregated page without provenance breaks the build.

#What happens with the language

Aggregated pages are copied as written in the source repo, into both language trees. They are not translated: whoever wrote them owns their content, and the portal only publishes them with their provenance.

#Related

• How to contribute to the portal — the flow for a hand-written page