Merge pull request openshift#13261 from bmcelvee/osdocs-83-triggering…

…-modifying-builds

OSDOCS-83 triggering and modifying builds

_topic_map.yml

@@ -41,6 +41,8 @@ Topics:
   File: build-strategies
 - Name: Performing basic builds
   File: basic-build-operations
+- Name: Triggering and modifying builds 
+  File: triggering-builds-build-hooks
 ---
 Name: OpenShift CCS modular docs guide
 Dir: mod_docs_guide

builds/triggering-builds-build-hooks.adoc

@@ -0,0 +1,39 @@
+// This assembly is included in the following assemblies:
+// * assembly/builds
+
+[id='triggering-builds-build-hooks']
+= Triggering and modifying builds
+include::modules/common-attributes.adoc[]
+:context: triggering-builds-build-hooks
+toc::[]
+
+The following sections outline how to trigger builds and modify builds using
+build hooks.
+
+// The following include statements pull in the module files that comprise the assembly. Include any combination of concept, procedure, or reference modules required to cover the user story. You can also include other assemblies.
+
+include::modules/builds-triggers.adoc[leveloffset=+1]
+
+include::modules/builds-webhook-triggers.adoc[leveloffset=+2]
+
+include::modules/builds-using-github-webhooks.adoc[leveloffset=+3]
+
+include::modules/builds-using-gitlab-webhooks.adoc[leveloffset=+3]
+
+include::modules/builds-using-bitbucket-webhooks.adoc[leveloffset=+3]
+
+include::modules/builds-using-generic-webhooks.adoc[leveloffset=+3]
+
+include::modules/builds-displaying-webhook-urls.adoc[leveloffset=+3]
+
+include::modules/builds-using-image-change-triggers.adoc[leveloffset=+2]
+
+include::modules/builds-configuration-change-triggers.adoc[leveloffset=+2]
+
+include::modules/builds-setting-triggers-manually.adoc[leveloffset=+3]
+
+include::modules/builds-build-hooks.adoc[leveloffset=+1]
+
+include::modules/builds-configuring-post-commit-build-hooks.adoc[leveloffset=+2]
+
+include::modules/builds-using-cli-post-commit-build-hooks.adoc[leveloffset=+2]

modules/builds-build-hooks.adoc

@@ -0,0 +1,36 @@
+// Module included in the following assemblies:
+//
+// * assembly/builds
+
+[id='builds-build-hooks-{context}']
+= Build hooks
+
+Build hooks allow behavior to be injected into the build process.
+
+The `postCommit` field of a `BuildConfig` object executes commands inside a
+temporary container that is running the build output image. The hook is executed
+immediately after the last layer of the image has been committed and before the
+image is pushed to a registry.
+
+The current working directory is set to the image's `WORKDIR`, which is the
+default working directory of the container image. For most images, this is where
+the source code is located.
+
+The hook fails if the script or command returns a non-zero exit code or if
+starting the temporary container fails. When the hook fails it marks the build
+as failed and the image is not pushed to a registry. The reason for failing can
+be inspected by looking at the build logs.
+
+Build hooks can be used to run unit tests to verify the image before the build
+is marked complete and the image is made available in a registry. If all tests
+pass and the test runner returns with exit code 0, the build is marked
+successful. In case of any test failure, the build is marked as failed. In all
+cases, the build log will contain the output of the test runner, which can be
+used to identify failed tests.
+
+The `postCommit` hook is not only limited to running tests, but can be used
+for other commands as well. Since it runs in a temporary container, changes made
+by the hook do not persist, meaning that the hook execution cannot affect the
+final image. This behavior allows for, among other uses, the installation and
+usage of test dependencies that are automatically discarded and will be not
+present in the final image.

modules/builds-configuration-change-triggers.adoc

@@ -0,0 +1,23 @@
+// Module included in the following assemblies:
+//
+// * assembly/builds
+
+[id='builds-configuration-change-triggers-{context}']
+= Configuration change triggers
+
+A configuration change trigger allows a build to be automatically invoked as
+soon as a new `BuildConfig` is created.
+
+The following is an example trigger definition YAML within the `BuildConfig`:
+
+[source,yaml]
+----
+  type: "ConfigChange"
+----
+
+[NOTE]
+====
+Configuration change triggers currently only work when creating a new
+`BuildConfig`. In a future release, configuration change triggers will also be
+able to launch a build whenever a `BuildConfig` is updated.
+====

modules/builds-configuring-post-commit-build-hooks.adoc

