Operations

GitHub integration

Each integration has as GitHub application created in the lsst-sqre org for every environment in which it is enabled.

All of the applications:

GitHub application configuration

To enable the GitHub integrations for another mobu env, you have to create a new GitHub application and sync Phalanx secrets.

Refresh app

Create a new GitHub app

  1. Click the New GitHub App button in the lsst-sqre org Developer Settings apps page.

  2. Name it mobu refresh (<env URL or id if the URL is too long>).

  3. Make sure the Active checkbox is checked in the Webhook section.

  4. Enter https://<env URL>/mobu/github/refresh/webhook in the Webhook URL input.

  5. Generate a strong password to use as the webhook secret.

  6. Store this in the SQuaRE vault in the LSST IT 1Password account in an item named mobu GitHub refresh app webhook secret (<env URL>).

  7. Get this into the Phalanx secret store for that env under the key: github-refresh-app-webhook-secret (this process is different for different envs).

  8. Enter this secret in the Webhook secret (optional) box in the GitHub App config.

  9. Select Read-only in the dropdown of the Contents access category in the Repository Permissions section.

  10. Check the Push checkbox in the Subscribe to events section.

  11. Select the Any account radio button in the Where can this GitHub App be installed? section.

  12. Click the Create GitHub App button.

  13. Do the Phalanx configuration.

Install the app for a repo

  1. Go to new app’s homepage (something like apps/mobu-refresh-usdfdev).

  2. Click the Install button.

  3. Select the Only select repositories radio button.

  4. Select the repo in the dropdown.

  5. Click Install.

CI app

Create a new GitHub app

  1. Click the New GitHub App button in the lsst-sqre org Developer Settings apps page.

  2. Name it mobu CI (<env URL or id if the URL is too long>).

  3. Make sure the Active checkbox is checked in the Webhook section.

  4. Enter https://<env URL>/mobu/github/ci/webhook in the Webhook URL input.

  5. Generate a strong password to use as the webhook secret.

  6. Store this in the SQuaRE vault in the LSST IT 1Password account in an item named mobu GitHub CI app webhook secret (<env URL>).

  7. Get this into the Phalanx secret store for that env under the key: github-ci-app-webhook-secret (this process is different for different envs).

  8. Enter this secret in the Webhook secret (optional) box in the GitHub App config.

  9. Select Read and Write in the dropdown of the Checks access category in the Repository Permissions section.

  10. Select Read-only in the dropdown of the Contents access category in the Repository Permissions section.

  11. Check the Check suite and Check run checkboxes in the Subscribe to events section.

  12. Select the Any account radio button in the Where can this GitHub App be installed? section.

  13. Click the Create GitHub App button.

  14. Find the App ID (an integer) in the About section. Get this into the Phalanx secret store for that env under the key: github-ci-app-id (this process is different for different envs).

  15. Click the Generate a private key button in the Private keys section.

  16. Store this private key in the SQuaRE vault in the LSST IT 1Password account in an item named mobu GitHub CI app private key (<env URL>).

  17. Get this into the Phalanx secret store for that env under the key: github-ci-app-private-key (this process is different for different envs).

  18. Do the Phalanx configuration.

Install the app for a repo

  1. Go to new app’s homepage (something like apps/mobu-refresh-usdfdev).

  2. Click the Install button.

  3. Select the Only select repositories radio button.

  4. Select the repo in the dropdown.

  5. Click Install.

Phalanx configuration

The GitHub integrations each need to be explicitly enabled in Phalanx for a given environment. If an integration is not enabled, then the webhook route for that integration will not be mounted, GitHub webhook requests will get 404 responses. To enable these integrations for an environment, set these values to true:

  • config.githubRefreshAppEnabled

  • config.githubCiAppEnabled

If you want to enable either GitHub integration in a given environment, you also need to add a config.github section to that env’s values in Mobu. That needs to be a dict with at users and accepted_github_orgs entries. It should look something like this:

config:
  github:
    accepted_github_orgs:
      - lsst-sqre
    users:
      - username: "bot-mobu-ci-user-1"
        uidnumber: 123
        gidnumber: 456
      - username: "bot-mobu-ci-user-2"
        uidnumber: 789
        gidnumber: 876

The organization of any repo that uses any of the GitHub integrations in an env must be added to the accepted_github_orgs list, otherwise Github webhook requests will get 403 responses.

The users list follows the same rules as the users list in a flock autostart config. The usernames must all start with bot-mobu. In envs with Firestore integration, you only need to specify username. In envs without it, you need to ensure that users are manually provisioned, and then you need all three of username, uidnumber, and gidnumber.