> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Build Triggers
> Explains OpenShift build triggers and webhooks to automate builds and deployments from GitHub GitLab or generic repositories with setup steps and best practices
Hello and welcome to this lesson.
We are learning [OpenShift 3 for the Absolute Beginners](https://learn.kodekloud.com/user/courses/openshift-3-for-the-absolute-beginners).
In this lesson we’ll examine build triggers in detail and show how to automate builds so code pushes result in new container images and (optionally) automatic redeploys.
Why automated builds?
* Manual builds work, but they are not continuous integration. Automated builds let OpenShift react to source changes and produce updated container images and deployments without manual intervention.
* When the repository receives a change (push, merge, or a specific event), it can notify OpenShift. OpenShift then pulls the updated source, runs the build defined in the BuildConfig, produces a new image, and—if configured—triggers a rollout so users see the updated application.
So how does the code repository notify OpenShift?
This is done using webhooks.
A webhook is an HTTP POST sent to a predefined URL when a specific event occurs (for example, a push to a branch). Most repository hosts — [GitHub](https://github.com), [GitLab](https://gitlab.com), and [Bitbucket](https://bitbucket.org) — provide webhook support. When OpenShift receives the webhook event it can automatically trigger the BuildConfig associated with your application.
Quick steps to connect your repository to an OpenShift BuildConfig
1. In the OpenShift web console, open the BuildConfig for your application.
2. Under the Configuration tab locate the Webhooks section. OpenShift exposes provider-specific webhook URLs (GitHub, GitLab, Generic).
3. Copy the webhook URL for the provider you use (for GitHub choose the GitHub webhook URL).
4. In your repository host (for example GitHub → Settings → Webhooks) create a new webhook and paste the BuildConfig webhook URL into the Payload URL field.
5. Set the content type (commonly `application/json`) and, if desired, add a secret token to protect against unauthorized requests.
6. Save the webhook. Now pushes (or configured events) will POST to OpenShift and trigger builds according to the BuildConfig triggers.
Once the webhook is configured, every matching push or event can start an automated build and, if your deployment watches images, redeploy the updated application automatically.
BuildConfig trigger types — at a glance
| Trigger Type | What it does | Where to configure |
| - | - | - |
| GitHub webhook | Triggers a build when GitHub sends a push/event to the GitHub-specific webhook URL | BuildConfig Webhooks (GitHub) + GitHub repo Settings → Webhooks |
| GitLab webhook | Triggers a build when GitLab sends a push/event to the GitLab webhook URL | BuildConfig Webhooks (GitLab) + GitLab repo Settings → Webhooks |
| Generic webhook | A provider-agnostic webhook you can use with any service that can POST to a URL | BuildConfig Webhooks (Generic) + repo/control plane that can POST |
| Image change trigger | Triggers a deployment when a referenced image stream tag is updated with a new image | BuildConfig / DeploymentConfig → imageChange triggers |
Operational details and best practices
* Network accessibility: The webhook endpoint (OpenShift route) must be reachable from the repository host. If your OpenShift cluster is in a private network, public hosts (like github.com) cannot reach it. Use a public route, proxy, or tunneling tool (e.g., `ngrok`) for testing, or host the repository inside the same network.
* Use secret tokens: Configure the secret token both in the BuildConfig webhook and in the repository webhook settings to validate incoming requests and prevent unauthorized triggers.
* Filter events and branches: Configure the repository-side webhook to trigger only on the events and branches you want (for example, pushes to `main` or merge events).
* Multiple triggers: BuildConfigs support multiple triggers (GitHub/GitLab/generic webhooks and image-change). Use the trigger type that best fits your CI/CD flow.
Make sure to copy the webhook URL for the correct provider (GitHub vs GitLab vs Generic) from the BuildConfig. If you configure a secret token in the BuildConfig, add the same secret to the repository webhook settings to ensure valid requests.
If your webhook POSTs fail with HTTP connection errors, confirm network routing and firewall rules between the repository host and the OpenShift route. Consider using a public route, a reverse proxy, or a tunneling service for testing.
Quick checklist before enabling automated builds
| Step | Check |
| - | - |
| Webhook URL copied | Confirm provider-specific URL copied from BuildConfig |
| Secret token set | Add same token to the repository webhook configuration |
| Content type | Set to `application/json` (or matching BuildConfig expectation) |
| Network reachable | Ensure repository host can reach OpenShift endpoint |
| Branch/event filters | Limit triggers to desired branches/events to avoid unnecessary builds |
References and further reading
* [OpenShift Builds and BuildConfig](https://docs.openshift.com/container-platform/latest/builds/understanding-builds.html)
* [GitHub Webhooks Documentation](https://docs.github.com/en/developers/webhooks-and-events/webhooks)
* [GitLab Webhooks Documentation](https://docs.gitlab.com/ee/user/project/integrations/webhooks.html)
* [Using ngrok for local webhook testing](https://ngrok.com/docs)
We will next walk through setting up a basic webhook using a locally hosted [GitLab](https://gitlab.com) instance to avoid public network accessibility issues.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.