Skip to content

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 .pem file). With no App yet, nereus authentication app-register creates 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
output
✓ 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
output
✓ 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
output
✓ 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
output
✓ 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
output
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
output
✓ authentication/tokens/catalog deleted

Next steps:

  nereus authentication token list

Next

Learn more