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

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 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 repo:refs_changed,pr:declined,pr:merged,pr:deleted.

ALLOWED_CHANGE_REF_TYPES

Comma-separated list of Bitbucket change refs. Defaults to BRANCH, which means tags do not create pipelines nor forward to them. If you want this to happen, specify e.g. BRANCH,TAG.

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 opendevstack project to be passed as a project parameter.

OPENSHIFT_API_HOST

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

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. feature/) or * for all branches. Defaults to: master,develop,production,staging,release/.

REPO_BASE

The base URL of the repository (e.g. your BitBucket host). This variable is set by the OpenShift template from which the DeploymentConfig is created 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 OpenShift template from which the DeploymentConfig is created and usually does not need to be modified.

Development

See the Makefile targets.