Skip to content

Connect an organisation

Connect an organisation of a source host to Nereus through the GitHub App an scm Mandate names: you write the organisation, and the github Nereid writes whether the App reaches it. A Connection holds no key and no token.

Before you start

  • The App's Mandate github, Ready, from Prove a GitHub App installed. For GitHub to deliver events, give that Mandate the App's webhook secret in --param webhookSecret=<secret>.

Steps

1. Apply the scm reef and the github Nereid

The scm reef is opt-in, outside the internal-developer-platform profile. One github Nereid serves both the authentication and the scm reef.

nereus reef apply scm
output
✓ core/reefs/scm created (scm.getnereus.dev/v1alpha1: connections)

nereus nereid apply names both reefs.

nereus nereid apply github \
  --reef authentication \
  --reef scm
output
✓ 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

2. Bind the scm reef to the App

nereus mandate create binds the scm reef to the Nereid. Its name follows <nereid>-<reef>, and its param identity names the App's Mandate; a second App is a second scm Mandate.

nereus mandate create github-scm \
  --reef scm \
  --nereid github \
  --param identity=github \
  --default
output
✓ 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

3. Connect the organisations

nereus scm connection create names one organisation. The first Connection is the reef's default; --mandate picks another scm Mandate.

nereus scm connection create example \
  --org example
output
✓ scm/connections/example created (mandate github-scm)

Next steps:

  nereus scm connection get example

Connect labs, meta and some the same way, with --org example-labs, example-meta and example-some. A second --default is refused: one in the reef.

nereus scm connection create other \
  --org example-other \
  --default
output
✗ scm/connections/example is the reef's default already: one in the reef. Nothing was changed.

Check it worked

nereus scm connection list shows what the App reaches on each organisation. There is no verify: the status is the check, from the first that fails: NotInstalled, NotAllRepositories, MissingPermissions (less than metadata and contents read), else Ready.

nereus scm connection list
output
CONNECTION  ORG           MANDATE     STATUS              DEFAULT
example     example       github-scm  Ready               yes
labs        example-labs  github-scm  NotInstalled        no
meta        example-meta  github-scm  MissingPermissions  no
some        example-some  github-scm  NotAllRepositories  no

nereus scm connection get says what to do about a status.

nereus scm connection get labs
output
Name:          labs
Org:           example-labs
Mandate:       github-scm
Nereid:        github
Default:       no
Status:        NotInstalled
Installation:  -
Repositories:  -
Permissions:   -
Message:       the App of mandate github is not installed on the organisation example-labs: install it at https://github.com/apps/example-nereus/installations/new

The App's webhook points at POST /scm/webhook on the github Nereid's Service, reached only inside the cluster for now: a delivery is accepted only when X-Hub-Signature-256 checks with the App's webhookSecret.

Clean up

nereus scm connection delete removes the Connection; the App stays installed on the organisation, and its Mandate in the authentication reef.

nereus scm connection delete labs
output
✓ scm/connections/labs deleted

Next steps:

  nereus scm connection list

Next

Learn more