Skip to content

Latest commit

 

History

History
111 lines (80 loc) · 4.18 KB

CONTRIBUTING.md

File metadata and controls

111 lines (80 loc) · 4.18 KB
Raw

Contributing Guide

The Brigade GitHub Gateway is an official extension of the Brigade project and as such follows all of the practices and policies laid out in the main Brigade Contributor Guide. Anyone interested in contributing to this gateway should familiarize themselves with that guide first.

The remainder of this document only supplements the above with things specific to this project.

Running make hack-kind-up

As with the main Brigade repository, running make hack-kind-up in this repository will utilize ctlptl and KinD to launch a local, development-grade Kubernetes cluster that is also connected to a local Docker registry.

In contrast to the main Brigade repo, this cluster is not pre-configured for building and running Brigade itself from source, rather it is pre-configured for building and running this gateway from source. Because Brigade is a logical prerequisite for this gateway to be useful in any way, make hack-kind-up will pre-install a recent, stable release of Brigade into the cluster.

Create a GitHub App

Create a GitHub APP as described in this section of the installation docs. Use a placeholder for the Webhook URL field. This configuration will be revisited later.

Running tilt up

As with the main Brigade repository, running tilt up will build and deploy project code (the gateway, in this case) from source.

For the gateway to successfully communicate with the Brigade instance in your local, development-grade cluster, you will need to execute the following steps before running tilt up:

  1. Log into Brigade:

    $ brig login -k -s https://localhost:31600 --root

    The root password is F00Bar!!!.

  2. Create a service account for the gateway:

    $ brig service-account create \
    --id github-gateway \
    --description github-gateway

  3. Copy the token returned from the previous step and export it as the BRIGADE_API_TOKEN environment variable:

    $ export BRIGADE_API_TOKEN=<token from previous step>

  4. Grant the service account permission to create events:

    $ brig role grant EVENT_CREATOR \
  --service-account github-gateway \
  --source brigade.sh/github

    ⚠️  Contributions that automate the creation and configuration of the service account setup are welcome.

  5. Edit the github.apps section of charts/brigade-github-gateway/values.yaml with your appID, apiKey, and sharedSecret. Refer to instructions in this section of the installation docs for more information.

    ⚠️  Take care not to include modifications to the values.yaml file in any PRs you open.

You can then run tilt up to build and deploy this gateway from source.

Receiving Events from GitHub

Making the gateway that runs in your local, development-grade Kubernetes cluster visible to GitHub such that it can successfully deliver webhooks can be challenging. To help ease this process, our Tiltfile has built-in support for exposing your local gateway using ngrok. To take advantage of this:

  1. # for a free ngrok account.

  2. Follow ngrok setup & installation instructions

  3. Set the environment variable ENABLE_NGROK_EXTENSION to a value of 1 before running tilt up.

  4. After running tilt up, the option should become available in the Tilt UI at http://localhost:10350/ to expose the gateway using ngrok. After going so, the applicable ngrok URL will be displayed in the gateway's logs in the Tilt UI.

  5. Revisit your GitHub App configuration at https://github.com/settings/apps/<app name> and replace the placeholder value in the Webhook URL field with <ngrok URL>/events.

⚠️  We cannot guarantee that ngrok will work in all environments, especially if you are behind a corporate firewall.