114 lines
4.5 KiB
Markdown
114 lines
4.5 KiB
Markdown
# Registry Onboarding
|
|
|
|
Multi-repo onboarding uses an operator-owned manifest to register ecosystem
|
|
repositories with a running Railiance Fabric registry and to push graph and
|
|
library inventory when the local checkout has the required inputs.
|
|
|
|
Repo-local declarations remain useful self-description evidence. They should
|
|
not be treated as the default authority for external fabric membership,
|
|
ownership, tenant boundaries, or cross-boundary utility relations. Those belong
|
|
to the accountability-root discovery model described in
|
|
`docs/FabricDiscoveryAndUpdate.md`.
|
|
|
|
## Run The Railiance Manifest
|
|
|
|
Start the registry:
|
|
|
|
```bash
|
|
railiance-fabric-registry --db .railiance-fabric/registry.sqlite3 --port 8765
|
|
```
|
|
|
|
Sync the known local Railiance ecosystem repos:
|
|
|
|
```bash
|
|
railiance-fabric registry sync-manifest registry/railiance-repos.yaml
|
|
```
|
|
|
|
Sync every active State Hub repo that is available on this local host:
|
|
|
|
```bash
|
|
railiance-fabric registry sync-manifest registry/local-repos.yaml
|
|
```
|
|
|
|
Use `--json` for automation and `--strict` when unavailable repos or invalid
|
|
inputs should fail the command.
|
|
|
|
## Manifest Shape
|
|
|
|
```yaml
|
|
apiVersion: railiance.fabric/v1alpha1
|
|
kind: RegistryOnboardingManifest
|
|
registry_url: http://127.0.0.1:8765
|
|
repositories:
|
|
- slug: railiance-fabric
|
|
name: railiance-fabric
|
|
path: ..
|
|
default_branch: main
|
|
state_hub_repo_id: 2c0de614-e468-4eb6-8157-470649ac8c05
|
|
repo_family: ownership
|
|
declaration_paths:
|
|
- ..
|
|
sbom: bom.json
|
|
```
|
|
|
|
`path` is the local checkout used for git metadata, default graph discovery,
|
|
and repo-family relation projection when the registry later needs to reopen
|
|
repo-local `rail`, `rapp`, or `reef` files.
|
|
`declaration_paths` is optional; when omitted, the repo path is scanned for a
|
|
`fabric/` directory. Relative paths are resolved from the manifest file.
|
|
|
|
`state_hub_repo_id` is optional. Include it when known so registry consumers can
|
|
link back to State Hub repo views, but do not block onboarding when a repo is
|
|
registered in Fabric before that ID is wired in here.
|
|
|
|
The following repo-family metadata fields are also optional:
|
|
|
|
- `repo_family`: `ownership`, `rail`, `rapp`, or `reef`
|
|
- `ownership_repo`: canonical owning `railiance-*` repo when the registered repo
|
|
is not itself an ownership repo
|
|
- `primary_rail`: default rail for a reef or package when one is explicitly
|
|
declared
|
|
- `supported_rails`: array of supported rail ids for `rapp-*` repos
|
|
- `substrate_kind`: grouped substrate category such as `server`,
|
|
`server-group`, `workstation-group`, or `cluster`
|
|
|
|
`sbom` or `sboms` may point to CycloneDX JSON/YAML files. When present, the
|
|
command ingests them as queryable library inventory after repository
|
|
registration.
|
|
|
|
## Onboarding Behavior
|
|
|
|
Each repository entry is registered first. If the checkout is unavailable or has
|
|
no Fabric declarations yet, the command leaves the repo registered and reports a
|
|
warning. This lets the registry represent known repos before every repo has
|
|
published local evidence.
|
|
|
|
For `rail-*`, `rapp-*`, and `reef-*` repos, registration-only entries still
|
|
matter: the registry stores the checkout path and repo-family metadata, and the
|
|
graph export can use the conventional repo-local declaration files to project
|
|
first-wave `governed_by`, `supports_rail`, `hosts_rail`, and `binds_rapp`
|
|
edges even when the repo does not yet publish native Fabric declarations.
|
|
|
|
When declarations exist, the command validates them, builds a graph snapshot,
|
|
and posts it to:
|
|
|
|
```text
|
|
POST /repositories/{repo_slug}/snapshots
|
|
```
|
|
|
|
The first Railiance manifest keeps the seed ecosystem graph in
|
|
`railiance-fabric` and registers adjacent repos as known sources. As discovery
|
|
roots mature, adjacent repos can contribute local evidence without making each
|
|
repo responsible for the whole external fabric relation model.
|
|
|
|
`registry/local-repos.yaml` is a broader local-host manifest. It is generated
|
|
from active State Hub repo records whose local path exists on the current WSL
|
|
host. It registers cross-domain local repos into the Fabric registry while only
|
|
syncing graph snapshots for repos that already have Fabric declarations.
|
|
|
|
When two active repo records point at the same checkout path, accountability
|
|
root discovery treats them as aliases of one repository identity. The canonical
|
|
identity can be declared with `canonical_slug`; otherwise discovery prefers the
|
|
slug matching the checkout directory name and then the entry with a remote URL.
|
|
Use `split_identity: true` only when shared paths are intentional and should
|
|
remain separate review candidates.
|