mirror of
https://github.com/openshift/openshift-docs.git
synced 2026-02-05 21:46:22 +01:00
99 lines
3.0 KiB
Plaintext
99 lines
3.0 KiB
Plaintext
// Module included in the following assemblies:
|
|
//
|
|
// * assembly/builds
|
|
|
|
[id="builds-using-github-webhooks_{context}"]
|
|
= Using GitHub webhooks
|
|
|
|
link:https://developer.github.com/webhooks/creating/[GitHub webhooks] handle the
|
|
call made by GitHub when a repository is updated. When defining the trigger, you
|
|
must specify a `secret`, which will be 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`
|
|
link:https://developer.github.com/webhooks/#delivery-headers[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:
|
|
|
|
----
|
|
http://<openshift_api_host:port>/oapi/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:
|
|
+
|
|
----
|
|
$ oc describe bc/<name-of-your-BuildConfig>
|
|
----
|
|
+
|
|
This generates a webhook GitHub URL that looks like:
|
|
+
|
|
----
|
|
<https://api.starter-us-east-1.openshift.com:443/oapi/v1/namespaces/nsname/buildconfigs/bcname/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 &
|
|
Services*.
|
|
|
|
.. Paste the URL output (similar to above) 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, whenever you push a change to your GitHub repository, a new build will
|
|
automatically start, and upon a successful build a new deployment will start.
|
|
+
|
|
[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`:
|
|
+
|
|
----
|
|
$ curl -H "X-GitHub-Event: push" -H "Content-Type: application/json" -k -X POST --data-binary @payload.json https://<openshift_api_host:port>/oapi/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.
|
|
|
|
.Additional resources
|
|
|
|
* link:https://developer.github.com/webhooks/[GitHub]
|
|
* link:https://gogs.io[Gogs]
|