Improve documentation around variable behaviour and gotchas

We used to link from the docs directory's README.md to our variables.md doc
but variables.md doesn't really explain the way variables work - it just
describes what values they can be used for and where they can be used in
our CRDs.

This commit changes the docs directory's README.md to point at the variable
documentation in our task doc, and adds a few lines there to talk a bit
more about how the substitution happens.

This commit also describes how to safely inject variables into `bash`
`script` blocks in Tasks without accidentally eval'ing the variable
contents.

docs/README.md

@@ -71,7 +71,7 @@ See the following topics to learn how to use Tekton Pipelines in your project:
 - [Using labels](labels.md)
 - [Viewing logs](logs.md)
 - [Pipelines metrics](metrics.md)
-- [Variable Substitutions](variables.md)
+- [Variable Substitutions](tasks.md#using-variable-substitution)
 - [Running a Custom Task (alpha)](runs.md)
 
 ## Contributing to Tekton Pipelines

docs/pipelines.md

@@ -19,6 +19,7 @@ weight: 3
     - [Guard `Task` execution using `When Expressions`](#guard-task-execution-using-whenexpressions)
     - [Guard `Task` execution using `Conditions`](#guard-task-execution-using-conditions)
     - [Configuring the failure timeout](#configuring-the-failure-timeout)
+  - [Using variable substitution](#using-variable-substitution)
   - [Using `Results`](#using-results)
     - [Passing one Task's `Results` into the `Parameters` of another](#passing-one-tasks-results-into-the-parameters-of-another)
     - [Emitting `Results` from a `Pipeline`](#emitting-results-from-a-pipeline)
@@ -514,6 +515,19 @@ spec:
       timeout: "0h1m30s"
 ```
 
+## Using variable substitution
+
+Tekton provides variables to inject values into the contents of certain fields.
+The values you can inject come from a range of sources including other fields
+in the Pipeline, context-sensitive information that Tekton provides, and runtime
+information received from a PipelineRun.
+
+The mechanism of variable substitution is quite simple - string replacement is
+performed by the Tekton Controller when a PipelineRun is executed.
+
+See the [complete list of variable substitutions for Pipelines](./variables.md#variables-available-in-a-pipeline)
+and the [list of fields that accept substitutions](./variables.md#fields-that-accept-variable-substitutions).
+
 ## Using `Results`
 
 Tasks can emit [`Results`](tasks.md#emitting-results) when they execute. A Pipeline can use these

docs/tasks.md

@@ -26,6 +26,7 @@ weight: 1
     - [Substituting `Array` parameters](#substituting-array-parameters)
     - [Substituting `Workspace` paths](#substituting-workspace-paths)
     - [Substituting `Volume` names and types](#substituting-volume-names-and-types)
+    - [Substituting in `Script` blocks](#substituting-in-script-blocks)
 - [Code examples](#code-examples)
   - [Building and pushing a Docker image](#building-and-pushing-a-docker-image)
   - [Mounting multiple `Volumes`](#mounting-multiple-volumes)
@@ -581,14 +582,23 @@ The `description` field is an optional field that allows you to add an informati
 
 ### Using variable substitution
 
+Tekton provides variables to inject values into the contents of certain fields.
+The values you can inject come from a range of sources including other fields
+in the Task, context-sensitive information that Tekton provides, and runtime
+information received from a TaskRun.
+
+The mechanism of variable substitution is quite simple - string replacement is
+performed by the Tekton Controller when a TaskRun is executed.
+
 `Tasks` allow you to substitute variable names for the following entities:
 
 - [Parameters and resources](#substituting-parameters-and-resources)
 - [`Array` parameters](#substituting-array-parameters)
 - [`Workspaces`](#substituting-workspace-paths)
 - [`Volume` names and types](#substituting-volume-names-and-paths)
 
-Also see the [complete list of variable substitutions for Tasks](./variables.md#variables-available-in-a-task).
+See the [complete list of variable substitutions for Tasks](./variables.md#variables-available-in-a-task)
+and the [list of fields that accept substitutions](./variables.md#fields-that-accept-variable-substitutions).
 
 #### Substituting parameters and resources
 
@@ -666,6 +676,34 @@ by parameterizing them. Tekton supports popular `Volume` types such as `ConfigMa
 See this [example](#mounting-a-configmap-as-a-volume-source) to find out how to perform this type of substitution
 in your `Task.`
 
+#### Substituting in `Script` blocks
+
+Variables can contain any string, including snippets of script that can
+be injected into a Task's `Script` field. If you are using Tekton's variables
+in your Task's `Script` field be aware that the strings you're interpolating
+could include executable instructions.
+
+Preventing a substituted variable from executing as code depends on the container
+image, language or shell that your Task uses. Here's an example of interpolating
+a Tekton variable into a `bash` `Script` block that prevents the variable's string
+contents from being executed:
+
+```yaml
+# Task.yaml
+spec:
+  steps:
+  - image: an-image-that-runs-bash
+    env:
+    - name: SCRIPT_CONTENTS
+      value: $(params.script)
+    script: |
+      printf '%s' "${SCRIPT_CONTENTS}" > input-script
+```
+
+This works by injecting Tekton's variable as an environment variable into the Step's
+container. The `printf` program is then used to write the environment variable's
+content to a file.
+
 ## Code examples
 
 Study the following code examples to better understand how to configure your `Tasks`:

docs/variables.md

@@ -7,6 +7,9 @@ weight: 15
 # Variable Substitutions Supported by `Tasks` and `Pipelines`
 
 This page documents the variable substitutions supported by `Tasks` and `Pipelines`.
+
+For instructions on using variable substitutions see the relevant section of [the Tasks doc](tasks.md#using-variable-substitution).
+
 **Note:** Tekton does not escape the contents of variables. Task authors are responsible for properly escaping a variable's value according to the shell, image or scripting language that the variable will be used in.
 
 ## Variables available in a `Pipeline`