Trigger API Documentation

Author: otaviof

docs/build.md

@@ -602,6 +602,103 @@ spec:
         name: test-config
 ```
 
+### Defining Triggers
+
+Using the [triggers](https://github.com/shipwright-io/triggers) application you can issue `BuildRun` instances when certain events happen. The idea is to be able to trigger Shipwright builds in a event driven fashion, for that purpose you can watch certain types of events.
+
+The types of events under watch are defined on the `.spec.trigger` attribute, please consider the following example:
+
+```yaml
+apiVersion: shipwright.io/v1alpha1
+kind: Build
+spec:
+  source:
+    url: https://github.com/shipwright-io/sample-go
+    contextDir: docker-build
+    credentials:
+      name: webhook-secret
+  trigger:
+    when: []
+```
+
+Certain types of events will use attributes defined on `.spec.source` to complete the information needed in order to dispatch events.
+
+#### GitHub
+
+The GitHub type is meant to react on events coming from GitHub WebHook, the events are compared against the existing `Build` resources and therefore it can find `Build` based on `.spec.source.url` combined with the attributes on `.spec.trigger.when[].github`.
+
+When `.spec.trigger.when[].github.branches` is empty, the `.spec.source.revision` is employed, the default "branch" name employed is based on the regular source repository configuration.
+
+The folowing snippet shows a configuration machting `Push` and `PullRequest` events on the `main` branch, for example:
+
+```yaml
+# [...]
+spec:
+  source:
+    url: https://github.com/shipwright-io/sample-go
+  trigger:
+    when:
+      - name: push and pull-request on the main branch
+        type: GitHub
+        github:
+          events:
+            - Push
+            - PullRequest
+          branches:
+            - main
+```
+
+#### Image
+
+In order to watch over images, in combination with the [Image](https://github.com/shipwright-io/image) controller, you can trigger new builds when those container image names change.
+
+For instance, lets imagine the image named `ghcr.io/some/base-image` is used as input for the Build process and every time it changes we would like to trigger a new build. Please consider the following snippet:
+
+```yaml
+# [...]
+spec:
+  trigger:
+    when:
+      - name: watching for the base-image changes
+        type: Image
+        image:
+          names:
+            - ghcr.io/some/base-image:latest
+```
+
+#### Tekton Pipeline
+
+Shipwright can also be used in combination with [Tekton Pipeline](https://github.com/tektoncd/pipeline), you can configure the Build to watch for `Pipeline` resources in Kubernetes reacting when the object reaches the desired status (`.objectRef.status`), and is identified either by its name (`.objectRef.name`) or a label selector (`.objectRef.selector`). The example below uses the label selector approach:
+
+```yaml
+# [...]
+spec:
+  trigger:
+    when:
+      - name: watching over for the Tekton Pipeline
+        type: Pipeline
+        objectRef:
+          status:
+            - Succeeded
+          selector:
+            label: value
+```
+
+While the next snippet uses the object name for identification:
+
+```yaml
+# [...]
+spec:
+  trigger:
+    when:
+      - name: watching over for the Tekton Pipeline
+        type: Pipeline
+        objectRef:
+          status:
+            - Succeeded
+          name: tekton-pipeline-name
+```
+
 ### Sources
 
 Sources represent remote artifacts, as in external entities added to the build context before the actual Build starts. Therefore, you may employ `.spec.sources` to download artifacts from external repositories.