Configuring the GitHub App¶

Times Square operates as a GitHub App to access notebooks in GitHub repositories, to get webhooks when those notebooks change, and to offer status checks for pull requests that change notebooks. Each installation of Times Square in different Phalanx environments has its own GitHub App in order to receive webhook events. Times Square 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.

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=Times%20Square%20%28data-dev.lsst.cloud%29&description=Times%20Square%20is%20a%20service%20for%20parameterized%20Jupyter%20Notebooks%20as%20dynamic%20webpages.%20An%20instance%20of%20the%20Times%20Square%20app%20is%20associated%20with%20each%20%5BRSP%20environment%5D%28https%3A%2F%2Fphalanx.lsst.io%2Fenvironments%2Findex.html%29.&url=https%3A%2F%2F%7Bdomain%7D%2Ftimes-square%2F&public=false&webhook_active=true&webhook_url=https%3A%2F%2Fdata-dev.lsst.cloud%2Ftimes-square%2Fapi%2Fgithub%2Fwebhook&events%5B%5D=push&events%5B%5D=check_run&events%5B%5D=check_suite&events%5B%5D=pull_request&events%5B%5D=repository&contents=read&pull_requests=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=Times%20Square%20%28data-dev.lsst.cloud%29&description=Times%20Square%20is%20a%20service%20for%20parameterized%20Jupyter%20Notebooks%20as%20dynamic%20webpages.%20An%20instance%20of%20the%20Times%20Square%20app%20is%20associated%20with%20each%20%5BRSP%20environment%5D%28https%3A%2F%2Fphalanx.lsst.io%2Fenvironments%2Findex.html%29.&url=https%3A%2F%2F%7Bdomain%7D%2Ftimes-square%2F&public=false&webhook_active=true&webhook_url=https%3A%2F%2Fdata-dev.lsst.cloud%2Ftimes-square%2Fapi%2Fgithub%2Fwebhook&events%5B%5D=push&events%5B%5D=check_run&events%5B%5D=check_suite&events%5B%5D=pull_request&events%5B%5D=repository&contents=read&pull_requests=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 “Times Square (env)”. For example, Times Square (data.lsst.cloud).

This naming convention distinguishes the Times Square 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 Times Square app in the RSP, e.g. https://data-dev.lsst.cloud/times-square/.

Identifying and authorizing users¶

Not applicable.

Post installation¶

Not applicable.

Webhook¶

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

Create a webhook secret and store it in the TS_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
Pull requests: Read-only

Events¶

The GitHub App needs to subscribe to the following events:

Check Run
Check Suite
Push
Pull request
Repository

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 Times Square needs to authenticate with GitHub and verify webhook events. These are provided to Times Square as environment variables:

TS_GITHUB_APP_ID: The GitHub App ID. This is shown on the GitHub App’s General page under the About heading.
TS_GITHUB_APP_PRIVATE_KEY: The GitHub App’s private key. This is shown on the GitHub App’s General.
TS_GITHUB_WEBHOOK_SECRET: The webhook secret you created in the GitHub App’s General page under Webhooks.
TS_GITHUB_ORGS: A comma-separated list of the GitHub organizations that Times Square should operate on. For a private GitHub App, this should be the organization that owns the app. See also: Sourcing notebooks from multiple GitHub organizations.

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 Times Square 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 Times Square.

Sourcing notebooks from multiple GitHub organizations¶

By default, the Times Square GitHub App is configured as “private,” meaning that it can only be installed in repositories owned by the organization that owns the GitHub App. If you want to source notebooks from multiple GitHub organizations, you need to configure the GitHub App as “public” instead. There are three steps involved in doing this:

Update the TS_GITHUB_ORGS environment variable in the Times Square configuration to include the additional organizations. For example, set it to lsst,lsst-dm,lsst-sqre.
Update the GitHub App to be “public” instead of “private.” This is done on the GitHub App’s Advanced settings page under the Make this GitHub App public heading.
Install the GitHub App in additional repositories in the other GitHub organizations.