Connect a GitHub App¶
Connect a GitHub App as a Mandate of the authentication reef's Nereid github: its status proves where the App is installed and what it may do, and consumers ask it for one-hour tokens, never for its key.
Before you start¶
- A cluster with the secrets reef and its vault
default, from Keep a secret. - An App you already have: its id, and its private key (a
.pemfile). With no App yet,nereus authentication app-registercreates one in the browser, and only the Nereid ever holds its key; skip to step 4. - Reef, Nereid and Mandate: the App is a Mandate, its id and key its params.
Steps¶
1. Keep the App's private key as a secret¶
nereus secrets create encrypts it on your machine before it leaves it.
GITHUB_APP_KEY="$(cat app.pem)" nereus secrets create github-app-key --from-env GITHUB_APP_KEY
✓ secrets/vaults/default/secrets/github-app-key created (key SHA256:l0jt+UOKUmA72jydN0DSpTzFJIdO6wP/xUvdAKryBe4)
Stored encrypted; a Kubernetes Secret is made only when a binding asks for it (#532).
2. Apply the Nereid¶
The Nereid is opt-in, outside every profile. nereus nereid apply gives it one namespace, nereus-system-github, the only one where it reads Secrets.
nereus nereid apply github --reef authentication
✓ core/nereids/github created, Ready, pinned to sha256:021dd70640d0: 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
3. Create the App's Mandate¶
nereus mandate create names the App, its key's secret and who may ask a token. Each allow is <namespace>:<repository or *>:<permission>=<level>; with none, no token is ever made.
nereus mandate create github \
--reef authentication \
--nereid github \
--param appId=123456 \
--param privateKey=github-app-key \
--param allow=nereus-system:*:contents=read \
--param allow=example:example/app:metadata=read \
--default
✓ core/mandates/github created (reef: authentication, nereid: github, default)
clusterrole/controller-github configured (nereid github writes the status of mandate github)
4. Lend a repository for an hour¶
nereus authentication token create asks the Mandate for a token of one repository. The Nereid writes it to the Secret token-<name> of the Token's namespace; no command prints it.
nereus authentication token create catalog \
--repository example/app \
--permission contents=read
✓ authentication/tokens/catalog created (expires in 1h, mandate github)
Next steps:
nereus authentication token get catalog
A namespace the Mandate does not allow gets no token, and the line names the allow to add.
Check it worked¶
nereus mandate get shows the App as GitHub answered, and the allowlist as the Nereid read it.
nereus mandate get github
Name: github
Reef: authentication
Nereid: github
Default: true
Params: allow=nereus-system:*:contents=read;example:example/app:metadata=read, appId=123456, privateKey=github-app-key
Status: Ready
App: example-nereus
Installations: example (all repositories)
Permissions: contents=read, metadata=read
Age: 10s
Allowed:
NAMESPACE REPOSITORY PERMISSIONS
nereus-system * contents=read
example example/app metadata=read
Another status names what is wrong: NotInstalled with the URL to install the App, InvalidCredentials for a key of no App, MissingParam for a secret that does not exist.
Clean up¶
nereus authentication token delete catalog
✓ authentication/tokens/catalog deleted
Next steps:
nereus authentication token list
Next¶
- Connect a repository host that builds and mirrors through the App.
Learn more¶
- The authentication reef:
app-register, tokens and every command. - ADR 0006: the platform's identity towards an outside system is a Mandate.