Add a short example of using optional workspaces in when expressions

We've just added support for optional workspaces but I forgot to include
an example showing how to use them as part of a When Expression.

This commit adds a PipelineRun example YAML showing use of a
workspaces.<name>.bound variable in a when expression.

I've also updated pipelines.md to mention that you
can use a when expression to evaluate whether an optional workspace was
bound or not and to provide a short example snippet of using the bound
variables in a when expression.

docs/pipelines.md

@@ -115,6 +115,7 @@ spec:
 For more information, see:
 - [Using `Workspaces` in `Pipelines`](workspaces.md#using-workspaces-in-pipelines)
 - The [`Workspaces` in a `PipelineRun`](../examples/v1beta1/pipelineruns/workspaces.yaml) code example
+- The [variables available in a `PipelineRun`](variables.md#variables-available-in-a-pipeline), including `workspaces.<name>.bound`.
 
 ## Specifying `Parameters`
 
@@ -324,13 +325,13 @@ To run a `Task` only when certain conditions are met, it is possible to _guard_
 The components of `WhenExpressions` are `Input`, `Operator` and `Values`:
 - `Input` is the input for the `WhenExpression` which can be static inputs or variables ([`Parameters`](#specifying-parameters) or [`Results`](#using-results)). If the `Input` is not provided, it defaults to an empty string.
 - `Operator` represents an `Input`'s relationship to a set of `Values`. A valid `Operator` must be provided, which can be either `in` or `notin`.
-- `Values` is an array of string values. The `Values` array must be provided and be non-empty. It can contain static values or variables ([`Parameters`](#specifying-parameters) or [`Results`](#using-results)).
+- `Values` is an array of string values. The `Values` array must be provided and be non-empty. It can contain static values or variables ([`Parameters`](#specifying-parameters), [`Results`](#using-results) or [a Workspaces's `bound` state](#specifying-workspaces)).
 
 The [`Parameters`](#specifying-parameters) are read from the `Pipeline` and [`Results`](#using-results) are read directly from previous [`Tasks`](#adding-tasks-to-the-pipeline). Using [`Results`](#using-results) in a `WhenExpression` in a guarded `Task` introduces a resource dependency on the previous `Task` that produced the `Result`. 
 
 The declared `WhenExpressions` are evaluated before the `Task` is run. If all the `WhenExpressions` evaluate to `True`, the `Task` is run. If any of the `WhenExpressions` evaluate to `False`, the `Task` is not run and the `Task` is listed in the [`Skipped Tasks` section of the `PipelineRunStatus`](pipelineruns.md#monitoring-execution-status). 
 
-In these examples, `first-create-file` task will only be executed if the `path` parameter is `README.md` and `echo-file-exists` task will only be executed if the `exists` result from `check-file` task is `yes`. 
+In these examples, `first-create-file` task will only be executed if the `path` parameter is `README.md`, `echo-file-exists` task will only be executed if the `exists` result from `check-file` task is `yes` and `run-lint` task will only be executed if the `lint-config` optional workspace has been provided by a PipelineRun. 
 
 ```yaml
 tasks:
@@ -350,6 +351,15 @@ tasks:
         values: ["yes"]
     taskRef:
         name: echo-file-exists
+---
+tasks:
+  - name: run-lint
+    when:
+      - input: "$(workspaces.lint-config.bound)"
+        operator: in
+        values: ["true"]
+    taskRef:
+      name: lint-source
 ```
 
 For an end-to-end example, see [PipelineRun with WhenExpressions](../examples/v1beta1/pipelineruns/pipelinerun-with-when-expressions.yaml).
@@ -362,6 +372,7 @@ There are a lot of scenarios where `WhenExpressions` can be really useful. Some
 - Checking if a git file has changed in the previous commits
 - Checking if an image exists in the registry
 - Checking if the name of a CI job matches
+- Checking if an optional Workspace has been provided
 
 ### Guard `Task` execution using `Conditions`
 

examples/v1beta1/pipelineruns/using-optional-workspaces-in-when-expressions.yaml

@@ -0,0 +1,66 @@
+# This example demonstrates using the workspaces.<name>.bound variable
+# in a when expression to selectively run different portions of a Pipeline
+# based on the presence of an optional workspace.
+#
+# In the PipelineRun below an optional message-of-the-day workspace is accepted
+# by the Pipeline. If that workspace is provided then the print-motd task is
+# executed. If that workspace is not provided then a print-default-motd task
+# is run instead. We supply a ConfigMap for the workspace and so the print-motd
+# task ends up running and printing the contents of each entry in the ConfigMap.
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: test-motd
+data:
+  message_1: "Hello, good morning!"
+  message_2: "Hello, good evening!"
+---
+apiVersion: tekton.dev/v1beta1
+kind: PipelineRun
+metadata:
+  generateName: optional-workspace-when-
+spec:
+  serviceAccountName: 'default'
+  workspaces:
+  - name: message-of-the-day
+    configMap:
+      name: test-motd
+  pipelineSpec:
+    workspaces:
+    - name: message-of-the-day
+      optional: true
+      description: |
+        If a workspace is provided here then every file at the root of the workspace
+        will be printed.
+    tasks:
+    - name: print-motd
+      when:
+      - input: "$(workspaces.message-of-the-day.bound)"
+        operator: in
+        values: ["true"]
+      workspaces:
+      - name: message-of-the-day
+        workspace: message-of-the-day
+      taskSpec:
+        workspaces:
+        - name: message-of-the-day
+        steps:
+        - image: alpine
+          script: |
+            #!/usr/bin/env ash
+            for f in "$(workspaces.message-of-the-day.path)"/* ; do
+              echo "Message from $f:"
+              cat "$f"
+              echo "" # add newline
+            done
+    - name: print-default-motd
+      when:
+      - input: "$(workspaces.message-of-the-day.bound)"
+        operator: in
+        values: ["false"]
+      taskSpec:
+        steps:
+        - name: print-default
+          image: alpine
+          script: |
+            echo "No message-of-the-day workspace was provided. This is the default MOTD instead!"