diff options
| -rw-r--r-- | INSTALL | 96 |
1 files changed, 46 insertions, 50 deletions
@@ -358,43 +358,39 @@ For sample CI request handler implementations see brep/handler/ci/. 6.4.1 Background -This GitHub CI integration only has one user-configurable option: +The GitHub CI integration has one user-configurable setting: 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., +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). +warning=success and the other with warning=failure. The App id is passed (as a +query parameter) 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". +We will call the warning=success App the "Default App" and the warning=failure +App the "Werror App". -6.4.2 Create the GitHub apps +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 <org> organization, visit +https://github.com/organizations/<org>/settings/apps (Settings -> Developer +settings -> GitHub Apps). Then click on New GitHub App. -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 names (note: 34 character limit): -App name (note: 34 character limit): + Default App: "<org> CI" + Werror App: "<org> CI - warnings as errors" -Default app: "build2 stage CI" -Strict app: "build2 stage CI|warnings as errors" +App description: - @@ TMP With " - warnings are errors" the name is rejected as too long. + Default App: "Trigger <org> CI on branch push and pull request." + Werror App: "Trigger <org> CI on branch push and pull request. Warnings are + treated as errors". -Description: +App homepage: -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/ + https://ci.<org>.org/ Skip the "Identifying and authorizing users" and "Post installation" sections. @@ -402,21 +398,21 @@ 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 + Default App: https://ci.<org>.org/?ci-github&app-id=XXX&warning=success + Werror App: https://ci.<org>.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. +Note that the App id only becomes available once the App has been registered +so we update it later in both URLs. -Webhook secret: Use the same random 64-character string for both apps. +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.) + echo `tr -dc -- A-Za-z0-9 </dev/urandom | head -c 64` - @@ TMP I feel like 64 characters might be a good length? +Note that 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.) Repository permissions: - Checks: RW @@ -429,49 +425,49 @@ Subscribed events: - Pull request - Push -Note that GitHub apps with write access to the "Checks" permission are +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(completed) events, which we need, 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 +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. +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 +- Webhook secret: abcdefg +- Default App id: 12345 +- Werror App id: 67890 In brep-module.conf: -Set the webhook secret from the GitHub app settings: +Set the webhook secret from the GitHub App settings: - ci-github-app-webhook-secret "deadbeef" + ci-github-app-webhook-secret abcdefg -Associate each GitHub app id with the app's private key: +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 + ci-github-app-id-private-key 67890=path/to/werror-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 +branch pushes and pull requests in repositories into which one of these Apps has been installed. + 7. Optimize CSS This step is optional and involves optimizing the CSS files used by brep. For |