The scm reef
Every command that lets Nereus reach a source host as an application, never as a person
O reef scm
Todos os comandos que deixam o Nereus alcançar um host de código como uma aplicação, nunca como uma pessoa
The source of truth for the commands of the scm reef (#927, ADR 0024). The Connection is built (#1281, the Connection names an organisation reached through a Mandate), its output the one make scene-github prints against a fake GitHub API; the Mirror is built (#1255, the forgejo Nereid runs Forgejo in the cluster and mirrors a GitHub repository), its output the one make scene-forgejo prints against a fake Git host in the cluster. The group is scm.getnereus.dev/v1alpha1.
Who the platform is towards GitHub is not here: the GitHub App is a Mandate of the authentication reef, and a short-lived token is that reef's Token (ADR 0006, its deck).
A fonte da verdade dos comandos do reef scm (#927, ADR 0024). A Connection está construída (#1281, a Connection nomeia uma organização alcançada por um Mandate), a sua saída a que o make scene-github imprime contra uma API do GitHub falsa; o Mirror está construído (#1255, o Nereid forgejo roda o Forgejo no cluster e espelha um repositório do GitHub), a sua saída a que o make scene-forgejo imprime contra um host Git falso no cluster. O grupo é scm.getnereus.dev/v1alpha1.
Quem a plataforma é perante o GitHub não está aqui: o GitHub App é um Mandate do reef authentication, e um token de vida curta é o Token desse reef (ADR 0006, o seu deck).
A Connection names an organisation, a Mandate reaches it
Connection, the default kind:spechasorg,mandateanddefault;statushasinstallationId,repositorySelectionandpermissions- No vendor, no key, no token: the App is an authentication Mandate, the token its
Token - One webhook per App: the scm reef receives it and checks its signature
Uma Connection nomeia uma organização, um Mandate a alcança
Connection, o kind padrão: ospectemorg,mandateedefault; ostatusteminstallationId,repositorySelectionepermissions- Sem vendor, sem chave, sem token: o App é um Mandate do authentication, o token o seu
Token - Um webhook por App: o reef scm o recebe e confere a sua assinatura
One writer per field (ADR 0005): the person, or a Nereid as a client, writes spec; the Nereid of the Mandate writes status. --mandate names an scm Mandate (ADR 0011), with none the reef's default; its param identity names the authentication Mandate, the App. The webhook's secret is a param of the App's Mandate; the push of #914 builds on the receiver. Mirror (a repository copied into the cluster, #1255) needs no Connection: a public source needs no App; the forgejo Nereid keeps it.
Um escritor por campo (ADR 0005): a pessoa, ou um Nereid como cliente, escreve o spec; o Nereid do Mandate escreve o status. --mandate nomeia um Mandate do scm (ADR 0011), sem ele o padrão do reef; o seu param identity nomeia o Mandate do authentication, o App. O secret do webhook é um param do Mandate do App; o push da #914 se apoia no receptor. Mirror (um repositório copiado para o cluster, #1255) não precisa de Connection: uma fonte pública não precisa de App; o Nereid forgejo o mantém.
What comes before the first connection?
O que vem antes da primeira conexão?
One github Nereid serves both reefs, opt-in
Um Nereid github serve os dois reefs, opcional
# Apply the github Nereid to both reefs$ nereus nereid apply github \ --reef authentication \ --reef scm✓ core/nereids/github created, Ready, pinned to sha256:1e74cbc6a968: see 'nereus authentication --help' namespaces/nereus-system-github applied (the github Nereid's Role there, where vault default delivers the App keys) Next steps: nereus mandate create github --reef authentication --nereid github --param appId=<id> --param privateKey=<secret> --param allow=<namespace>:<repository>:<permission>=<level> --default nereus mandate create github-scm --reef scm --nereid github --param identity=github --default # Bind the scm reef to it, through the App github$ nereus mandate create github-scm \ --reef scm \ --nereid github \ --param identity=github \ --default✓ core/mandates/github-scm created (reef: scm, nereid: github, default) clusterrole/controller-github configured (nereid github writes the status of mandate github-scm) Next steps: nereus mandate list
The internal-developer-platform profile does not install it (owner, 2026-11-09): it needs a GitHub App the person owns. The App itself is the authentication Mandate github (#1273), created first; this scm Mandate says which Nereid serves Connections and, with identity, which App they use (owner, 2026-11-09). Mandate names are global, so it takes its own name, by the convention <nereid>-<reef>.
O profile internal-developer-platform não o instala (dono, 2026-11-09): ele precisa de um GitHub App que a pessoa possui. O App em si é o Mandate github do authentication (#1273), criado antes; este Mandate do scm diz qual Nereid serve as Connections e, com identity, qual App elas usam (dono, 2026-11-09). Os nomes de Mandate são globais, então ele tem nome próprio, pela convenção <nereid>-<reef>.
Which organisation, through which App?
Qual organização, por qual App?
A Connection names an organisation, and nothing secret
Uma Connection nomeia uma organização, e nada secreto
# The organisation, through the reef's default Mandate$ nereus scm connection create example \ --org example✓ scm/connections/example created (mandate github-scm) Next steps: nereus scm connection get example # A second default is refused: one in the reef$ nereus scm connection create other \ --org example-other \ --default✗ scm/connections/example is the reef's default already: one in the reef. Nothing was changed.
--mandate names an scm Mandate, as on every object (ADR 0011); with none, the reef's default. That Mandate's param identity names the App that reaches the organisation; a second App is a second scm Mandate (nereus mandate create github-scm-labs --reef scm --nereid github --param identity=other-app). --default makes the Connection the reef's default, one in the reef. No --vendor, no App id, no key: those are the Mandate's (ADR 0006).
--mandate nomeia um Mandate do scm, como em todo objeto (ADR 0011); sem ele, o padrão do reef. O param identity desse Mandate nomeia o App que alcança a organização; um segundo App é um segundo Mandate do scm (nereus mandate create github-scm-labs --reef scm --nereid github --param identity=other-app). --default torna a Connection a padrão do reef, uma no reef. Sem --vendor, sem id de App, sem chave: isso é do Mandate (ADR 0006).
list says what each App reaches, and what is missing
O list diz o que cada App alcança e o que falta
# Every Connection, with its status$ nereus scm connection listCONNECTION ORG MANDATE STATUS DEFAULTexample example github-scm Ready yeslabs example-labs github-scm NotInstalled nometa example-meta github-scm MissingPermissions nosome example-some github-scm NotAllRepositories no # One of them, with what to do$ nereus scm connection get metaName: metaOrg: example-metaMandate: github-scmNereid: githubDefault: noStatus: MissingPermissionsInstallation: 3Repositories: allPermissions: metadata=readMessage: the App of mandate github lacks contents=read on example-meta: grant them in the App's settings, then accept them on the installation
The statuses, in order: NotInstalled, NotAllRepositories (installed on a selection), MissingPermissions (less than metadata and contents read, the least #904 needs), Ready. There is no verify: the status says it. A feature that needs more permissions widens them in its own issue.
Os status, em ordem: NotInstalled, NotAllRepositories (instalado numa seleção), MissingPermissions (menos que leitura de metadata e contents, o mínimo de que a #904 precisa), Ready. Não há verify: o status o diz. Uma feature que precisa de mais permissões as amplia na sua própria issue.
delete removes the Connection, never the App
O delete remove a Connection, nunca o App
# Remove the Connection$ nereus scm connection delete labs✓ scm/connections/labs deleted Next steps: nereus scm connection list
The App stays on GitHub, and its Mandate in the authentication reef, until the person deletes them.
O App continua no GitHub, e o seu Mandate no reef authentication, até a pessoa apagá-los.
Can the source live in the cluster?
O código pode morar no cluster?
The forgejo Nereid runs Forgejo in the cluster, in the profile
O Nereid forgejo roda o Forgejo no cluster, no profile
# Apply the forgejo Nereid to the scm reef; it needs the release and secrets reefs$ nereus nereid apply forgejo \ --reef scm✓ core/nereids/forgejo created, Ready: see 'nereus scm --help' core/mandates/forgejo created (reef: scm, nereid: forgejo) Next steps: nereus scm mirror create <name> --from https://github.com/<owner>/<repository>
The profile internal-developer-platform installs it (#1327), and its Mandate forgejo is the scm reef's default there; on another profile, this command does (#1255). It makes its Mandate forgejo, then asks the release reef for Forgejo's upstream Helm chart (SQLite on a volume, no Ingress) and makes Forgejo's admin, sealed into the vault default as the secret forgejo-admin. Forgejo copies from github.com only; the setting MIRROR_ALLOWED_DOMAINS adds a host, as the scene adds its fake. Plain http:// needs --allow-http and the setting MIRROR_ALLOW_HTTP=true, which only the scene sets.
O profile internal-developer-platform o instala (#1327), e o seu Mandate forgejo é o padrão do reef scm ali; em outro profile, este comando o instala (#1255). Ele cria o seu Mandate forgejo, depois pede ao reef release o Helm chart oficial do Forgejo (SQLite num volume, sem Ingress) e cria o admin do Forgejo, selado no vault default como o secret forgejo-admin. O Forgejo copia só de github.com; a setting MIRROR_ALLOWED_DOMAINS acrescenta um host, como a cena acrescenta o seu falso. http:// simples precisa de --allow-http e da setting MIRROR_ALLOW_HTTP=true, que só a cena usa.
A Mirror copies a repository into the cluster
Um Mirror copia um repositório para o cluster
# Copy a public repository, pulled every 10 minutes$ nereus scm mirror create nereus \ --from https://github.com/getnereus/nereus \ --interval 10m✓ scm/mirrors/nereus created (mandate forgejo) Next steps: nereus scm mirror get nereus
No Connection, no App: a public source needs neither. The Mirror goes through --mandate, else the reef's default Mandate, and the CLI refuses one whose Nereid does not list mirrors in its status.kinds: the default may be the github Nereid's, which checks Connections only. The copy lands at <owner>/<repository> on Forgejo, private; two Mirrors of one place, the oldest keeps it and the other is Taken.
Sem Connection, sem App: uma fonte pública não precisa de nenhum. O Mirror passa pelo --mandate, senão pelo Mandate padrão do reef, e o CLI recusa um cujo Nereid não lista mirrors no seu status.kinds: o padrão pode ser o do Nereid github, que só confere Connections. A cópia fica em <owner>/<repository> no Forgejo, privada; dois Mirrors do mesmo lugar, o mais antigo o mantém e o outro fica Taken.
list shows the commit each copy holds
O list mostra o commit que cada cópia tem
# Every Mirror, the commit it holds and its status$ nereus scm mirror listMIRROR FROM MANDATE LAST SYNC COMMIT STATUSnereus https://github.com/getnereus/nereus forgejo 2026-11-10T12:00:00Z 68d7a0d Readyoutside https://example.com/example/outside forgejo - - SourceUnreachable # One of them, and where the cluster clones it from$ nereus scm mirror get nereusName: nereusFrom: https://github.com/getnereus/nereusInterval: 10mMandate: forgejoNereid: forgejoStatus: ReadyRepository: getnereus/nereusClone: http://forgejo-http.nereus-system-forgejo.svc:3000/getnereus/nereus.gitBranch: mainCommit: 68d7a0d6f1c2b3a4d5e6f708192a3b4c5d6e7f80Last sync: 2026-11-10T12:00:00ZMessage: getnereus/nereus holds 68d7a0d6f1c2 of main, pulled every 10m.
The statuses: Syncing until the first pull, Ready with the commit, SourceUnreachable when Forgejo refuses the source (a host it may not copy from, a repository that is not there), Taken, NoMandate, WaitingForForgejo. The clone address answers inside the cluster only. delete removes the copy too, never the source.
Os status: Syncing até o primeiro pull, Ready com o commit, SourceUnreachable quando o Forgejo recusa a fonte (um host de onde não pode copiar, um repositório que não existe), Taken, NoMandate, WaitingForForgejo. O endereço de clone só responde dentro do cluster. O delete remove a cópia também, nunca a fonte.
Where the ideas came from
- GitHub, installation access tokens: an installation and its repository selection
- GitHub, validating webhook deliveries: the signature the receiver checks
De onde vieram as ideias
- GitHub, tokens de instalação: uma instalação e a sua seleção de repositórios
- GitHub, validando entregas de webhook: a assinatura que o receptor confere
The full credits are in the ADR of this reef.
Os créditos completos estão no ADR deste reef.