Brigade OAuth Gateway
Note: this is the initial GitHub gateway that shipped with Brigade, and uses a per-repository OAuth model. The new, and recommended way, is to use the GitHub app model, implemented in this repo.
Brigade provides GitHub integration for triggering Brigade builds from GitHub events.
Brigade integrates with GitHub by providing GitHub webhook implementations for the following events:
push: Fired whenever something is pushed
pull_request: Fired whenever a pull request's state is changed. See the
actionvalue in the payload, which will be one of the following:
pull_request:labeled: Fired whenever a label is added to a pull request.
pull_request:unlabeled: Fired whenever a label is removed from a pull request.
create: Fired when a tag, branch, or repo is created.
release: Fired when a new release is created.
status: Fired when a status change happens on a commit.
commit_comment: Fired when a comment is added to a commit.
You must be running
brigade-github-gateway in a way that makes
it available to GitHub. (For example, assign it a publicly routable IP and domain name.)
Configuring Your Project
Brigade uses projects to tie repositories to builds. Check out the project documentation if you haven't already.
When creating a project with
brig project create, the following information is required for
GitHub integration to function:
- Repository name, e.g.
- Clone URL, e.g.
- A shared secret for GitHub Webhooks (this will be auto-generated if not provided)
- A GitHub Oauth2 token
Assuming these values have been entered, the resulting project should be good to go.
To add a Brigade project to GitHub:
- Go to "Settings"
- Click "Webhooks"
- Click the "Add webhook" button
- For "Payload URL", add the URL: "http://YOUR_HOSTNAME:7744/events/github"
- For "Content type", choose "application/json"
- For "Secret", use the shared secret configured via
- Choose "Just the push event" or choose specific events you want to receive, such as "push" and "pull_request".
Each event you select here will increase the number of events that fire within the Brigade system. We recommend only enabling the events that you are using, as enabling unused events will merely result in extra load on your system.
You may use GitHub's testing page to verify that GitHub can successfully send an event to the Brigade gateway.
Finding Your Gateway's URL
To find your "Payload URL" IP address, you can run this command on your Kubernetes cluster:
$ kubectl get service NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE brigade-brigade-api ClusterIP 10.0.0.57 <none> 7745/TCP 8h brigade-brigade-gw LoadBalancer 10.0.0.157 10.21.77.9 7744:31946/TCP 8h
EXTERNAL-IP for the
brigade-gw service is the one you will use. You can
map this to a DNS name if you wish.
The gateway listens on port
7744, so the URL for the above will be
Protectecting Your Gateway with SSL/TLS
Please note that
cert-manageris pre-1.0, and does not currently offer strong guarantees around the API stability and
kube-legois in maintenance mode only, with Kubernetes 1.8 as the last release with official support
In this case, once the NGINX proxy is set up with SSL, you can point your
GitHub "Payload URL" to the proxy instead of directly at the
Configuring the GitHub Gateway
Running Pull Requests from untrusted parties is dangerous. It can consume your
Brigade resources, or even (in some cases) allow access to private information
For that reason, the Brigade GitHub gateway tries to protect your repo by default.
By default, when you install Brigade, the GitHub gateway is configured to ignore pull requests that come from forks.
By default, your Brigade GitHub gateway is configured to ONLY build PRs that were submitted by authors with trusted roles:
- OWNER: The repo owner
- COLLABORATOR: Someone who is an invited collaborator on the project
- MEMBER: Someone who is a member of the organization that this repo belongs to
There are two configuration options that can alter these defaults:
gw.buildForkedPullRequests: This can be set to
trueto allow forked pull requests to build. If this is true, the author check is applied to these users.
gw.allowedAuthorRoles: This is a list of author roles that are allowed to build PRs. This list is always applied, whether the PR is from forked repository or not.
Here is an example that upgrades Brigade to allow forked builds, but only from the OWNER and COLLABORATOR author roles:
$ helm upgrade brigade brigade/brigade \ --set gw.buildForkedPullRequests=true \ --set gw.allowedAuthorRoles=COLLABORATOR\,OWNER \ --reuse-values
Note that this configuration will not eliminate all possibilities of mis-use (a comprimized GitHub account is still a vector of attack). But it will restrict PRs to only accounts that are owners or collaborators (invited contributors) on the main repository.
Connecting to Private GitHub Repositories (or Using SSH)
Sometimes it is better to configure Brigade to interact with GitHub via SSH. For example, if your repository is private and you don't want to allow anonymous Git clones, you may need to use an SSH GitHub URL. To use GitHub with SSH, you will also need to create a Deployment Key.
To create a new GitHub Deployment Key, generate an SSH key. On UNIX-like systems, this is
ssh-keygen -f ./github_deployment_key. When prompted to set a passphrase, do not set a passphrase.
ssh-keygen -f ./github_deployment_key Generating public/private rsa key pair. Enter passphrase (empty for no passphrase): Enter same passphrase again: Your identification has been saved in ./github_deployment_key. Your public key has been saved in ./github_deployment_key.pub. ...
In GitHub, navigate to your project, choose Settings (the gear icon), then choose Depoyment Keys from the left-hand navigation. Click the Add deploy key button.
The Title field should be something like
brigade-checkout, though the intent of this
field is just to help you remember that this key was used by Brigade.
The Key field should be the content of the
./github_deployment_key.pub file generated
Save that key.
Inside of your project configuration for your
brigade-project, make sure to add your key:
project: "my/brigade-project" repository: "github.com/my/brigade-project" # This is an SSH clone URL cloneURL: "email@example.com:my/brigade-project.git" # paste your entire key here: sshKey: |- -----BEGIN RSA PRIVATE KEY----- MIIEowIBAAKCAQEAupolYH/x2+V+L15ci3PU75GX8aKTWZzCPkX3qNqRqiO5q0LV nMIVeMSqrLDHSGnbUF6DN3EgKuwdv0bfiq3Cz1rjtszQX6ti50ICObGphU+6dTwO # removed some lines 9KjBbQKBgA23dOOF98EjLcCZm/lky+Ifu2ZSbi+5N8MlbP3+5rWIgw74iAo6KHFb v/mHCUT7SWguIdNGzdAD+wYHG2W14fu+IQCWQ6oaZauHHqlxGrXH -----END RSA PRIVATE KEY----- # The rest of your config...
Then you can install (or upgrade) your project:
$ helm install -n my-project brigade/brigade-project -f myvalues.yaml
Now your project is configured to clone via SSH using the deployment key we generated.
This Brigade project accepts contributions via GitHub pull requests. This document outlines the process to help get your contribution accepted.
A DCO sign-off is required for contributions to repos in the brigadecore org. See the documentation in Brigade's Contributing guide for how this is done.