From 06db65a01a2f464c352933426cfb18c1ba65d54b Mon Sep 17 00:00:00 2001 From: Easton Crupper <65553218+ecrupper@users.noreply.github.com> Date: Mon, 24 Jun 2024 18:44:04 -0400 Subject: [PATCH] chore: add step status docs (#408) Co-authored-by: Kelly Merrick --- content/reference/environment/variables.md | 27 ++++++++------- content/reference/yaml/steps.md | 13 +++++++ content/tour/status.md | 40 ++++++++++++++++++++++ 3 files changed, 67 insertions(+), 13 deletions(-) create mode 100644 content/tour/status.md diff --git a/content/reference/environment/variables.md b/content/reference/environment/variables.md index 4ef416fb8..fdb3235a7 100644 --- 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 index ec3ab6552..2b46ee8bc 100644 --- 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 new file mode 100644 index 000000000..91a64e129 --- /dev/null +++ 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. + + + +```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 `//testing`. + +- name: Welcome + image: alpine + commands: + - echo "Welcome to the Vela docs" + +- name: Test Suite + image: golang:latest + report_as: testing + commands: + - go test +``` + + + +**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) \ No newline at end of file