From a6e49d77f6c749b5e7c7c3b3968867c59c755f8d Mon Sep 17 00:00:00 2001
From: Hidde Beydals <hidde@hhh.computer>
Date: Mon, 13 Jan 2025 22:16:03 +0100
Subject: [PATCH] docs: document `compose-output` step

Signed-off-by: Hidde Beydals <hidde@hhh.computer>
---
 docs/docs/35-references/10-promotion-steps.md | 56 +++++++++++++++++++
 1 file changed, 56 insertions(+)

diff --git a/docs/docs/35-references/10-promotion-steps.md b/docs/docs/35-references/10-promotion-steps.md
index 4747ad90c0..dfb851de52 100644
--- a/docs/docs/35-references/10-promotion-steps.md
+++ b/docs/docs/35-references/10-promotion-steps.md
@@ -1596,4 +1596,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.git
+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/