Skip to content

Enhance Webhooks Documentation for OpenShift #57

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: ocp-4.9
Choose a base branch
from
Open

Enhance Webhooks Documentation for OpenShift #57

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
133 changes: 59 additions & 74 deletions documentation/modules/ROOT/pages/nationalparks-java-codechanges-github.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,130 +1,115 @@
= Webhooks with OpenShift
:navtitle: Webhooks with OpenShift

As we discussed in the previous module, OpenShift provides the Source-2-Image mechanism to create containers by defining a `BuildConfig`. In addition to that, it provides link:https://docs.openshift.com/container-platform/{openshift-version}/cicd/builds/triggering-builds-build-hooks.html[triggers,window='_blank'] to control the circumstances in which the BuildConfig should be run, such as Webhooks.
OpenShift provides the Source-to-Image (S2I) mechanism to create containers by defining a BuildConfig. In addition, it offers link:https://docs.openshift.com/container-platform/{openshift-version}/cicd/builds/triggering-builds-build-hooks.html[triggers,window='_blank'] to control when the BuildConfig should run, such as Webhooks.

[#prerequisite_github_account]
== Prerequisite: GitHub Account
Webhooks allow automation of the build process by triggering builds when changes occur in the source repository. In this guide, you'll learn how to configure GitHub webhooks to automate build and deployment in OpenShift.

We will demonstrate the automation capability with OpenShift, and in order to do this, we need you to have an account on https://github.com[GitHub,window='_blank'].
== Prerequisite: GitHub Account

If you don't have an account on GitHub, please create one https://github.com/join[here,window='_blank'].
To follow along, you need an account on https://github.com[GitHub,window='_blank']. If you don't have one, create an account https://github.com/join[here,window='_blank'].

[#webhooks]
== Background: Webhooks

Most Git repository servers support the concept of web hooks -- calling to an
external source via HTTP(S) when a change in the code repository happens.
OpenShift provides an API endpoint that supports receiving hooks from
remote systems in order to trigger builds. By pointing the code repository's
hook at the OpenShift API, automated code/build/deploy can be
achieved.
Most Git repository platforms support webhooks—HTTP(S) callbacks triggered when changes occur in a repository. OpenShift provides an API endpoint that listens for webhook events, allowing automated build and deployment when changes are pushed to a repository.

[#webhooks_with_openshift]
== Exercise: Webhooks with OpenShift
In this lab you can use a build webhook to trigger a build execution every time there is a change in your copy of the nationalparks GitHub repository. In the OpenShift web console, navigate to your **%PROJECT%** project, and then click to **Builds**. Click the `nationalparks` BuildConfig and then go to the **Webhooks** section.

On this screen you will see the option to copy the GitHub webhook URL, click to **Copy URL with Secret** as shown in the following image:

image::nationalparks-codechanges-webhook-config.png[Webhook]
In this exercise, you'll set up a webhook that triggers a build when changes occur in your forked copy of the nationalparks GitHub repository.

. In the OpenShift web console, navigate to your %PROJECT% project.
. Click Builds and select nationalparks BuildConfig.
. Navigate to the Webhooks section.
. Copy the GitHub webhook URL by clicking Copy URL with Secret.

[#fork_repository_from_github]
== Exercise: Fork NationalParks repository from GitHub
image::nationalparks-codechanges-webhook-config.png[Webhook]

A link:https://docs.github.com/en/free-pro-team@latest/github/getting-started-with-github/fork-a-repo[fork,window='_blank'] is a copy of a repository. Forking a repository allows you to freely experiment with changes without affecting the original project.
== Exercise: Fork NationalParks Repository from GitHub

In this step we will fork the original `nationalparks` repository to apply our changes and automatically trigger the Pipeline through a link:https://docs.github.com/en/free-pro-team@latest/developers/webhooks-and-events/about-webhooks[GitHub Webhook,window='_blank'] that we're going to configure.
A link:https://docs.github.com/en/github/getting-started-with-github/fork-a-repo[fork,window='_blank'] is a copy of a repository. Forking allows you to make changes without affecting the original project.

Go to link:https://github.com/openshift-roadshow/nationalparks[Nationalparks,window='_blank'] repository. From top-right side, click to *Fork* to start forking it into your account.
. Open the link:https://github.com/openshift-roadshow/nationalparks[Nationalparks,window='_blank'] repository.
. Click Fork (top-right) to create a fork in your account.

image::nationalparks-codechanges-github-fork-1.png[Fork Repository]

Select your account, and click *Fork*
. Select your account and click Fork.

image::nationalparks-codechanges-github-fork-2.png[Fork in progress]

Your repository is forked now, we can start adding our automation to that.

[#configuring_github_webhooks]
== Exercise: Configuring GitHub Web Hooks
Your repository is now forked and ready for automation.

== Exercise: Configuring GitHub Webhooks

Once you have forked the repository and you have the Webhook URL with Secret copied to your clipboard, navigate to the code repository fork that you have on GitHub.

From your fork page top-right menu, click *Settings*. Then from result left-side menu, click *Webhook*, then from right side click *Add webhooks*.
. Go to your forked repository on GitHub.
. Click Settings (top-right menu).
. In the left-side menu, select Webhooks and click Add webhook.

image::nationalparks-codechanges-github-webhook-settings.png[Add Webhook]

In the next screen, paste your link into the "Payload URL" field. You can leave the
secret token field blank -- the secret is already in the URL and does not need
to be in the payload.

Change the `Content Type` to `application/json`.

Finally, click on *Add Webhook*.
. Paste the copied webhook URL into the "Payload URL" field.
. Set Content Type to application/json.
. Click Add Webhook.

image::nationalparks-codechanges-github-automation-webhook.png[Webhook]

Boom! From now on, every time you commit new source code to your GitHub
repository, a new build and deploy will occur inside of OpenShift. Let's try
this out.
Now, every commit to your GitHub repository will trigger a new build and deployment in OpenShift.

[#using_github_webhooks]
== Exercise: Using GitHub Web Hooks
Click the *Code* tab in GitHub. This is GitHub's repository view.
== Exercise: Using GitHub Webhooks

CAUTION: Make sure that the drop-down menu at the upper right is set for
the *`master`* branch. Navigate to the
following path:
. Click the Code tab in GitHub.
. Ensure the branch dropdown is set to master.
. Navigate to:

[.console-output]
[source,bash]
----

src/main/java/com/openshift/evg/roadshow/parks/rest/
----

Then click on the `BackendController.java` file.
. Click BackendController.java and edit the file.
. Change line 20:

Once you have the file on the screen, click the edit button in the top right
hand corner as shown here:
[source,java]

image::nationalparks-codechanges-github-change-code.png[Webhook]
return new Backend("nationalparks","National Parks", new Coordinates("47.039304", "14.505178"), 4);

Change line number 20:
to:

[source,java]
----
return new Backend("nationalparks","National Parks", new Coordinates("47.039304", "14.505178"), 4);
----

To

[source,java,role="copypaste"]
----
return new Backend("nationalparks","Awesome National Parks", new Coordinates("47.039304", "14.505178"), 4);
----

Click on *Commit changes* at the bottom of the screen. Feel free to enter a commit message.
. Click Commit changes and enter a commit message.

Once you have committed your changes, a new *Build* should almost instantaneously be
triggered in OpenShift. From OpenShift Web Console, click **Builds**->**nationalparks** and then navigate to the **Builds**. You should see a new one running:
Once committed, a new build should trigger in OpenShift. Verify in OpenShift Web Console:

. Click Builds -> nationalparks.
. Navigate to Builds and confirm a new one is running.

image::nationalparks-codechanges-build-running.png[Webhook]

or run the following command to verify:
Alternatively, check via CLI:

[.console-input]
[source,bash,subs="+attributes,macros+"]
----
oc get builds
----
[source,bash]

Once the build and deploy has finished, verify your new image was automatically deployed by viewing the application in your browser:
oc get builds

Once the build and deployment complete, verify the update by opening the application in your browser:

link:https://nationalparks-%PROJECT%.%CLUSTER_SUBDOMAIN%/ws/info/[National Parks Info Page,role='params-link',window='_blank']

You should now see the new name you have set in the JSON string returned.
You should see the updated name in the returned JSON response.

[NOTE]

To reflect the change in the map's legend, scale down your parksmap deployment to 0 and back up to 1 to refresh the cache.

== Webhook Testing Tools

If you need to test webhooks without setting up OpenShift, you can use webhook testing services like:

NOTE: To see this in the map's legend itself, you will need to scale down your parksmap to 0, then back up to 1 to force the app to refresh its cache.
[options="header"]
|===
| Tool | Description
| link:https://beeceptor.com/[Beeceptor] | A free tool to inspect and debug webhook requests in real time.
| link:https://webhook.site/[Webhook.site] | Captures and inspects HTTP requests to test webhook payloads.
|===