Configuring the GitHub App#

Semaphore uses GitHub to source certain content, such as broadcasts. To authenticate with GitHub, Semaphore uses a GitHub App. Each installation of Semaphore has its own GitHub App in order to receive webhook events. Semaphore installations in different RSP/Phalanx environments can share the same source repository, however.

To learn more about installing GitHub Apps in general, see the GitHub Apps documentation.

Important

The GitHub App must be created in the GitHub organization or user that owns the source repository. For example, if the source repository is lsst-sqre/rsp_broadcast, the GitHub App must be created in the lsst-sqre organization.

Do not create a public GitHub App. If the GitHub App is public, it can be installed in any GitHub organization or user account. Semaphore does not yet support an “accept” list to ensure that only authorized organizations or users can install a public GitHub App.

Create an app with a template URL#

You can create the GitHub App by customizing and visiting the following URL (replace lsst-sqre with the GitHub organization or user that owns the source repository):

https://github.com/organizations/lsst-sqre/settings/apps/new?name=Semaphore%20%28data-dev.lsst.cloud%29&description=Semaphore%20is%20the%20user%20notification%20service%20for%20the%20Rubin%20Science%20Platform%20%28data-dev.lsst.cloud%29.%20An%20instance%20of%20the%20Semaphore%20app%20is%20associated%20with%20each%20%5BRSP%20environment%5D%28https%3A%2F%2Fphalanx.lsst.io%2Fenvironments%2Findex.html%29.&url=https%3A%2F%2Fsemaphore.lsst.io&public=false&webhook_active=true&webhook_url=https%3A%2F%2Fdata-dev.lsst.cloud%2Fsemaphore%2Fgithub%2Fwebhook&events%5B%5D=push&events%5B%5D=check_run&contents=read&checks=write

Alternatively, the app can be installed in a personal account (not recommended for production use):

https://github.com/settings/apps/new?name=Semaphore%20%28data-dev.lsst.cloud%29&description=Semaphore%20is%20the%20user%20notification%20service%20for%20the%20Rubin%20Science%20Platform%20%28data-dev.lsst.cloud%29.%20An%20instance%20of%20the%20Semaphore%20app%20is%20associated%20with%20each%20%5BRSP%20environment%5D%28https%3A%2F%2Fphalanx.lsst.io%2Fenvironments%2Findex.html%29.&url=https%3A%2F%2Fsemaphore.lsst.io&public=false&webhook_active=true&webhook_url=https%3A%2F%2Fdata-dev.lsst.cloud%2Fsemaphore%2Fgithub%2Fwebhook&events%5B%5D=push&events%5B%5D=check_run&contents=read&checks=write

Once you follow the link, you will be able to make further customizations to the GitHub App before creating it. These settings are described in the following sections.

GitHub App settings#

Name#

The name of the GitHub App should be “Semaphore (env)”. For example, Semaphore (data.lsst.cloud).

This naming convention distinguishes the Semaphore installations for each Phalanx environment.

Description#

Use the description provided with the GitHub App template URL, and modify it as needed.

Homepage URL#

Set this to the documentation URL, https://semaphore.lsst.io.

Identifying and authorizing users#

Not applicable.

Post installation#

Not applicable.

Webhook#

The webhook should be enabled. Set the webhook URL to the /semaphore/github/webhook endpoint in the RSP/Phalanx environment. For example, https://data.lsst.cloud/semaphore/github/webhook.

Create a webhook secret and store it in the SEMAPHORE_GITHUB_WEBHOOK_SECRET environment variable (through Vault/1Password).

Permissions#

The GitHub App needs the following repository permissions:

Checks: Read & write
Contents: Read-only
Metadata: Read-only

Events#

The GitHub App needs to subscribe to the following events:

Check Run
Push

Create the app and secrets#

Once the GitHub App is configured, you can click the Create GitHub App button to create it in your GitHub organization or user account.

When you do this, you can create the secret keys that Semaphore needs to authenticate with GitHub and verify webhook events. These are provided to Semaphore as environment variables:

SEMAPHORE_GITHUB_APP_ID: The GitHub App ID. This is shown on the GitHub App’s General page under the About heading.
SEMAPHORE_GITHUB_APP_PRIVATE_KEY: The GitHub App’s private key. This is shown on the GitHub App’s General page under Client secrets.
SEMAPHORE_GITHUB_WEBHOOK_SECRET: The webhook secret you created in the GitHub App’s General page under Webhooks.

See Environment variables for more information on Phalanx’s environment variable settings.

Install the app in the source repository#

Once the app is created and the Semaphore app is configured, you need to install the app in the source repository (or repositories, if there are several). From the app’s GitHub settings page, click Install App and select the repositories to install it in. Avoid installing the app in repositories that do not use Semaphore.