docs: PromotionTask reference and more (#3266)

Signed-off-by: Hidde Beydals <[email protected]>
akuity · Jan 14, 2025 · 09cb991 · 09cb991
1 parent 6a35538
commit 09cb991
Show file tree

Hide file tree

Showing 2 changed files with 368 additions and 0 deletions.
diff --git a/docs/docs/35-references/10-promotion-steps.md b/docs/docs/35-references/10-promotion-steps.md
@@ -42,6 +42,44 @@ steps:
   as: alias
 ```
 
+### Step Variables
+
+A step can define variables that can be referenced in its configuration by
+providing a `vars` key in the step definition. The value of the `vars` key is a
+list of variables, each of which is an object with `name` and `value` keys.
+
+```yaml
+steps:
+- uses: step-name
+  vars:
+  - name: var1
+    value: value1
+  - name: var2
+    value: value2
+  config:
+    option1: ${{ vars.var1 }}
+    option2: ${{ vars.var2 }}
+```
+
+Variables defined in a step are scoped to that step and are not accessible to
+other steps. The values of variables may contain [expressions](./20-expression-language.md).
+In addition, the values of step variables may be references to the
+[outputs](#step-outputs) of other steps.
+
+```yaml
+steps:
+- uses: step1
+  as: step1
+- uses: step2
+  vars:
+  - name: var1
+    value: ${{ outputs.step1.someOutput }}
+```
+
+When a variable in a step is also defined as a global variable in the
+[Promotion Template](../30-how-to-guides/14-working-with-stages.md#promotion-templates),
+the step variable takes precedence over the global variable.
+
 ### Step Outputs
 
 A promotion step may produce output that can be referenced by subsequent steps,
@@ -100,6 +138,23 @@ errors, and to provide more control over retry behavior like backoff strategies
 or time limits.
 :::
 
+### Promotion Task Step
+
+A step can be used to reference a
+[`PromotionTask` or `ClusterPromotionTask`](30-promotion-tasks.md)
+using the `task` key, whose value is an object with a `name` key that specifies
+the name of the task and optionally a `kind` key to specify if the task is a
+`ClusterPromotionTask`.
+
+```yaml
+steps:
+- task:
+    name: task-name
+    kind: ClusterPromotionTask
+```
+
+When a task is referenced, the `uses` key is not required.
+
 ## Built-in Steps
 
 This section describes the promotion steps that are built directly into Kargo.
@@ -1596,4 +1651,60 @@ steps:
 The `http` step only produces the outputs described by the `outputs` field of
 its configuration.
 
+### `compose-output`
+
+`compose-output` is a step that composes a new output from one or more existing
+outputs. This step can be useful when subsequent steps need to reference a
+combination of outputs from previous steps, or to allow a
+[`PromotionTask`](30-promotion-tasks.md) to provide easy access to outputs from
+the steps it contains.
+
+#### `compose-output` Configuration
+
+The `compose-output` step accepts an arbitrary set of key-value pairs, where the
+key is the name of the output to be created and the value is arbitrary and can
+be an [Expression Language](./20-expression-language.md) expression.
+
+#### `compose-output` Example
+
+```yaml
+vars:
+- name: repoURL
+  value: https://github.com/example/repo
+steps:
+- uses: git-open-pr
+  as: open-pr
+  config:
+    repoURL: ${{ vars.repoURL }}
+    createTargetBranch: true
+    sourceBranch: ${{ outputs.push.branch }}
+    targetBranch: stage/${{ ctx.stage }}
+- uses: compose-output
+  as: pr-link
+  config:
+    url: ${{ vars.repoURL }}/pull/${{ outputs['open-pr'].prNumber }}
+- uses: http
+  config:
+    method: POST
+    url: https://slack.com/api/chat.postMessage
+    headers:
+    - name: Authorization
+      value: Bearer ${{ secrets.slack.token }}
+    - name: Content-Type
+      value: application/json
+    body: |
+      ${{ quote({
+        "channel": "C123456",
+        "blocks": [
+          {
+            "type": "section",
+            "text": {
+              "type": "mrkdwn",
+              "text": "A new PR has been opened: ${{ outputs['pr-link'].url }}"
+            }
+          }
+        ]
+      }) }}
+```
+
 [expr-lang]: https://expr-lang.org/
diff --git a/docs/docs/35-references/30-promotion-tasks.md b/docs/docs/35-references/30-promotion-tasks.md
@@ -0,0 +1,257 @@
+---
+sidebar_label: Promotion Tasks Reference
+description: Learn about Kargo's promotion tasks that can define reusable promotion steps.
+---
+
+# Promotion Tasks Reference
+
+`PromotionTask`s allow you to define a set of
+[Promotion Steps](./10-promotion-steps.md) on a project or global
+(`ClusterPromotionTask`) level that can be reused across multiple
+[Promotion Templates](../30-how-to-guides/14-working-with-stages.md#promotion-templates).
+
+## Defining a Promotion Task
+
+A simple `PromotionTask` is defined as follows:
+
+```yaml
+apiVersion: kargo.akuity.io/v1alpha1
+kind: PromotionTask
+metadata:
+  name: open-pr-and-wait
+  namespace: kargo-demo
+spec:
+  vars:
+  - name: repoURL
+  - name: sourceBranch
+  - name: targetBranch
+  steps:
+  - uses: git-open-pr
+    as: open-pr
+    config:
+      repoURL: ${{ vars.repoURL }}
+      createTargetBranch: true
+      sourceBranch: ${{ vars.sourceBranch }}
+      targetBranch: ${{ vars.targetBranch }}
+  - uses: git-wait-for-pr
+    as: wait-for-pr
+    config:
+      repoURL: ${{ vars.repoURL }}
+      prNumber: ${{ task.outputs['open-pr'].prNumber }}
+  - uses: compose-output
+    as: output
+    config:
+      mergeCommit: ${{ task.outputs['wait-for-pr'].commit }}
+```
+
+### Promotion Task Variables
+
+The `spec.vars` section of a `PromotionTask` defines the input variables that
+it expects when it is used in a Promotion Template. Each variable requires a
+`name` and optionally a default `value`. When the `value` is not provided, the
+variable is considered required and must be provided when the `PromotionTask`
+is used in a Promotion Template.
+
+```yaml
+apiVersion: kargo.akuity.io/v1alpha1
+kind: PromotionTask
+# ...omitted for brevity
+spec:
+  vars:
+  # This variable is required
+  - name: repoURL
+  # This variable is optional and defaults to "main"
+  - name: targetBranch
+    value: main
+```
+
+Variables can be referenced in the `PromotionTask` steps' configuration using
+the `${{ vars.<variable-name> }}` syntax. For example, the `repoURL` variable
+is referenced as `${{ vars.repoURL }}`.
+
+```yaml
+apiVersion: kargo.akuity.io/v1alpha1
+kind: PromotionTask
+# ...omitted for brevity
+spec:
+  vars:
+  - name: repoURL
+  - name: sourceBranch
+  - name: targetBranch
+    value: main
+  steps:
+  - uses: git-open-pr
+    as: open-pr
+    config:
+      repoURL: ${{ vars.repoURL }}
+      createTargetBranch: true
+      sourceBranch: ${{ vars.sourceBranch }}
+      targetBranch: ${{ vars.targetBranch }}
+```
+
+When the `PromotionTask` is used in a Promotion Template, the input variables
+must be provided as `vars` of the step referencing the `PromotionTask`.
+
+```yaml
+apiVersion: kargo.akuity.io/v1alpha1
+kind: Stage
+# ...omitted for brevity
+spec:
+  promotionTemplate:
+    spec:
+      steps:
+      - task:
+          name: my-promotion-task
+          vars:
+          - name: repoURL
+            value: https://github.com/example/repository.git
+          - name: sourceBranch
+            value: feature-branch
+```
+
+When the Promotion Template defines a
+[`vars` section](../30-how-to-guides/14-working-with-stages.md#promotion-templates)
+the variables are inherited by the `PromotionTask` and do not require redefinition
+unless they need to be overridden.
+
+```yaml
+apiVersion: kargo.akuity.io/v1alpha1
+kind: Stage
+# ...omitted for brevity
+spec:
+  promotionTemplate:
+    spec:
+      vars:
+      - name: repoURL
+        value: https://github.com/example/repository.git
+      steps:
+        - task:
+            name: my-promotion-task
+            vars:
+            - name: sourceBranch
+              value: feature-branch
+```
+
+### Promotion Task Steps
+
+The `spec.steps` section of a `PromotionTask` define the sequence of steps that
+are inflated when a `Promotion` is created from a Promotion Template that
+references the task. Each step works the as a [regular step](10-promotion-steps.md)
+in a Promotion Template, except that references to other tasks are not allowed.
+
+#### Promotion Task Context
+
+The steps of a `PromotionTask` have access to an additional `task`
+[pre-defined variable](20-expression-language.md#pre-defined-variables) that
+provides access to the `outputs` of the previous steps. The `task.outputs`
+property is a map of step aliases to their outputs.
+
+```yaml
+apiVersion: kargo.akuity.io/v1alpha1
+kind: PromotionTask
+# ...omitted for brevity
+spec:
+  steps:
+  - uses: git-open-pr
+    as: open-pr
+    config:
+      repoURL: ${{ vars.repoURL }}
+      createTargetBranch: true
+      sourceBranch: ${{ vars.sourceBranch }}
+      targetBranch: ${{ vars.targetBranch }}
+  - uses: git-wait-for-pr
+    as: wait-for-pr
+    config:
+      repoURL: ${{ vars.repoURL }}
+      prNumber: ${{ task.outputs['open-pr'].prNumber }}
+```
+
+### Promotion Task Outputs
+
+Outputs of a `PromotionTask` can be made more accessible by defining them using
+a [`compose-output` step](10-promotion-steps.md#compose-output). The outputs are
+then made available under the alias defined in the
+[`as` field](10-promotion-steps.md#step-aliases) of the step referencing the
+`PromotionTask`.
+
+```yaml
+---
+apiVersion: kargo.akuity.io/v1alpha1
+kind: PromotionTask
+metadata:
+  name: open-pr-and-wait
+  namespace: kargo-demo
+spec:
+    # ...omitted for brevity
+    - uses: compose-output
+      as: output
+      config:
+        mergeCommit: ${{ task.outputs['wait-for-pr'].commit }}
+---
+apiVersion: kargo.akuity.io/v1alpha1
+kind: Stage
+# ...omitted for brevity
+spec:
+  promotionTemplate:
+    spec:
+      steps:
+      - task:
+          name: open-pr-and-wait
+          as: pr
+          # ...additional configuration
+      - uses: http
+        config:
+          method: POST
+          url: https://slack.com/api/chat.postMessage
+          headers:
+          - name: Authorization
+            value: Bearer ${{ secrets.slack.token }}
+          - name: Content-Type
+            value: application/json
+          body: |
+            ${{ quote({
+              "channel": "C123456",
+              "blocks": [
+                {
+                  "type": "section",
+                  "text": {
+                    "type": "mrkdwn",
+                    "text": "A new commit was merged: ${{ outputs.pr.mergeCommit }}"
+                  }
+                }
+              ]
+            }) }}
+```
+
+### Cluster Promotion Task
+
+A `ClusterPromotionTask` is a `PromotionTask` that is available to all
+[projects](../30-how-to-guides/11-working-with-projects.md)
+in the cluster. The `ClusterPromotionTask` is defined the same way as a
+`PromotionTask`, but without the `namespace` field in the metadata.
+
+```yaml
+apiVersion: kargo.akuity.io/v1alpha1
+kind: ClusterPromotionTask
+metadata:
+  name: open-pr-and-wait
+spec:
+  # ...equivalent to a PromotionTask
+```
+
+A `ClusterPromotionTask` can be used in a Promotion Template the same way as a
+`PromotionTask`, but requires the additional specification of the `kind` field
+in the step referencing the task.
+
+```yaml
+apiVersion: kargo.akuity.io/v1alpha1
+kind: Stage
+# ...omitted for brevity
+spec:
+  promotionTemplate:
+    spec:
+      steps:
+      - kind: ClusterPromotionTask
+        name: open-pr-and-wait
+      # ...additional configuration
+```