mirror of
https://github.com/openshift/openshift-docs.git
synced 2026-02-05 12:46:18 +01:00
92 lines
3.1 KiB
Plaintext
92 lines
3.1 KiB
Plaintext
// Module included in the following assemblies:
|
|
//
|
|
// * builds/triggering-builds-build-hooks.adoc
|
|
|
|
:_content-type: PROCEDURE
|
|
[id="builds-using-github-webhooks_{context}"]
|
|
= Using GitHub webhooks
|
|
|
|
GitHub webhooks handle the call made by GitHub when a repository is updated. When defining the trigger, you must specify a secret, which is part of the URL you supply to GitHub when configuring the webhook.
|
|
|
|
Example GitHub webhook definition:
|
|
|
|
[source,yaml]
|
|
----
|
|
type: "GitHub"
|
|
github:
|
|
secretReference:
|
|
name: "mysecret"
|
|
----
|
|
|
|
[NOTE]
|
|
====
|
|
The secret used in the webhook trigger configuration is not the same as `secret` field you encounter when configuring webhook in GitHub UI. The former is to make the webhook URL unique and hard to predict, the latter is an optional string field used to create HMAC hex digest of the body, which is sent as an `X-Hub-Signature` header.
|
|
====
|
|
|
|
The payload URL is returned as the GitHub Webhook URL by the `oc describe`
|
|
command (see Displaying Webhook URLs), and is structured as follows:
|
|
|
|
.Example output
|
|
[source,terminal]
|
|
----
|
|
https://<openshift_api_host:port>/apis/build.openshift.io/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/github
|
|
----
|
|
|
|
.Prerequisites
|
|
|
|
* Create a `BuildConfig` from a GitHub repository.
|
|
|
|
.Procedure
|
|
|
|
. To configure a GitHub Webhook:
|
|
|
|
.. After creating a `BuildConfig` from a GitHub repository, run:
|
|
+
|
|
[source,terminal]
|
|
----
|
|
$ oc describe bc/<name-of-your-BuildConfig>
|
|
----
|
|
+
|
|
This generates a webhook GitHub URL that looks like:
|
|
+
|
|
.Example output
|
|
[source,terminal]
|
|
----
|
|
<https://api.starter-us-east-1.openshift.com:443/apis/build.openshift.io/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/github
|
|
----
|
|
|
|
.. Cut and paste this URL into GitHub, from the GitHub web console.
|
|
|
|
.. In your GitHub repository, select *Add Webhook* from *Settings -> Webhooks*.
|
|
|
|
.. Paste the URL output into the *Payload URL* field.
|
|
|
|
.. Change the *Content Type* from GitHub's default `application/x-www-form-urlencoded` to `application/json`.
|
|
|
|
.. Click *Add webhook*.
|
|
+
|
|
You should see a message from GitHub stating that your webhook was successfully configured.
|
|
+
|
|
Now, when you push a change to your GitHub repository, a new build automatically starts, and upon a successful build a new deployment starts.
|
|
+
|
|
[NOTE]
|
|
====
|
|
link:https://gogs.io[Gogs] supports the same webhook payload format as GitHub. Therefore, if you are using a Gogs server, you can define a GitHub webhook trigger on your `BuildConfig` and trigger it by your Gogs server as well.
|
|
====
|
|
|
|
. Given a file containing a valid JSON payload, such as `payload.json`, you can manually trigger the webhook with `curl`:
|
|
+
|
|
[source,terminal]
|
|
----
|
|
$ curl -H "X-GitHub-Event: push" -H "Content-Type: application/json" -k -X POST --data-binary @payload.json https://<openshift_api_host:port>/apis/build.openshift.io/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/github
|
|
----
|
|
+
|
|
The `-k` argument is only necessary if your API server does not have a properly
|
|
signed certificate.
|
|
|
|
[role="_additional-resources"]
|
|
.Additional resources
|
|
|
|
//* link:https://developer.github.com/webhooks/[GitHub]
|
|
* link:https://gogs.io[Gogs]
|