vbehar/openshift-github-hooks repository overview

⁠OpenShift GitHub Hooks

Manages GitHub hooks for OpenShift BuildConfig triggers.

This Go⁠ application is an OpenShift⁠ client that can manage your GitHub Webhooks⁠ for your OpenShift BuildConfig⁠ triggers.

Its main feature is to keep your GitHub Webhooks in sync with your OpenShift BuildConfigs, and so automatically create/delete the webhooks on GitHub to reflect the build trigger⁠ changes on OpenShift.

It is very useful when you host your source code on a GitHub organization: instead of having to manually create your webhooks on GitHub when you create a new build on OpenShift (and then forget to delete it when you remove the build on OpenShift), you just need to run this application (on OpenShift), and let it handle all that boring stuff for you!

There are also additional commands, for example to list all the Hooks of a GitHub organization that references your OpenShift instance.

⁠How It Works

⁠Keep Webhooks in sync

This application can be deployed on OpenShift or anywhere else, but I guess you will want to run it in your OpenShift cluster - at least for the sync command that runs as a daemon. It should run with a ServiceAccount⁠ that has the cluster-reader role⁠, so that it can watch all the BuildConfigs⁠.

The sync command will listen for every BuildConfig change in the cluster, and for all BuildConfig with a GitHub Webhook trigger⁠, it will try to create the hook on the GitHub repository⁠, using the GitHub API⁠.

It will also list all the existing webhooks on GitHub, and remove webhooks that references non-existing OpenShift BuildConfigs.

At a pre-defined period interval, it will re-sync everything, to make sure it didn't miss any event.

⁠Exceptions

If you want to bypass this automatic hook creation for a specific BuildConfig, you can just set the openshift-github-hooks-sync/ignore annotation to true:

kind: BuildConfig
apiVersion: v1
metadata:
  annotations:
  	openshift-github-hooks-sync/ignore: "true"
[...]

With this annotation (and its value set to true), no GitHub Webhook will be created/deleted.

⁠Listing Webhooks

The list command will just use the GitHub API to list webhooks and print them in the standard output.

It uses a GitHub Access Token⁠ to talk to the GitHub API. You can create such a token in your GitHub Tokens Settings⁠ page. It requires the repo and admin:repo_hook scopes, to be able to list repositories, and list/create/delete hooks.

⁠Usage

Pre-build binaries for the main platforms (darwin-amd64, linux-amd64 and windows-amd64) are available in bintray⁠:

https://bintray.com/vbehar/openshift-github-hooks/openshift-github-hooks/_latestVersion#files⁠

This application has many commands, you can list them by running:

openshift-github-hooks -h

⁠Running on OpenShift

If you want to deploy this application on an OpenShift cluster to run the sync command as a controller, you need to:

• create a project named github-hooks-controller:

  oc new-project github-hooks-controller
  

  Copy

• create a specific ServiceAccount⁠ named github-hooks-controller, using the provided openshift-serviceaccount.yml⁠ definition file:

  oc create -f openshift-serviceaccount.yml
  

  Copy

• as a cluster admin, give the cluster-reader role to your new ServiceAccount:

  oadm policy add-cluster-role-to-user cluster-reader system:serviceaccount:github-hooks-controller:github-hooks-controller
  

  Copy

• create a new application from the provided openshift-template-deploy-only.yml⁠ template, and overwrite some parameters:

  oc new-app -f openshift-template-deploy-only.yml -p SERVICE_ACCOUNT=github-hooks-controller,GITHUB_ACCESS_TOKEN=xxx,GITHUB_ORGANIZATION=yyy
  

  Copy

Of course, replace xxx by the value of your GitHub Access Token⁠. To create such a token, go to your GitHub Tokens Settings⁠ page, and create a new token with the repo and admin:repo_hook scopes. You also need to define the GitHub organization name for which the controller will manage the hooks.

You can use either of the following templates:

• openshift-template-deploy-only.yml⁠ to just deploy from an existing Docker image - by default vbehar/openshift-github-hooks⁠
• openshift-template-full.yml⁠ to build from sources (by default the vbehar/openshift-github-hooks⁠ github repository) and then deploy

⁠Building from sources

If you want to build it from sources:

• Install Go⁠ (tested with 1.6) and setup your GOPATH⁠

• clone the sources in your GOPATH

  git clone https://github.com/vbehar/openshift-github-hooks.git $GOPATH/src/github.com/vbehar/openshift-github-hooks
  

  Copy

• install godep⁠ (to use the vendored dependencies)

  go get github.com/tools/godep
  

  Copy

• build the binary with godep:

  cd $GOPATH/src/github.com/vbehar/openshift-github-hooks
  godep go install
  

  Copy

• have a look at the application commands, help messages and examples:

  $GOPATH/bin/openshift-github-hooks -h
  $GOPATH/bin/openshift-github-hooks list -h
  $GOPATH/bin/openshift-github-hooks sync -h
  

  Copy

  • if you want to run the sync command, you will need to get your GitHub Access Token⁠ and the GitHub organization name, and then run:

    $GOPATH/bin/openshift-github-hooks sync --github-token="..." --organization="..."
    

    Copy

  • for the list command, you will also need to get your GitHub Access Token⁠ and the GitHub organization name, and then run:

    $GOPATH/bin/openshift-github-hooks list --github-token="..." --organization="..."
    

    Copy

• enjoy!

⁠License

Copyright 2016 the original author or authors.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.