chore: add step status docs (#408)

Co-authored-by: Kelly Merrick <kelly.merrick@target.com>
go-vela · Jun 24, 2024 · 06db65a · 06db65a
1 parent 306bd2e
commit 06db65a
Show file tree

Hide file tree

Showing 3 changed files with 67 additions and 13 deletions.
diff --git a/content/reference/environment/variables.md b/content/reference/environment/variables.md
@@ -144,19 +144,20 @@ The following table includes variables only available during the **tag** event.
 
 The following environment variables are **only** injected into every step container.
 
-| Key                      | Value                    | Explanation                                                        |
-| ------------------------ | ------------------------ | ------------------------------------------------------------------ |
-| `VELA_STEP_CREATED`      | `1556720958`             | unix timestamp representing step creation time                     |
-| `VELA_STEP_DISTRIBUTION` | `linux`                  | distribution where the step was executed                           |
-| `VELA_STEP_EXIT_CODE`    | `0`                      | exit code of the step when container starts                        |
-| `VELA_STEP_HOST`         | `vela-worker-1`          | fully qualified domain name of the worker the step was executed on |
-| `VELA_STEP_IMAGE`        | `target/vela-git:latest` | name of the image executed                                         |
-| `VELA_STEP_NAME`         | `clone`                  | name of the step                                                   |
-| `VELA_STEP_NUMBER`       | `1`                      | number of the step executed within the pipeline                    |
-| `VELA_STEP_RUNTIME`      | `docker`                 | runtime where the step was executed                               |
-| `VELA_STEP_STAGE`        | `clone`                  | name of the stage the step belongs to within the pipeline          |
-| `VELA_STEP_STARTED`      | `1556730001`             | unix timestamp representing step start time                       |
-| `VELA_STEP_STATUS`       | `success`                | status of the step                                                 |
+| Key                      | Value                    | Explanation                                                          |
+| ------------------------ | ------------------------ | ------------------------------------------------------------------- |
+| `VELA_STEP_CREATED`      | `1556720958`             | unix timestamp representing step creation time                       |
+| `VELA_STEP_DISTRIBUTION` | `linux`                  | distribution where the step was executed                             |
+| `VELA_STEP_EXIT_CODE`    | `0`                      | exit code of the step when container starts                          |
+| `VELA_STEP_HOST`         | `vela-worker-1`          | fully qualified domain name of the worker the step was executed on   |
+| `VELA_STEP_IMAGE`        | `target/vela-git:latest` | name of the image executed                                           |
+| `VELA_STEP_NAME`         | `clone`                  | name of the step                                                     |
+| `VELA_STEP_NUMBER`       | `1`                      | number of the step executed within the pipeline                      |
+| `VELA_STEP_REPORT_AS`    | `cypress tests`          | context to which to publish for the commit that reflects step status |
+| `VELA_STEP_RUNTIME`      | `docker`                 | runtime where the step was executed                                  |
+| `VELA_STEP_STAGE`        | `clone`                  | name of the stage the step belongs to within the pipeline            |
+| `VELA_STEP_STARTED`      | `1556730001`             | unix timestamp representing step start time                          |
+| `VELA_STEP_STATUS`       | `success`                | status of the step                                                   |
 
 ## Service Only Defaults
 

diff --git a/content/reference/yaml/steps.md b/content/reference/yaml/steps.md
@@ -367,6 +367,19 @@ steps:
           build: "go build ./..."  
 ```
 
+#### The `report_as` tag
+
+```yaml
+---
+steps:
+  # publish custom status for commit with `test suite` as the context
+  - report_as: test suite
+```
+
+{{% alert color="info" %}}
+A pipeline can have up to 10 steps that report their own status.
+{{% /alert %}}
+
 #### The `entrypoint:` tag
 
 ```yaml

diff --git a/content/tour/status.md b/content/tour/status.md
@@ -0,0 +1,40 @@
+---
+title: "Status"
+linkTitle: "Status"
+weight: 12
+description: >
+  Learn about Vela statuses.
+---
+
+Vela will always publish build statuses to the source control management system. These statuses correspond with the webhook event that triggered the build.
+
+These statuses can be used to define various branch protection policies.
+
+Vela also supports up to 10 step-level statuses. These statuses will reflect the success or failure of the _step_ rather than the build. The name of this status will match the value of the `report_as` tag.
+
+<!-- section break -->
+
+```yaml
+# In this pipeline, the status of the build overall will publish 
+# to the source control management system (SCM).
+#
+# The step "Test Suite" will publish to the
+# SCM separately as `<context_prefix>/<event>/testing`.
+
+- name: Welcome
+  image: alpine
+  commands:
+    - echo "Welcome to the Vela docs"
+
+- name: Test Suite
+  image: golang:latest
+  report_as: testing
+  commands:
+    - go test
+```
+
+<!-- section break -->
+
+**Tag references:**
+
+[`name:`](/docs/reference/yaml/steps/#the-name-tag), [`image:`](/docs/reference/yaml/steps/#the-image-tag), [`commands:`](/docs/reference/yaml/steps/#the-commands-tag), [`report_as:`](/docs/reference/yaml/steps/#the-report_as-tag)