diff options
| -rw-r--r-- | INSTALL | 115 |
1 files changed, 114 insertions, 1 deletions
@@ -356,8 +356,121 @@ For sample CI request handler implementations see brep/handler/ci/. 6.4 Enabling GitHub CI integration -@@ TODO +6.4.1 Background +This GitHub CI integration only has one user-configurable option: +warning=<success|failure> (whether or not to fail on warnings). + +In order not to have to support repository configuration files a deployment +will consist of two registered GitHub apps with the same webhook URL (i.e., +the same brep instance) but different query parameters: one with +warning=success and the other with warning=failure. The app id is passed so +that we know which private key to use (the key cannot be shared between apps). + +We will call the warning=success app the "default app" and the warning=failure +app the "strict app". + +6.4.2 Create the GitHub apps + +Note that these instructions assume deployment to stage.build2.org; some +details would have to be adapted for other deployments. + +To create a GitHub app under the build2 organization, visit +https://github.com/organizations/build2/settings/apps. Alternatively, starting +from the build2 organization's page at https://github.com/build2, click on +Settings, Developer settings (bottom left), and GitHub Apps. Then click on New +GitHub App. + +App name (note: 34 character limit): + +Default app: "build2 stage CI" +Strict app: "build2 stage CI|warnings as errors" + + @@ TMP With " - warnings are errors" the name is rejected as too long. + +Description: + +Default app: "Trigger build2 CI on branch push and pull request." +Strict app: "Trigger build2 CI on branch push and pull request. Warnings are + treated as errors". + +Homepage: https://ci.stage.build2.org/ + +Skip the "Identifying and authorizing users" and "Post installation" sections. + +Leave webhooks active. + +Webhook URL: + +Default app: https://ci.stage.build2.org/?ci-github&app-id=XXX&warning=success +Strict app: https://ci.stage.build2.org/?ci-github&app-id=XXX&warning=failure + +Note that the app id only becomes available once the app has been registered +so we will update it later in both URLs. + +Webhook secret: Use the same random 64-character string for both apps. + +GitHub says only that the secret should be "a random string with high +entropy." However lots of sources say 32 bytes should be secure enough for +HMAC-SHA256, while other sources recommend 64 bytes for maximal security at an +insignificant performance cost. (Keys longer than 64 bytes are hashed to match +the internal block size and are therefore not recommended.) + + @@ TMP I feel like 64 characters might be a good length? + +Repository permissions: + - Checks: RW + - Contents: RO (for Push events) + - Metadata (mandatory): RO + - Pull requests: RO + +Subscribed events: + - Check suite + - Pull request + - Push + +Note that GitHub apps with write access to the "Checks" permission are +automatically subscribed to check_suite(requested|rerequested) and check_run +events so no need to subscribe explicitly. However in order to receive +check_suite(completed) events, which we do, one does have to subscribe to +Check suite. + +Select "Any account" under "Where can this GitHub App be installed?". + +Click "Create GitHub App". + +When the page reloads (should be the General tab), note the app id and replace +the XXX in the webhook URL with it. + +Still in the General tab, scroll to Private keys and generate a private +key. The file will be downloaded by the browser. + +@@ TODO Logo + +@@ TODO Create Marketplace listing + +6.4.3 Configure brep + +Assume the following configuration values: + +- Webhook secret: deadbeef +- Default app id: 12345 +- Strict app id: 67890 + +In brep-module.conf: + +Set the webhook secret from the GitHub app settings: + + ci-github-app-webhook-secret "deadbeef" + +Associate each GitHub app id with the app's private key: + + ci-github-app-id-private-key 12345=path/to/default-app-private-key.pem + ci-github-app-id-private-key 67890=path/to/strict-app-private-key.pem + +Now brep should be ready to handle the webhook event requests triggered by +branch pushes and pull requests in repositories into which one of these apps +has been installed. 7. Optimize CSS |