@@ -0,0 +1,86 @@
+// Module included in the following assemblies:
+//
+// * assembly/builds
+
+[id='builds-configuring-post-commit-build-hooks-{context}']
+= Configuring post commit build hooks
+
+There are different ways to configure the post build hook. All forms in the
+following examples are equivalent and execute `bundle exec rake test --verbose`.
+
+.Procedure
+
+* Shell script:
++
+[source,yaml]
+----
+postCommit:
+  script: "bundle exec rake test --verbose"
+----
++
+The `script` value is a shell script to be run with `/bin/sh -ic`. Use
+this when a shell script is appropriate to execute the build hook. For example,
+for running unit tests as above. To control the image entry point,
+or if the image does not have `/bin/sh`, use `command` and/or `args`.
++
+[NOTE]
+====
+The additional `-i` flag was introduced to improve the experience
+working with CentOS and RHEL images, and may be removed in a future release.
+====
+
+* Command as the image entry point:
++
+[source,yaml]
+----
+postCommit:
+  command: ["/bin/bash", "-c", "bundle exec rake test --verbose"]
+----
++
+In this form, `command` is the command to run, which overrides the image
+entry point in the exec form, as documented in the
+link:https://docs.docker.com/engine/reference/builder/#entrypoint[Dockerfile reference]. This is needed if the image does not have `/bin/sh`, or if
+you do not want to use a shell. In all other cases, using `script` might be
+more convenient.
+
+* Pass arguments to the default entry point:
++
+[source,yaml]
+----
+postCommit:
+  args: ["bundle", "exec", "rake", "test", "--verbose"]
+----
++
+In this form, `args` is a list of arguments that are provided to the default
+entry point of the image. The image entry point must be able to handle
+arguments.
+
+* Shell script with arguments:
++
+[source,yaml]
+----
+postCommit:
+  script: "bundle exec rake test $1"
+  args: ["--verbose"]
+----
++
+Use this form if you need to pass arguments that would otherwise be hard
+to quote properly in the shell script. In the `script`, `$0` will be "/bin/sh"
+and `$1`, `$2`, etc, are the positional arguments from `args`.
+
+* Command with arguments:
++
+[source,yaml]
+----
+postCommit:
+  command: ["bundle", "exec", "rake", "test"]
+  args: ["--verbose"]
+----
++
+This form is equivalent to appending the arguments to `command`.
+
+[NOTE]
+====
+Providing both `script` and `command` simultaneously creates an invalid
+build hook.
+====

modules/builds-displaying-webhook-urls.adoc

@@ -0,0 +1,19 @@
+// Module included in the following assemblies:
+//
+// * assembly/builds
+
+[id='builds-displaying-webhook-urls-{context}']
+= Displaying webhook URLs
+
+You can use the following command to display webhook URLs associated with a
+`BuildConfig`. If the command does not display any webhook URLs, then no webhook
+trigger is defined for that build configuration. See Setting Triggers to
+manually add triggers.
+
+.Procedure
+
+* To display any webhook URLs associated with a `BuildConfig`
+
+----
+$ oc describe bc <name>
+----

modules/builds-setting-triggers-manually.adoc

@@ -0,0 +1,38 @@
+// Module included in the following assemblies:
+//
+// * assembly/builds
+
+[id='builds-setting-triggers-manually-{context}']
+= Setting triggers manually
+
+Triggers can be added to and removed from build configurations with `oc set
+triggers`.
+
+.Procedure
+
+* To set a GitHub webhook trigger on a build configuration, use:
++
+----
+$ oc set triggers bc <name> --from-github
+----
+
+* To set an imagechange trigger, use
++
+----
+$ oc set triggers bc <name> --from-image='<image>'
+----
+
+* To remove a trigger, add `--remove`:
++
+----
+$ oc set triggers bc <name> --from-bitbucket --remove
+----
+
+[NOTE]
+====
+When a webhook trigger already exists, adding it again regenerates the
+webhook secret.
+====
+
+For more information, consult the help documentation with `oc set triggers
+--help`

modules/builds-triggers.adoc

@@ -0,0 +1,14 @@
+// Module included in the following assemblies:
+//
+// * assembly/builds
+
+[id='builds-triggers-{context}']
+= Build triggers
+
+When defining a `BuildConfig`, you can define triggers to control the
+circumstances in which the `BuildConfig` should be run. The following build
+triggers are available:
+
+* Webhook
+* Image change
+* Configuration change

modules/builds-using-bitbucket-webhooks.adoc

@@ -0,0 +1,58 @@
+// Module included in the following assemblies:
+//
+// * assembly/builds
+
+[id='builds-using-bitbucket-webhooks-{context}']
+= Using Bitbucket webhooks
+
+link:https://confluence.atlassian.com/bitbucket/manage-webhooks-735643732.html[Bitbucket
+webhooks] handle the call made by Bitbucket when a repository is updated.
+Similar to the previous triggers, you must specify a `secret`. The following
+example is a trigger definition YAML within the `BuildConfig`:
+
+[source,yaml]
+----
+type: "Bitbucket"
+bitbucket:
+  secretReference:
+    name: "mysecret"
+----
+
+The payload URL is returned as the Bitbucket 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>/bitbucket
+----
+
+.Procedure
+
+. To configure a Bitbucket Webhook:
+
+.. Describe the 'BuildConfig' to get the webhook URL:
++
+----
+$ oc describe bc <name>
+----
+
+.. Copy the webhook URL, replacing `<secret>` with your secret value.
+
+.. Follow the
+link:https://confluence.atlassian.com/bitbucket/manage-webhooks-735643732.html[Bitbucket
+setup instructions] to paste the webhook URL into your Bitbucket repository
+settings.
+
+. Given a file containing a valid JSON payload, such as `payload.json`, you can
+manually trigger the webhook with `curl`:
++
+----
+$ curl -H "X-Event-Key: repo: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>/bitbucket
+----
++
+The `-k` argument is only necessary if your API server does not have a properly
+signed certificate.
+
+.Additional resources
+
+* link:https://confluence.atlassian.com/bitbucket/manage-webhooks-735643732.html[Bitbucket]

modules/builds-using-cli-post-commit-build-hooks.adoc

@@ -0,0 +1,26 @@
+// Module included in the following assemblies:
+//
+// * assembly/builds
+
+[id='builds-using-cli-post-commit-build-hooks-{context}']
+= Using the CLI to set post commit build hooks
+
+The `oc set build-hook` command can be used to set the build hook for a build
+configuration.
+
+.Procedure
+
+. To set a command as the post-commit build hook:
++
+----
+$ oc set build-hook bc/mybc \
+    --post-commit \
+    --command \
+    -- bundle exec rake test --verbose
+----
++
+. To set a script as the post-commit build hook:
++
+----
+$ oc set build-hook bc/mybc --post-commit --script="bundle exec rake test --verbose"
+----