Jenkins Webhook Proxy
The webhook proxy service allows to trigger Jenkins pipelines. Further, it automatically creates pipelines that do not exist yet and can delete pipelines that are no longer needed.
One instance of the webhook proxy runs in every <project>-cd
namespace next to
the Jenkins instance.
Endpoints
POST /
Accepts webhooks from BitBucket and forwards them to the corresponding Jenkins
pipeline (which is determined based on the component param and the branch name).
If there is no corresponding pipeline yet, it will be created on the fly (by
creating a BuildConfig
in OpenShift which is synced to Jenkins via the
OpenShift plugin). Once a branch is deleted or a pull request declined/merged,
the corresponding Jenkins pipeline is deleted.
POST /build
Accepts a payload of the following form:
{
"branch": "foo",
"repository": "repository",
"env": [
{
"name": "FOO_BAR",
"value": "baz"
}
],
"project": "bar"
}
Important: In order to avoid conflicts between pipelines created/triggered
via BitBucket and pipelines created/triggered via /build
, most likely you’d
want to pass a component name to /build
, like so: /build?component=foo
, see
the next section.
Also note that the project
field is optional, and restricted to the project of the webhook proxy and opendevstack
by default (but can be customized via ALLOWED_EXTERNAL_PROJECTS
).
Parameters
Both /
and /build
accept the following query parameters. They are offered
as query parameters only because otherwise they could not be adjusted for
BitBucket webhooks.
Variable | Description |
---|---|
jenkinsfile_path |
The path to the |
component |
The component part of the pipeline name. If not given, the pipeline name is created from the repository and the branch. |
Responses
All endpoints return the BuildConfig
response as-is from OpenShift, see https://docs.openshift.com/container-platform/3.11/rest_api/apis-build.openshift.io/v1.BuildConfig.html#object-schema.
Adding a webhook in BitBucket
The provisioning app sets up one webhook per repository by default. It is
possible to create webhooks manually as well, e.g. to add more than one
webhook (likely differentiated by the component
param then).
To manually create a webhook, go to "Repository Settings > Webhooks" and click on "Create webhook". Fill in the following:
-
Name:
Jenkins
(or similar, value is only serves as a description) -
URL: route to the webhook proxy instance, followed by the
trigger_secret
, e.g.https://webhook-proxy-foo-cd.example.com?trigger_secret=s3cr3t
. The secret can be retrieved in the OpenShift console in your*-cd
namespace (in this examplefoo-cd
) under "Resources > Secrets > webhook-proxy". -
Secret: leave blank
-
Under "Repository events", select
Push
. Under "Pull request events", selectMerged
andDeclined
Now you can verify by clicking "Test connection". Afterwards, save your changes. The next pushed commit should automatically send a request to the webhook proxy and start a pipeline in Jenkins.
Customizing the behaviour of the webhook proxy
The following environment variables can be set on the DeploymentConfig
and are read by the webhook proxy:
Variable | Description |
---|---|
ACCEPTED_EVENTS |
Comma-separated list of handled Bitbucket events. Defaults to |
ALLOWED_CHANGE_REF_TYPES |
Comma-separated list of Bitbucket change refs. Defaults to |
ALLOWED_EXTERNAL_PROJECTS |
Comma-separated list of external projects which the Webhook Proxy can deal with. For security reasons, by default the webhook proxy allows only its own project and the |
OPENSHIFT_API_HOST |
Defaults to |
PROTECTED_BRANCHES |
Comma-separated list of branches which pipelines should not be removed after they have been merged. Use either exact branch names, branch prefixes (e.g. |
REPO_BASE |
The base URL of the repository (e.g. your BitBucket host). This variable is set by the OpenShift template from which the |
TRIGGER_SECRET |
The secret which protects the pipeline to be executed from outside. This variable is set by the OpenShift template from which the |