Skip to content

Files

Latest commit

 

History

History
130 lines (121 loc) · 6.48 KB

PREBUILDS.md

File metadata and controls

130 lines (121 loc) · 6.48 KB

App Creation in Github

In addition to the OAuth app that is used for normal execution (non-prebuilds), which effectively acts on behalf of the user operating the browser, a GitHub app also needs to be installed for pre-builds. This has its own user id and does not operate on behalf of the user. The required configuration items are:

Create App in GitHub:

  1. Log in as organization account (i.e. trilogy-group) in github.
  2. Go to Developer Settings
  3. Go to GitHub Apps
  4. Click New GitHub App
  5. Configure the following app settings:
    • Main:
      • AppName: Required. Will be shown in Marketplace if we make prebuilds public
      • Homepage URL: Required. Will be displayed in Marketplace if the app is made public. Can be changed later.
      • Callback URL: https://{hostname}/install-github-app
      • Expire user authentication tokens: Unchecked (if checked, can have errors starting a prebuild)
      • Request user authorization (OAuth) during installation: Leave unchecked (value is irrelevant, since our callback URL automatically performs user authorization using our GitHub OAuth app regardless of this setting)
      • Setup URL: https://{hostname}/install-github-app (i.e., the same as Callback URL)
      • Redirect on update: Leave unchecked
    • Webhook:
      • Active: Leave checked
      • Webhook URL: https://{hostname}/apps/github/ (include the trailing slash)
      • Webhook secret: Required. Generate a random 20-digit hex string.
    • Repository Permissions: Enable only the following:
      • Contents - Read-only
      • Issues - Read & Write
      • Metadata - Read-only
      • Pull Requests - Read & Write
      • Commit statuses - Read & Write
    • Subscribe to events: Select only the following:
      • Meta
      • Pull request
      • Push
    • Where can this GitHub App be installed?:
      • Any account
  6. Click Create GitHub App

On the next screen, note down the App ID Generate a private key. This key file needs to be installed as a secret in kubernetes Note down the app public url. Should be something like https://github.com/apps/{appname}

Install App in Devspaces

There are two installation methods. Either via values.yaml or by editing the running deployment. In both cases, the private key needs to be installed as a kubernetes secret.

Secret Key Installation

kubectl create secret generic github-app-cert-secret --from-file=cert={keyfilename}

Values in values.yaml

Under components.server.github.app, create the following keys:

  • enabled: “true”
  • appId: “{AppID obtained when app created}”
  • webhookSecret: “{20-digit hex secret you created when creating the app}”
  • authProviderId: Value from values.yaml under authproviders for the “name” of the github oauth provider. Gitpod default is “Public-GitHub”. Devspaces seems to use “Github”
  • baseUrl: “github.com” (not required)
  • marketplaceName: Name of the app in the marketplace. However, this value is not currently used anywhere in the code. If app is not put into the marketplace, suggest setting to empty string.

Install on Running Devspaces Deployment

To enable the prebuild github app on a running deployment, the following changes are needed on the server deployment.

  1. Get the current deployment: kubectl get deployment server -o json >{tempfile.json}

  2. Edit the json file: Search for ws-manager-client-tls-certs. For match inside volume mounts, add array element:

                            {
                                "mountPath": "/github-app-cert",
                                "name": "github-app-cert-secret",
                                "readOnly": true
                            }

For match inside volumes, add array element:

                    {
                        "name": "github-app-cert-secret",
                        "secret": {
                            "defaultMode": 420,
                            "secretName": "github-app-cert-secret"
                        }
                    }

Search for env vars (look under ENABLE_LOCAL_APP) and add following elements

                            {  
                                "name": "GITPOD_GITHUB_APP_ENABLED",
                                "value": "true"
                            },
                            {
                                "name": "GITPOD_GITHUB_APP_ID",
                                "value": "{AppID}"
                            },
                            {
                                "name": "GITPOD_GITHUB_APP_WEBHOOK_SECRET",
                                "value": "{Secret}"
                            },
                            {
                                "name": "GITPOD_GITHUB_APP_AUTH_PROVIDER_ID",
                                "value": "{AuthProviderName}"
                            },
                            {
                                "name": "GITPOD_GITHUB_APP_CERT_PATH",
                                "value": "/github-app-cert/cert"
                            },
                            {
                                "name": "GITPOD_GITHUB_APP_MKT_NAME",
                                "value": "{MarketplaceName}"
                            },
  1. Apply the new deployment kubectl apply -f {tempfile.json}

Install App in Github User

  1. Log into github as the user to install the app on. This should be the organization user that owns the repos to be prebuilt (e.g. trilogy-group), not the individual users within that organization. (But can also be performed by individual users to get pre-builds working on their private repos)
  2. Access the public url of the app. Should be of the form: https://github.com/apps/{appname}
  3. Click install
  4. Accept everything.

Testing

To test that the prebuilds is working, you need a github repo that has prebuild tasks. (I.e., the .gitpod.yml file specifies at least one init or before task). If you create a new repo for testing, you can use the following .gitpod.yml file:

tasks:
  - before: sleep 20 && echo 'before script' # runs during prebuild
    init: sleep 20 && echo 'init script' # runs during prebuild
    command: echo 'start script'
github:
  prebuilds:
    addBadge: true
    addCheck: true
    addComment: true
    addLabel: "devspaces-prebuild-done-label"

Create a branch and then create a pull request. If everything is working, the pull request page on github should get updated by devspaces, and you should be able to click the link on the page to open the prebuilding devspace and watch its progress.