OpenShift GitHub Hooks
Manages GitHub hooks for 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.
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.
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
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.
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
admin:repo_hook scopes, to be able to list repositories, and list/create/delete hooks.
Pre-build binaries for the main platforms (
windows-amd64) are available in bintray:
This application has many commands, you can list them by running:
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
oc new-project github-hooks-controller
oc create -f openshift-serviceaccount.yml
as a cluster admin, give the
cluster-readerrole to your new ServiceAccount:
oadm policy add-cluster-role-to-user cluster-reader system:serviceaccount:github-hooks-controller:github-hooks-controller
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
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
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
git clone https://github.com/vbehar/openshift-github-hooks.git $GOPATH/src/github.com/vbehar/openshift-github-hooks
install godep (to use the vendored dependencies)
go get github.com/tools/godep
build the binary with godep:
cd $GOPATH/src/github.com/vbehar/openshift-github-hooks godep go install
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
if you want to run the
synccommand, 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="..."
listcommand, 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="..."
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
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.