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 Jenkinsfile. By default, the Jenkinsfile is assumed to be in the root of the repository, therefore this value defaults to simply Jenkinsfile.

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 example foo-cd) under "Resources > Secrets > webhook-proxy".

  • Secret: leave blank

  • Under "Repository events", select Push. Under "Pull request events", select Merged and Declined

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 are read by the proxy:

Variable Description

PROTECTED_BRANCHES

Comma-separated list of branches which pipelines should not be cleaned up. Use either exact branch names, branch prefixes (e.g. feature/) or * for all branches. Defaults to: master,develop,production,staging,release/.

OPENSHIFT_API_HOST

Defaults to openshift.default.svc.cluster.local. Usually does not need to be modified.

REPO_BASE

The base URL of the repository (e.g. your BitBucket host). This variable is set by the template and usually does not need to be modified.

TRIGGER_SECRET

The secret which protects the pipeline to be executed from outside. This variable is set by the template and usually does not need to be modified.

ALLOWED_EXTERNAL_PROJECTS

Comma-separated list of external projects which the Webhook Proxy can deal with. By default, this is just the opendevstack project.

Development

See the Makefile targets.