pipeline level finally - implementation

We can now specify a list of tasks needs to be executed just before
pipeline exits (either after finishing all non-final tasks successfully or after
a single failure)

Most useful for tasks such as report test results, cleanup cluster resources, etc

```
apiVersion: tekton.dev/v1beta1
kind: Pipeline
metadata:
  name: pipeline-with-final-tasks
spec:
  tasks:
    - name: pre-work
      taskRef:
        Name: some-pre-work
    - name: unit-test
      taskRef:
        Name: run-unit-test
      runAfter:
        - pre-work
    - name: integration-test
      taskRef:
        Name: run-integration-test
      runAfter:
        - unit-test
  finally:
    - name: cleanup-test
      taskRef:
        Name: cleanup-cluster
    - name: report-results
      taskRef:
        Name: report-test-results
```

docs/pipelines.md

@@ -21,6 +21,7 @@ weight: 3
   - [Configuring execution results at the `Pipeline` level](#configuring-execution-results-at-the-pipeline-level)
   - [Configuring the `Task` execution order](#configuring-the-task-execution-order)
   - [Adding a description](#adding-a-description)
+  - [Adding `Finally` to the `Pipeline`](#adding-finally-to-the-pipeline)
   - [Code examples](#code-examples)
 
 ## Overview
@@ -528,6 +529,198 @@ In particular:
 
 The `description` field is an optional field and can be used to provide description of the `Pipeline`.
 
+## Adding `Finally` to the `Pipeline`
+
+You can specify a list of one or more final tasks under `finally` section. Final tasks are guaranteed to be executed
+in parallel after all `PipelineTasks` under `tasks` have completed regardless of success or error. Final tasks are very
+similar to `PipelineTasks` under `tasks` section and follow the same syntax. Each final task must have a
+[valid](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names) `name` and a [taskRef or
+taskSpec](taskruns.md#specifying-the-target-task). For example:
+
+```yaml
+spec:
+  tasks:
+    - name: tests
+      taskRef:
+        Name: integration-test
+  finally:
+    - name: cleanup-test
+      taskRef:
+        Name: cleanup
+```
+
+### Specifying `Workspaces` in Final Tasks
+
+Finally tasks may want to use [workspaces](workspaces.md) which `PipelineTasks` might have utilized
+e.g. a mount point for credentials held in Secrets. To support that requirement, you can specify one or more
+`Workspaces` in the `workspaces` field for the final tasks similar to `tasks`.
+
+```yaml
+spec:
+  resources:
+    - name: app-git
+      type: git
+  workspaces:
+    - name: shared-workspace
+  tasks:
+    - name: clone-app-source
+      taskRef:
+        name: clone-app-repo-to-workspace
+      workspaces:
+        - name: shared-workspace
+          workspace: shared-workspace
+      resources:
+        inputs:
+          - name: app-git
+            resource: app-git
+  finally:
+    - name: cleanup-workspace
+      taskRef:
+        name: cleanup-workspace
+      workspaces:
+        - name: shared-workspace
+          workspace: shared-workspace
+```
+
+### Specifying `Parameters` in Final Tasks
+
+Again, similar to `tasks`, you can specify [`Parameters`](tasks.md#specifying-parameters):
+
+```yaml
+spec:
+  tasks:
+    - name: tests
+      taskRef:
+        Name: integration-test
+  finally:
+    - name: report-results
+      taskRef:
+        Name: report-results
+      params:
+        - name: url
+          value: "someURL"
+```
+
+### `PipelineRun` Status with `finally`
+
+With `finally`, `PipelineRun` status is calculated based on `PipelineTasks` under `tasks` section and final tasks.
+
+Without `finally`:
+
+| `PipelineTasks` under `tasks` | `PipelineRun` status | Reason |
+| ----------------------------- | -------------------- | ------ |
+| all `PipelineTasks` successful | `true` | `Succeeded` |
+| one or more `PipelineTasks` skipped and rest successful | `true` | `Completed` |
+| single failure of `PipelineTask` | `false` | `failed` |
+
+With `finally`:
+
+| `PipelineTasks` under `tasks` | Final Tasks | `PipelineRun` status | Reason |
+| ----------------------------- | ----------- | -------------------- | ------ |
+| all `PipelineTask` successful | all final tasks successful | `true` | `Succeeded` |
+| all `PipelineTask` successful | one or more failure of final tasks | `false` | `Failed` |
+| one or more `PipelineTask` skipped and rest successful | all final tasks successful | `true` | `Completed` |
+| one or more `PipelineTask` skipped and rest successful | one or more failure of final tasks | `false` | `Failed` |
+| single failure of `PipelineTask` | all final tasks successful | `false` | `failed` |
+| single failure of `PipelineTask` | one or more failure of final tasks | `false` | `failed` |
+
+### Known Limitations
+
+### Specifying `Resources` in Final Tasks
+
+Similar to `tasks`, you can use [PipelineResources](#specifying-resources) as inputs and outputs for
+final tasks in the Pipeline. The only difference here is, final tasks with an input resource can not have a `from` clause
+like a `PipelineTask` from `tasks` section. For example:
+
+```yaml
+spec:
+  tasks:
+    - name: tests
+      taskRef:
+        Name: integration-test
+      resources:
+        inputs:
+          - name: source
+            resource: tektoncd-pipeline-repo
+        outputs:
+          - name: workspace
+            resource: my-repo
+  finally:
+    - name: clear-workspace
+      taskRef:
+        Name: clear-workspace
+      resources:
+        inputs:
+          - name: workspace
+            resource: my-repo
+            from: #invalid
+              - tests
+```
+
+### Cannot configure the Final Task execution order
+
+It's not possible to configure or modify the execution order of the final tasks. Unlike `Tasks` in a `Pipeline`,
+all final tasks run simultaneously and starts executing once all `PipelineTasks` under `tasks` have settled which means
+no `runAfter` can be specified in final tasks.
+
+### Cannot specify execution `Conditions` in Final Tasks
+
+`Tasks` in a `Pipeline` can be configured to run only if some conditions are satisfied using `conditions`. But the
+final tasks are guaranteed to be executed after all `PipelineTasks` therefore no `conditions` can be specified in
+final tasks.
+
+#### Cannot configure `Task` execution results with `finally`
+
+Final tasks can not be configured to consume `Results` of `PipelineTask` from `tasks` section i.e. the following
+example is not supported right now but we are working on adding support for the same (tracked in issue
+[#2557](https://github.com/tektoncd/pipeline/issues/2557)).
+
+```yaml
+spec:
+  tasks:
+    - name: count-comments-before
+      taskRef:
+        Name: count-comments
+    - name: add-comment
+      taskRef:
+        Name: add-comment
+    - name: count-comments-after
+      taskRef:
+        Name: count-comments
+  finally:
+    - name: check-count
+      taskRef:
+        Name: check-count
+      params:
+        - name: before-count
+          value: $(tasks.count-comments-before.results.count) #invalid
+        - name: after-count
+          value: $(tasks.count-comments-after.results.count) #invalid
+```
+
+#### Cannot configure `Pipeline` result with `finally`
+
+Final tasks can emit `Results` but results emitted from the final tasks can not be configured in the
+[Pipeline Results](#configuring-execution-results-at-the-pipeline-level). We are working on adding support for this
+(tracked in issue [#2710](https://github.com/tektoncd/pipeline/issues/2710)).
+
+```yaml
+  results:
+    - name: comment-count-validate
+      value: $(finally.check-count.results.comment-count-validate)
+```
+
+In this example, `PipelineResults` is set to:
+
+```
+"pipelineResults": [
+  {
+    "name": "comment-count-validate",
+    "value": "$(finally.check-count.results.comment-count-validate)"
+  }
+],
+```
+
 ## Code examples
 
 For a better understanding of `Pipelines`, study [our code examples](https://github.com/tektoncd/pipeline/tree/master/examples).

examples/v1beta1/pipelineruns/pipelinerun-with-final-tasks.yaml

@@ -0,0 +1,95 @@
+# Task to clone repo into shared workspace
+apiVersion: tekton.dev/v1beta1
+kind: Task
+metadata:
+  name: clone-app-repo-to-workspace
+spec:
+  workspaces:
+    - name: shared-workspace
+  resources:
+    inputs:
+      - name: app-git
+        type: git
+        targetPath: application
+  steps:
+    - name: clone-app-repo-to-workspace
+      image: ubuntu
+      script: |
+        #!/usr/bin/env bash
+        set -xe
+        cp -avr $(resources.inputs.app-git.path)/ $(workspaces.shared-workspace.path)/
+---
+
+# Task to cleanup shared workspace
+apiVersion: tekton.dev/v1beta1
+kind: Task
+metadata:
+  name: cleanup-workspace
+spec:
+  workspaces:
+    - name: shared-workspace
+  steps:
+    - name: cleanup-workspace
+      image: ubuntu
+      script: |
+        #!/usr/bin/env bash
+        set -xe
+        rm -rf $(workspaces.shared-workspace.path)/application/
+---
+
+# Pipeline to clone repo into shared workspace and cleanup the workspace after done
+apiVersion: tekton.dev/v1beta1
+kind: Pipeline
+metadata:
+  name: clone-into-workspace-and-cleanup-workspace
+spec:
+  resources:
+    - name: app-git
+      type: git
+  workspaces:
+    - name: shared-workspace
+  tasks:
+    - name: clone-app-source
+      taskRef:
+        name: clone-app-repo-to-workspace
+      workspaces:
+        - name: shared-workspace
+          workspace: shared-workspace
+      resources:
+        inputs:
+          - name: app-git
+            resource: app-git
+  finally:
+    - name: cleanup-workspace
+      taskRef:
+        name: cleanup-workspace
+      workspaces:
+        - name: shared-workspace
+          workspace: shared-workspace
+---
+
+# PipelineRun to execute pipeline - clone-into-workspace-and-cleanup-workspace
+apiVersion: tekton.dev/v1beta1
+kind: PipelineRun
+metadata:
+  name: write-and-cleanup-workspace
+spec:
+  pipelineRef:
+    name: clone-into-workspace-and-cleanup-workspace
+  workspaces:
+    - name: shared-workspace
+      volumeClaimTemplate:
+        spec:
+          accessModes:
+            - ReadWriteOnce
+          resources:
+            requests:
+              storage: 16Mi
+  resources:
+    - name: app-git
+      resourceSpec:
+        type: git
+        params:
+          - name: url
+            value: https://github.com/tektoncd/pipeline.git
+---

pkg/apis/pipeline/v1beta1/pipeline_types.go

@@ -71,6 +71,10 @@ type PipelineSpec struct {
 	// Results are values that this pipeline can output once run
 	// +optional
 	Results []PipelineResult `json:"results,omitempty"`
+	// Finally declares the list of Tasks that execute just before leaving the Pipeline
+	// i.e. either after all Tasks are finished executing successfully
+	// or after a failure which would result in ending the Pipeline
+	Finally []PipelineTask `json:"finally,omitempty"`
 }
 
 // PipelineResult used to describe the results of a pipeline