Lighthouse
Lighthouse is a lightweight ChatOps based webhook handler which can trigger Jenkins X Pipelines, Tekton Pipelines or Jenkins Jobs based on webhooks from multiple git providers such as GitHub, GitHub Enterprise, BitBucket Server and GitLab.
Installing
Lighthouse is bundled and released as Helm Chart. You find the install instruction in the Chart's README.
Depending on the pipeline engine you want to use, you can find more detailed instructions in one of the following documents:
Background
Lighthouse derived originally from Prow and started with a copy of its essential code.
Currently, Lighthouse supports the standard Prow plugins and handles push webhooks to branches to then trigger a pipeline execution on the agent of your choice.
Lighthouse uses the same config.yaml
and plugins.yaml
for configuration than Prow.
Comparisons to Prow
Lighthouse reuses the Prow plugin source code and a bunch of plugins from Prow
Its got a few differences though:
- rather than being GitHub specific Lighthouse uses jenkins-x/go-scm so it can support any Git provider
- Lighthouse does not use a
ProwJob
CRD; instead, it has its ownLighthouseJob
CRD.
Porting Prow commands
If there are any prow commands you want which we've not yet ported over, it is relatively easy to port Prow plugins.
We've reused the prow plugin code and configuration code; so it is mostly a case of switching imports of k8s.io/test-infra/prow
to github.com/jenkins-x/lighthouse/pkg/prow
, then modifying the GitHub client structs from, say, github.PullRequest
to scm.PullRequest
.
Most of the GitHub structs map 1-1 to the jenkins-x/go-scm equivalents (e.g. Issue, Commit, PullRequest).
However, the go-scm API does tend to return slices to pointers to resources by default.
There are some naming differences in different parts of the API as well.
For example, compare the githubClient
API for Prow lgtm versus the Lighthouse lgtm.
Development
Building
To build the code, fork and clone this git repository, then type:
make build
make build
will build all relevant Lighthouse binaries natively for your OS which you then can run locally.
For example, to run the webhook controller, you would type:
./bin/webhooks
To see which other Make rules are available, run:
make help
Environment variables
While Prow only supports GitHub as SCM provider, Lighthouse supports several Git SCM providers. Lighthouse achieves the abstraction over the SCM provider using the go-scm library. To configure your SCM, go-scm uses the following environment variables :
Name | Description |
---|---|
GIT_KIND |
the kind of git server: github, gitlab, bitbucket, gitea, stash |
GIT_SERVER |
the URL of the server if not using the public hosted git providers: https://github.com, https://bitbucket.org or https://gitlab.com |
GIT_USER |
the git user (bot name) to use on git operations |
GIT_TOKEN |
the git token to perform operations on git (add comments, labels etc.) |
HMAC_TOKEN |
the token sent from the git provider in webhooks |
Testing
To run the unit tests, type:
make test
For development purposes, it is also nice to start an instance of the binary you want to work. Provided you have a connection to a cluster with Lighthouse installed, the locally started controller will join the cluster, and you can test your development changes directly in-cluster.
For example to run the webhook controller locally:
make build
GIT_TOKEN=<git-token> ./bin/webhooks -namespace <namespace> -bot-name <git-bot-user>
In the case of the webhook controller, you can also test webhook deliveries locally using a ngrok tunnel. Install ngrok and start a new tunnel:
$ ngrok http 8080
ngrok by @inconshreveable (Ctrl+C to quit)
Session Status online
Account ***
Version 2.3.35
Region United States (us)
Web Interface http://127.0.0.1:4040
Forwarding http://e289dd1e1245.ngrok.io -> http://localhost:8080
Forwarding https://e289dd1e1245.ngrok.io -> http://localhost:8080
Connections ttl opn rt1 rt5 p50 p90
0 0 0.00 0.00 0.00 0.00
Now you can use your ngrok URL to register a webhook handler with your Git provider.
NOTE Remember to append /hook
to the generated ngrok URL.
In the case of the above example http://e289dd1e1245.ngrok.io/hook
Any events that happen on your Git provider are now sent to your local webhook instance.
Debugging Lighthouse
You can setup a remote debugger for Lighthouse using delve via:
dlv --listen=:2345 --headless=true --api-version=2 exec ./bin/lighthouse -- $*
You can then debug from your Go-based IDE (e.g. GoLand / IDEA / VS Code).
Debugging webhooks
If you want to debug lighthouse locally from webhooks in your cluster there are a couple of tools that could help:
Localizer
If you install localizer (see the blog for more detail you can easily debug webhooks on your cluster.
- first run localizer:
sudo localizer
Then run/debug lighthouse locally.
e.g. in your IDE run the cmd/webhooks/main.go (passing --namespace jx
as program arguments)
Then to get the webhooks to trigger your local process:
localizer expose jx/hook --map 80:8080
when you have finished debugging, return things to normal via:
localizer expose jx/hook --stop
Telepresence
You can replace the running version in your cluster with the one running locally using telepresence.
First install the telepresence cli on your device then the traffic-manager into your cluster
For webhooks, just run:
telepresence intercept hook --namespace=jx --port 80 --env-file=/tmp/webhooks-env
in another terminal:
export $(cat /tmp/webhooks-env | xargs)
dlv --listen=:2345 --headless=true --api-version=2 exec ./bin/webhooks -- --namespace=jx
You can do the same for any other deployment (keeper, foghorn...), just make sur to check the command args used for it an set them instead of --namespace=jx
.
to stop intercepting:
telepresence leave hook-jx # hook-jx is the name of the intercept
Using a local go-scm
If you are hacking on support for a specific Git provider, you may find yourself working on the Lighthouse code and the jenkins-x/go-scm code together. Go modules lets you easily swap out the version of a dependency with a local copy of the code; so you can edit code in Lighthouse and jenkins-x/go-scm at the same time.
Just add this line to the end of your go.mod file:
replace github.com/jenkins-x/go-scm => /workspace/go/src/github.com/jenkins-x/go-scm
Using the exact path to where you cloned jenkins-x/go-scm