diff --git a/docs/docs/35-references/10-promotion-steps.md b/docs/docs/35-references/10-promotion-steps.md index 4747ad90c..662755278 100644 --- 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 new file mode 100644 index 000000000..7a9cabb6b --- /dev/null +++ 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. }}` 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 +```