diff --git a/content/faq/usage/_index.md b/content/faq/usage/_index.md
index 085a39940..ac0b259db 100644
--- a/content/faq/usage/_index.md
+++ b/content/faq/usage/_index.md
@@ -159,18 +159,21 @@ This can be accomplished by using the [`docker pull` CLI command](https://docs.d
 
 ![Invalid Secret Path](invalid_secret_path.png)
 
-This behavior indicates [the `key` property](/docs/reference/yaml/secrets/#the-key-tag) provided for a secret in the pipeline is invalid.
+This behavior indicates [the `key` property](/docs/reference/yaml/secrets/#the-key-key) provided for a secret in the pipeline is invalid.
 
 To resolve the issue, explicitly define the secret depending on the type as outlined in the [secret usage docs](/docs/usage/secrets/) with all of the expected fields.
 
 If you are using a secret that only defines `name` as the property and are receiving this error, you will need add the missing properties as this way of referencing a secret was deprecated in an older version of Vela.
 
 For example:
+
 ```yaml
 secrets:
   - name: foo
 ```
-and even 
+
+and even
+
 ```yaml
 secrets:
   - name: foo
@@ -193,7 +196,7 @@ secrets:
 Make sure to replace `<org>` and `<repo>` for the `key` property with the appropriate values from your source code provider.
 
 If you're using GitHub and using the secret for a pipeline at `https://github.com/octocat/hello`, your `org` would be `octocat` and `repo` would be `hello`.
-{{% /alert %}} 
+{{% /alert %}}
 
 ### Repo is not trusted
 
@@ -201,4 +204,4 @@ If you're using GitHub and using the secret for a pipeline at `https://github.co
 
 This behavior indicates [the `vela_executor_enforce_trusted_repos` flag](/docs/installation/worker/reference/#vela_executor_enforce_trusted_repos) has been set by the Vela platform administrators, which allows only certain repositories to run privileged images.
 
-To resolve the issue, identify the step attempting to run a privileged image and consider a workaround. Otherwise, work with your Vela platform administrators to add your repository to the allowlist. 
+To resolve the issue, identify the step attempting to run a privileged image and consider a workaround. Otherwise, work with your Vela platform administrators to add your repository to the allowlist.
diff --git a/content/reference/api/deployment/add.md b/content/reference/api/deployment/add.md
index e8f2e617e..0faae5b3e 100644
--- a/content/reference/api/deployment/add.md
+++ b/content/reference/api/deployment/add.md
@@ -77,7 +77,7 @@ curl \
 
 #### File with Parameters
 
-If you would like to pass parameters, which can be referenced in the pipeline as `$DEPLOYMENT_PARAMETER_<KEY>`, include them as a map inside the `payload` tag.
+If you would like to pass parameters, which can be referenced in the pipeline as `$DEPLOYMENT_PARAMETER_<KEY>`, include them as a map inside the `payload` key.
 
 ```json
 {
diff --git a/content/reference/yaml/_index.md b/content/reference/yaml/_index.md
index f76457e5b..0b0a58af2 100644
--- a/content/reference/yaml/_index.md
+++ b/content/reference/yaml/_index.md
@@ -27,7 +27,7 @@ See YAML [design goals](https://yaml.org/spec/1.2/spec.html#Introduction) from s
 Whether you are a YAML expert or a novice, here is some quick terminology that you should be aware of:
 
 {{% alert title="Tip:" color="info" %}}
-You can get feedback directly on your `.vela.yml` or `.vela.yaml` pipelines in your IDE with the available [JSON Schema](/docs/usage/schema/). 
+You can get feedback directly on your `.vela.yml` or `.vela.yaml` pipelines in your IDE with the available [JSON Schema](/docs/usage/schema/).
 {{% /alert %}}
 
 ### Document
@@ -41,9 +41,9 @@ Example:
 key: value
 ```
 
-### Tags
+### Keys
 
-A YAML document is compose of one to many key-value pairs where the key is called the tag and the value is evaluated to an explicit type (Int, Float, string, bool, etc), see [YAML 1.2 spec for full details](https://yaml.org/spec/1.2/spec.html#id2761292).
+A YAML document is compose of one to many key-value pairs where the value is evaluated to an explicit type (Int, Float, string, bool, etc), see [YAML 1.2 spec for full details](https://yaml.org/spec/1.2/spec.html#id2761292).
 
 Example:
 
@@ -60,4 +60,5 @@ canonical: "Hello, World"
 
 # a bool
 canonical: true
-```
\ No newline at end of file
+```
+
diff --git a/content/reference/yaml/environment.md b/content/reference/yaml/environment.md
index 781ebfd64..158469cbf 100644
--- a/content/reference/yaml/environment.md
+++ b/content/reference/yaml/environment.md
@@ -3,16 +3,17 @@ title: "Environment"
 linkTitle: "Environment"
 weight: 1
 description: >
-  YAML tags for environment block
+  YAML keys for environment block
 ---
 
-The environment tag is intended to be used to inject a global environment configuration into steps, services and secret containers. Control of which container types get the injected environment settings is available via the metadata block.
+The environment key is intended to be used to inject a global environment configuration into steps, services and secret containers. Control of which container types get the injected environment settings is available via the metadata block.
 
 ```yaml
 ---
-# This document is displaying using the environment tag with a map syntax.
+# This document is displaying using the environment key with a map syntax.
 # Additionally, you can also use array syntax where the items in
 # they array are of pattern HELLO="Hello, Vela!"
 environment:
   HELLO: "Hello, Vela!"
-```
\ No newline at end of file
+```
+
diff --git a/content/reference/yaml/metadata.md b/content/reference/yaml/metadata.md
index 78aa4de6b..cdca000cc 100644
--- a/content/reference/yaml/metadata.md
+++ b/content/reference/yaml/metadata.md
@@ -3,23 +3,23 @@ title: "Metadata"
 linkTitle: "Metadata"
 weight: 2
 description: >
-  YAML tags for metadata block
+  YAML keys for metadata block
 ---
 
-The metadata tag is intended to be used during the compile phase to signal how to treat the YAML document.
+The metadata key is intended to be used during the compile phase to signal how to treat the YAML document.
 
 ```yaml
 ---
-# This document is displaying all the available tags
+# This document is displaying all the available keys
 # in their default state for the compile process.
 metadata:
   template: false
   clone: true
 ```
 
-## Tags
+## Keys
 
-| Tag             | Required | Type        | Description                                                       |
+| Key             | Required | Type        | Description                                                       |
 | --------------- | -------- | ----------- | ----------------------------------------------------------------- |
 | `template`      | Y        | bool        | Enables compiling the pipeline as a template.                     |
 | `clone`         | N        | bool        | Enables injecting the default clone process.                      |
@@ -28,7 +28,7 @@ metadata:
 
 ### Usage
 
-#### The `template:` tag
+#### The `template:` key
 
 {{% alert title="Tip:" color="info" %}}
 To learn how to write templates, see the [template documentation](/docs/templates).
@@ -43,7 +43,7 @@ metadata:
   template: true
 ```
 
-#### The `clone:` tag
+#### The `clone:` key
 
 ```yaml
 ---
@@ -52,7 +52,7 @@ metadata:
   clone: true
 ```
 
-#### The `environment:` tag
+#### The `environment:` key
 
 ```yaml
 ---
@@ -63,7 +63,7 @@ metadata:
   environment: [steps, services, secrets]
 ```
 
-#### The `render_inline:` tag
+#### The `render_inline:` key
 
 ```yaml
 ---
@@ -75,9 +75,9 @@ metadata:
   render_inline: false
 ```
 
-#### The `auto_cancel` tag
+#### The `auto_cancel` key
 
-| Tag              | Default | Type | Description                                                                                 |
+| Key              | Default | Type | Description                                                                                 |
 | ---------------- | ------- | ---- | ------------------------------------------------------------------------------------------- |
 | `pending`        | True    | bool | Pending builds will be auto canceled if qualifying build is triggered                       |
 | `running`        | False   | bool | Currently running builds will be auto canceled if qualifying build is triggered             |
diff --git a/content/reference/yaml/secrets.md b/content/reference/yaml/secrets.md
index d8142619e..6b1ff0132 100644
--- a/content/reference/yaml/secrets.md
+++ b/content/reference/yaml/secrets.md
@@ -3,14 +3,14 @@ title: "Secrets"
 linkTitle: "Secrets"
 weight: 8
 description: >
-  YAML tags for secret block
+  YAML keys for secret block
 ---
 
-The secret tag is intended to be used to pull secrets from the Vela server or execute plugins to write the external secrets to the build volume.
+The secret key is intended to be used to pull secrets from the Vela server or execute plugins to write the external secrets to the build volume.
 
 ```yaml
 ---
-# This document is displaying all the required tags
+# This document is displaying all the required keys
 # to pull various secret types.
 secrets:
   # Below is displaying the declarative secret definitions.
@@ -46,9 +46,9 @@ secrets:
            path: user
 ```
 
-## Tags
+## Keys
 
-| Tag      | Required | Type   | Description                                                     |
+| Key      | Required | Type   | Description                                                     |
 | -------- | -------- | ------ | --------------------------------------------------------------- |
 | `name`   | Y        | string | Name of secret to reference in the pipeline.                    |
 | `key`    | N        | string | Path to secret to fetch from storage backend.                   |
@@ -57,7 +57,7 @@ secrets:
 | `pull`   | N        | string | When to pull in secrets from storage backend.                   |
 | `origin` | N        | struct | Declaration to pull secrets from non-internal secret providers. |
 
-#### The `name:` tag
+#### The `name:` key
 
 ```yaml
 ---
@@ -66,7 +66,7 @@ secrets:
   - name: postgres
 ```
 
-#### The `key:` tag
+#### The `key:` key
 
 {{% alert title="Tip:" color="info" %}}
 The key is unique
@@ -94,7 +94,7 @@ secrets:
   - key: go-vela/admins/foo1
 ```
 
-#### The `engine:` tag
+#### The `engine:` key
 
 {{% alert title="Tip:" color="info" %}}
 To know what engines are available for your Vela installation, we recommend consulting your system administrators.
@@ -108,7 +108,7 @@ secrets:
   - engine: native
 ```
 
-#### The `type:` tag
+#### The `type:` key
 
 ```yaml
 ---
@@ -119,7 +119,7 @@ secrets:
   - type: repo
 ```
 
-#### The `pull:` tag
+#### The `pull:` key
 
 ```yaml
 ---
@@ -132,12 +132,12 @@ secrets:
 
 {{% alert title="Important:" color="warning" %}} `step_start` or lazy loading secrets
 is not currently available for the [Kubernetes-based workers](/docs/installation/worker/kubernetes/) and does not work with secrets
-originating from plugins loaded via [`origin:` tag](/docs/reference/yaml/secrets/#the-pull-tag) (see below).
+originating from plugins loaded via [`origin:`](/docs/reference/yaml/secrets/#the-pull-key) (see below).
 {{% /alert %}}
 
-#### The `origin:` tag
+#### The `origin:` key
 
-| Tag           | Required | Type     | Description                                                      |
+| Key           | Required | Type     | Description                                                      |
 | ------------- | -------- | -------- | ---------------------------------------------------------------- |
 | `name`        | Y        | string   | Unique identifier for the container in the pipeline.             |
 | `image`       | Y        | []string | Docker image used to create an ephemeral container.              |
@@ -149,11 +149,11 @@ originating from plugins loaded via [`origin:` tag](/docs/reference/yaml/secrets
 
 {{% alert title="Note:" color="info" %}} The `pull:` option under `origin:`
 allows for different values than the
-[Secrets `pull:` tag](/docs/reference/yaml/secrets/#the-pull-tag). It mimics the
-[Steps version of the `pull:` tag](/docs/reference/yaml/steps/#the-pull-tag).
+[Secrets `pull:` key](/docs/reference/yaml/secrets/#the-pull-key). It mimics the
+[Steps version of the `pull:` key](/docs/reference/yaml/steps/#the-pull-key).
 {{% /alert %}}
 
 {{% alert title="Tip:" color="success" %}} In an effort to reduce duplicate
 documentation, see the comparable
-[step tags documentation](/docs/reference/yaml/steps/#tags) to learn how tags
+[step keys documentation](/docs/reference/yaml/steps/#keys) to learn how keys
 can be set and details on behavior. {{% /alert %}}
diff --git a/content/reference/yaml/services.md b/content/reference/yaml/services.md
index d6091ffd0..d58852107 100644
--- a/content/reference/yaml/services.md
+++ b/content/reference/yaml/services.md
@@ -3,23 +3,23 @@ title: "Services"
 linkTitle: "Services"
 weight: 5
 description: >
-  YAML tags for services block
+  YAML keys for services block
 ---
 
-The `services` tag is intended to be used to run applications alongside the pipeline.
+The `services` key is intended to be used to run applications alongside the pipeline.
 
 ```yaml
 ---
-# This document is displaying all the required tags
+# This document is displaying all the required keys
 # to run a postgres database for the duration of a pipeline.
 services: 
   - name: postgres
     image: postgres:latest
 ```
 
-## Tags
+## Keys
 
-| Tag           | Required | Type            | Description                                                     |
+| Key           | Required | Type            | Description                                                     |
 |---------------|----------|-----------------|-----------------------------------------------------------------|
 | `name`        | Y        | string          | Unique identifier for the container in the pipeline             |
 | `image`       | Y        | string          | Docker image used to create an ephemeral container              |
@@ -32,7 +32,7 @@ services:
 
 ### Usage
 
-#### The `name:` tag
+#### The `name:` key
 
 ```yaml
 ---
@@ -41,7 +41,7 @@ services:
   - name: postgres
 ```
 
-#### The `image:` tag
+#### The `image:` key
 
 ```yaml
 ---
@@ -50,7 +50,7 @@ services:
   - image: postgres:latest
 ```
 
-#### The `pull:` tag
+#### The `pull:` key
 
 ```yaml
 ---
@@ -61,7 +61,7 @@ services:
   - pull: always
 ```
 
-#### The `environment:` tag
+#### The `environment:` key
 
 ```yaml
 ---
@@ -81,7 +81,7 @@ services:
       - DB_NAME=vela
 ```
 
-#### The `entrypoint:` tag
+#### The `entrypoint:` key
 
 ```yaml
 ---
@@ -92,7 +92,7 @@ services:
       - /some/binary/postgres
 ```
 
-#### The `ports:` tag
+#### The `ports:` key
 
 ```yaml
 ---
@@ -102,7 +102,7 @@ services:
       - "8080:5432"
 ```
 
-#### The `ulimits:` tag
+#### The `ulimits:` key
 
 ```yaml
 ---
@@ -116,7 +116,7 @@ services:
         hard: 2048
 ```
 
-#### The `user:` tag
+#### The `user:` key
 
 ```yaml
 ---
diff --git a/content/reference/yaml/stages.md b/content/reference/yaml/stages.md
index 668f66ccf..ce6c3c07e 100644
--- a/content/reference/yaml/stages.md
+++ b/content/reference/yaml/stages.md
@@ -3,14 +3,14 @@ title: "Stages"
 linkTitle: "Stages"
 weight: 7
 description: >
-  YAML stages for stages block
+  YAML keys for stages block
 ---
 
-The `stages` tag is intended to be used to parallelize one-to-many sets of step tasks.
+The `stages` key is intended to be used to parallelize one-to-many sets of step tasks.
 
 ```yaml
 ---
-# This document is displaying all the required tags
+# This document is displaying all the required keys
 # to run two stages with one step task in parallel.
 stages:
   hello:
@@ -28,9 +28,9 @@ stages:
           - echo "Welcome to Vela!"
 ```
 
-## Tags
+## Keys
 
-| Tag           | Required | Type     | Description                                                               |
+| Key           | Required | Type     | Description                                                               |
 |---------------|----------|----------|---------------------------------------------------------------------------|
 | `name`        | Y        | string   | Unique identifier for the stage in the pipeline                           |
 | `steps`       | Y        | []string | Sequential execution instructions for the stage                           |
@@ -39,7 +39,7 @@ stages:
 
 ### Usage
 
-#### The `name:` tag
+#### The `name:` key
 
 ```yaml
 ---
@@ -48,7 +48,7 @@ stages:
     welcome:
 ```
 
-#### The `steps:` tag
+#### The `steps:` key
 
 ```yaml
 ---
@@ -60,10 +60,10 @@ stages:
 ```
 
 {{% alert title="Tip:" color="info" %}}
-For more details on steps tags, see the [step tags documentation](/docs/reference/yaml/steps/#tags)
+For more details on steps keys, see the [step keys documentation](/docs/reference/yaml/steps/#keys)
 {{% /alert %}}
 
-#### The `needs:` tag
+#### The `needs:` key
 
 ```yaml
 ---
@@ -76,7 +76,7 @@ stages:
       needs: [ greeting ]
 ```
 
-#### The `independent:` tag
+#### The `independent:` key
 
 ```yaml
 ---
diff --git a/content/reference/yaml/steps.md b/content/reference/yaml/steps.md
index 2b46ee8bc..75de92355 100644
--- a/content/reference/yaml/steps.md
+++ b/content/reference/yaml/steps.md
@@ -3,15 +3,15 @@ title: "Steps"
 linkTitle: "Steps"
 weight: 6
 description: >
-  YAML tags for steps block
+  YAML keys for steps block
 ---
 
-The steps tag is intended to be used to run sequential tasks in a pipeline.
+The steps key is intended to be used to run sequential tasks in a pipeline.
 
 ```yaml
 ---
-# This document is displaying all the required tags
-# to run a postgre database for the duration of a pipeline.
+# This document is displaying all the required keys
+# to run a postgres database for the duration of a pipeline.
 steps: 
   - name: Hello World
     image: alpine:latest
@@ -19,9 +19,9 @@ steps:
       - echo "Hello, Vela User"
 ```
 
-## Tags
+## Keys
 
-| Tag           | Required | Type            | Description                                                      |
+| Key           | Required | Type            | Description                                                      |
 |---------------|----------|-----------------|------------------------------------------------------------------|
 | `name`        | Y        | string          | Unique identifier for the container in the pipeline.             |
 | `image`       | Y        | string          | Docker image used to create ephemeral container.                 |
@@ -37,10 +37,9 @@ steps:
 | `ulimits`     | N        | string          | Set the user limits for the container.                           |                        |
 | `user`        | N        | string          | Set the user for the container. |
 
-
 ### Usage
 
-#### The `name:` tag
+#### The `name:` key
 
 ```yaml
 ---
@@ -49,7 +48,7 @@ steps:
   - name: Hello World
 ```
 
-#### The `image:` tag
+#### The `image:` key
 
 ```yaml
 ---
@@ -58,7 +57,7 @@ steps:
   - image: alpine:latest
 ```
 
-#### The `pull:` tag
+#### The `pull:` key
 
 ```yaml
 ---
@@ -69,7 +68,7 @@ steps:
   - pull: always
 ```
 
-#### The `secrets:` tag
+#### The `secrets:` key
 
 ```yaml
 ---
@@ -86,14 +85,14 @@ steps:
     # environment as upper case env. i.e. GIT_USERNAME=<secret_value> 
   - secrets: 
       # The source is the "name:" of a secret within the
-      # parent "secrets:" yaml tag
+      # parent "secrets:" yaml key
       - source: username
       # The target is the desired environment key accessible during
       # the container runtime.
         target: git_username
 ```
 
-#### The `environment:` tag
+#### The `environment:` key
 
 ```yaml
 ---
@@ -113,7 +112,7 @@ steps:
       - DB_NAME=vela
 ```
 
-#### The `ruleset:` tag
+#### The `ruleset:` key
 
 The following rules can be used to configure a ruleset:
 
@@ -183,6 +182,7 @@ If you wish to include _all_ event types from an event, you can specify a wildca
     ruleset:
       event: pull_request*  # will run on opened, reopened, synchronize, edited, labeled, and unlabeled
 ```
+
 {{% /alert %}}
 
 ```yaml
@@ -240,7 +240,7 @@ steps:
 steps:
   - ruleset:
       # As shown below this step will execute if the build target is stage or production.
-      # This tag is only compatible with deployment and schedule events.
+      # This key is only compatible with deployment and schedule events.
       target: [ dev/*, test/* ]
 ```
 
@@ -308,14 +308,14 @@ steps:
         event: push
 ```
 
-#### The `parameters:` tag
+#### The `parameters:` key
 
 ```yaml
 ---
 steps:
-    # Extra configuration variables specific to a plugin. All tags within the 
-    # parameters tag are injected environment variables into the
-    # container as PARAMETER_<TAG_NAME>.
+    # Extra configuration variables specific to a plugin. All keys within the 
+    # parameters key are injected environment variables into the
+    # container as PARAMETER_<KEY_NAME>.
     # As shown below this step will execute a plugin that needs two fields:
     # PARAMETER_REGISTRY=index.docker.io
     # PARAMETER_REPO=octocat/hello-world,go-vela/docs
@@ -324,7 +324,7 @@ steps:
       repo: [ go-vela/hello-world,  go-vela/docs ]
 ```
 
-#### The `commands:` tag
+#### The `commands:` key
 
 ```yaml
 ---
@@ -334,9 +334,9 @@ steps:
       - echo "Hello, World"
 ```
 
-#### The `template:` tag
+#### The `template:` key
 
-The following tags can be used to configure a template injection:
+The following keys can be used to configure a template injection:
 
 | Name   | Description                            |
 |--------| ---------------------------------------|
@@ -348,7 +348,7 @@ The following tags can be used to configure a template injection:
 steps:
   - template:
       # Name of template to inject in the step. The name must map
-      # to an existing template in the parent "template" tag.
+      # to an existing template in the parent "template" key.
       name: example
 ```
 
@@ -367,7 +367,7 @@ steps:
           build: "go build ./..."  
 ```
 
-#### The `report_as` tag
+#### The `report_as` key
 
 ```yaml
 ---
@@ -380,7 +380,7 @@ steps:
 A pipeline can have up to 10 steps that report their own status.
 {{% /alert %}}
 
-#### The `entrypoint:` tag
+#### The `entrypoint:` key
 
 ```yaml
 ---
@@ -391,18 +391,18 @@ steps:
       - /bin/ls
 ```
 
-#### The `detach:` tag
+#### The `detach:` key
 
 ```yaml
 ---
 steps:
     # Run the container in a detached (headless) state. Similar to the 
-    # "services:" tag this will create a container that can be used throughout
+    # "services:" key this will create a container that can be used throughout
     # the duration of the pipeline.
   - detach: true
 ```
 
-#### The `ulimits:` tag
+#### The `ulimits:` key
 
 ```yaml
 ---
@@ -416,11 +416,12 @@ steps:
         hard: 2048
 ```
 
-#### The `user:` tag
+#### The `user:` key
 
 ```yaml
 ---
 steps:
     # Run the container with the foo user.
   - user: foo
-```
\ No newline at end of file
+```
+
diff --git a/content/reference/yaml/templates.md b/content/reference/yaml/templates.md
index 5ee6ccedc..9cd0edd8b 100644
--- a/content/reference/yaml/templates.md
+++ b/content/reference/yaml/templates.md
@@ -3,14 +3,14 @@ title: "Templates"
 linkTitle: "Templates"
 weight: 4
 description: >
-  YAML tags for templates block
+  YAML keys for templates block
 ---
 
-The template tag is intended to be used to identify where to retrieve templates during the compiler phase of the pipeline.
+The template key is intended to be used to identify where to retrieve templates during the compiler phase of the pipeline.
 
 ```yaml
 ---
-# This document is displaying all the required tags
+# This document is displaying all the required keys
 # to pull a template from a remote system.
 templates:
   - name: example
@@ -18,9 +18,9 @@ templates:
     type: github    
 ```
 
-## Tags
+## Keys
 
-| Tag      | Required | Type   | Description                                           |
+| Key      | Required | Type   | Description                                           |
 |----------|----------|--------|-------------------------------------------------------|
 | `name`   | Y        | string | indicates a unique identifier for the template.       |
 | `source` | Y        | string | indicates a path to a template in remote system.      |
@@ -33,7 +33,7 @@ templates:
 To learn how to write templates, see the [template documentation](/docs/templates)
 {{% /alert %}}
 
-#### The `name:` tag
+#### The `name:` key
 
 ```yaml
 templates:
@@ -42,7 +42,7 @@ templates:
   - name: example
 ```
 
-#### The `source:` tag
+#### The `source:` key
 
 ```yaml
 templates:
@@ -61,7 +61,7 @@ templates:
     source: path/to/template.yml
 ```
 
-#### The `type:` tag
+#### The `type:` key
 
 ```yaml
 templates:
@@ -75,7 +75,7 @@ templates:
     type: file
 ```
 
-#### The `format:` tag
+#### The `format:` key
 
 ```yaml
 templates:
diff --git a/content/reference/yaml/version.md b/content/reference/yaml/version.md
index 37cb70cea..d9c136723 100644
--- a/content/reference/yaml/version.md
+++ b/content/reference/yaml/version.md
@@ -3,13 +3,14 @@ title: "Version"
 linkTitle: "Version"
 weight: 1
 description: >
-  YAML tags for version block
+  YAML keys for version block
 ---
 
-The version tag is intended to be used in order to issue warnings for deprecated features or breaking changes within the YAML document.
+The version key is intended to be used in order to issue warnings for deprecated features or breaking changes within the YAML document.
 
 ```yaml
 ---
-# This document is displaying using the version tag within a yaml file.
+# This document is displaying using the version key within a yaml file.
 version: "1"
-```
\ No newline at end of file
+```
+
diff --git a/content/reference/yaml/worker.md b/content/reference/yaml/worker.md
index c14abd4a3..dca24f769 100644
--- a/content/reference/yaml/worker.md
+++ b/content/reference/yaml/worker.md
@@ -3,14 +3,14 @@ title: "Worker"
 linkTitle: "Worker"
 weight: 3
 description: >
-  YAML tags for worker block
+  YAML keys for worker block
 ---
 
-The worker tag is intended to be used to route a build to a specific worker pool of workers available with the Vela queue.
+The worker key is intended to be used to route a build to a specific worker pool of workers available with the Vela queue.
 
 ```yaml
 ---
-# This document is displaying all the available tags
+# This document is displaying all the available keys
 # and routing the build to a specific worker "sm:docker".
 worker:
   flavor: sm
@@ -21,9 +21,9 @@ worker:
 Routes are defined by the Vela system administrators during installation. To know what routes are available for your Vela installation, we recommend consulting your system administrators.
 {{% /alert %}}
 
-## Tags
+## Keys
 
-| Tag        | Required | Type   | Description                                          |
+| Key        | Required | Type   | Description                                          |
 |------------|----------|--------|------------------------------------------------------|
 | `flavor`   | N        | string | Indicates what flavor of a worker. (i.e. sm, m, lg)    |
 | `platform` | N        | string | Indicates the platform of a worker. (i.e. docker, k8s) |
@@ -34,7 +34,7 @@ Routes are defined by the Vela system administrators during installation. To kno
 See an [example](/docs/usage/examples/route/) on how to route a build.
 {{% /alert %}}
 
-#### The `flavor:` tag
+#### The `flavor:` key
 
 ```yaml
 ---
@@ -44,7 +44,7 @@ worker:
   flavor: sm
 ```
 
-#### The `platform:` tag
+#### The `platform:` key
 
 ```yaml
 ---
@@ -52,4 +52,5 @@ worker:
   # Indicates the platform of worker (i.e. docker, k8s). If not specified
   # will be scheduled in the generic "vela" queue.
   platform: docker
-```
\ No newline at end of file
+```
+
diff --git a/content/tour/cloning.md b/content/tour/cloning.md
index d3c334e51..d61f94a09 100644
--- a/content/tour/cloning.md
+++ b/content/tour/cloning.md
@@ -32,7 +32,6 @@ steps:
       - cat .vela.yml
 ```
 
-
 ```yaml
 # Below is displaying how to turn off the clone behavior.
 metadata:
@@ -54,6 +53,7 @@ steps:
 
 <!-- section break -->
 
-**Tag references:**
+**Key references:**
+
+[`clone:`](/docs/reference/yaml/metadata/#the-clone-key), [`name:`](/docs/reference/yaml/steps/#the-name-key), [`image:`](/docs/reference/yaml/steps/#the-image-key), [`parameters:`](/docs/reference/yaml/steps/#the-parameters-key),
 
-[`clone:`](/docs/reference/yaml/metadata/#the-clone-tag), [`name:`](/docs/reference/yaml/steps/#the-name-tag), [`image:`](/docs/reference/yaml/steps/#the-image-tag), [`parameters:`](/docs/reference/yaml/steps/#the-parameters-tag),
\ No newline at end of file
diff --git a/content/tour/environment.md b/content/tour/environment.md
index 0e1ec328d..229b6b297 100644
--- a/content/tour/environment.md
+++ b/content/tour/environment.md
@@ -6,7 +6,7 @@ description: >
   Learn about environment.
 ---
 
-To define environment variables you can add an `environment:` YAML tag. Environment variables can be scoped to be global, within a stage, or within a step.
+To define environment variables you can add an `environment:` YAML key. Environment variables can be scoped to be global, within a stage, or within a step.
 
 All platform variables get injected with a custom `VELA_` prefix pattern.
 
@@ -60,6 +60,6 @@ stages:
 
 <!-- section break -->
 
-**Tag references:**
+**Key references:**
 
-[`name:`](/docs/reference/yaml/steps/#the-name-tag), [`image:`](/docs/reference/yaml/steps/#the-image-tag), [`environment:`](/docs/reference/yaml/steps/#the-environment-tag), [`commands:`](/docs/reference/yaml/steps/#the-commands-tag), 
+[`name:`](/docs/reference/yaml/steps/#the-name-key), [`image:`](/docs/reference/yaml/steps/#the-image-key), [`environment:`](/docs/reference/yaml/steps/#the-environment-key), [`commands:`](/docs/reference/yaml/steps/#the-commands-key),
diff --git a/content/tour/image.md b/content/tour/image.md
index d91ccc11c..5a11aee9f 100644
--- a/content/tour/image.md
+++ b/content/tour/image.md
@@ -7,13 +7,13 @@ description: >
 ---
 All Vela steps will require an image declaration to be provided.
 
-The `image:` tag is a key component that defines the [Docker Image](https://docs.docker.com/engine/docker-overview/#images) you want to be executed during the step.
+The `image:` key is a key component that defines the [Docker Image](https://docs.docker.com/engine/docker-overview/#images) you want to be executed during the step.
 
 The default behavior is for a Vela worker to pull an image if it is not present on the host. Docker daemon's cache image layers locally, by allowing the default behavior to use the cache you can get the advantage of faster build start up times.
 
 Sometimes this isn't the desired behavior and you want the image to always be pulled or pulled at a specific point in the pipeline lifecycle.
 
-That's when you can use the `pull:` tag to set the policy for how/when the image pull interaction should be treated.
+That's when you can use the `pull:` key to set the policy for how/when the image pull interaction should be treated.
 
 **Expand your knowledge with an example!**
 
@@ -49,6 +49,7 @@ image: index.docker.io/library/alpine:3
 
 <!-- section break -->
 
-**Tag references:**
+**Key references:**
+
+[`name:`](/docs/reference/yaml/steps/#the-name-key), [`image:`](/docs/reference/yaml/steps/#the-image-key), [`pull:`](/docs/reference/yaml/steps/#the-commands-key),  [`commands:`](/docs/reference/yaml/steps/#the-commands-key),
 
-[`name:`](/docs/reference/yaml/steps/#the-name-tag), [`image:`](/docs/reference/yaml/steps/#the-image-tag), [`pull:`](/docs/reference/yaml/steps/#the-commands-tag),  [`commands:`](/docs/reference/yaml/steps/#the-commands-tag), 
\ No newline at end of file
diff --git a/content/tour/plugins.md b/content/tour/plugins.md
index 8985e4f1f..9b0c31d9d 100644
--- a/content/tour/plugins.md
+++ b/content/tour/plugins.md
@@ -10,11 +10,11 @@ A plugin is a Docker container that is designed to perform a set of pre-defined
 
 These actions can be for any number of general tasks, deploying code, publishing artifacts and more.
 
-Anyone can create a plugin and use it in their pipeline. 
+Anyone can create a plugin and use it in their pipeline.
 
 The registry of existing plugins can be found on this site in the [plugins](/docs/plugins/registry/) tab.
 
-Within the parameters block tags are injected as upper case environment variables with the pattern of `PARAMETER_<YAML_TAG>`.
+Within the parameters block, keys are injected as upper case environment variables with the pattern of `PARAMETER_<YAML_KEY>`.
 
 **Expand your knowledge with an example!**
 
@@ -45,6 +45,7 @@ steps:
 
 <!-- section break -->
 
-**Tag references:**
+**Key references:**
+
+[`name:`](/docs/reference/yaml/steps/#the-name-key), [`image:`](/docs/reference/yaml/steps/#the-image-key), [`parameters:`](/docs/reference/yaml/steps/#the-parameters-key),
 
-[`name:`](/docs/reference/yaml/steps/#the-name-tag), [`image:`](/docs/reference/yaml/steps/#the-image-tag), [`parameters:`](/docs/reference/yaml/steps/#the-parameters-tag), 
\ No newline at end of file
diff --git a/content/tour/rulesets.md b/content/tour/rulesets.md
index 9c2c1a2fa..95723adf2 100644
--- a/content/tour/rulesets.md
+++ b/content/tour/rulesets.md
@@ -12,7 +12,7 @@ When you push your code to a source control management system a payload is sent
 
 Within that payload contains characteristics about what just happened. Maybe it was a push to the main branch, feature branch or tag on any specific commit.
 
-The ruleset tag gives you the ability to add conditions on the step to tell Vela when this step should be executed.
+The ruleset key gives you the ability to add conditions on the step to tell Vela when this step should be executed.
 
 <!-- section break -->
 
@@ -43,6 +43,6 @@ The ruleset tag gives you the ability to add conditions on the step to tell Vela
 
 <!-- section break -->
 
-**Tag references:**
+**Key references:**
 
-[`name:`](/docs/reference/yaml/steps/#the-name-tag), [`ruleset:`](/docs/reference/yaml/steps/#the-ruleset-tag),[`image:`](/docs/reference/yaml/steps/#the-image-tag), [`commands:`](/docs/reference/yaml/steps/#the-commands-tag),
+[`name:`](/docs/reference/yaml/steps/#the-name-key), [`ruleset:`](/docs/reference/yaml/steps/#the-ruleset-key),[`image:`](/docs/reference/yaml/steps/#the-image-key), [`commands:`](/docs/reference/yaml/steps/#the-commands-key),
diff --git a/content/tour/secrets.md b/content/tour/secrets.md
index cd9aed1ad..22eea2827 100644
--- a/content/tour/secrets.md
+++ b/content/tour/secrets.md
@@ -16,7 +16,7 @@ Let's go back to our Docker image used within the plugin tutorial and focus only
 
 The pipeline we are looking at shows a few different patterns on how you can leverage adding and aliasing secrets in your pipeline.
 
-However, this time we are going to remove the `username:` and `password:` YAML tags in the `parameter:` block and replace them with secrets within the container environment.
+However, this time we are going to remove the `username:` and `password:` YAML keys in the `parameter:` block and replace them with secrets within the container environment.
 
 **See it in action with examples!**
 
@@ -71,6 +71,6 @@ secrets:
 
 <!-- section break -->
 
-**Tag references:**
+**Key references:**
 
-[(step) `secrets:`](/docs/reference/yaml/steps/#the-secrets-tag), [(parent)  `secrets:`](/docs/reference/yaml/secrets),
+[(step) `secrets:`](/docs/reference/yaml/steps/#the-secrets-key), [(parent)  `secrets:`](/docs/reference/yaml/secrets),
diff --git a/content/tour/services.md b/content/tour/services.md
index b6c6c8fa3..49da1f9fe 100644
--- a/content/tour/services.md
+++ b/content/tour/services.md
@@ -71,7 +71,6 @@ $ vela exec pipeline
 
 <!-- section break -->
 
-**Tag references:**
-
-[`name:`](/docs/reference/yaml/services/#the-name-tag), [`image:`](/docs/reference/yaml/services/#the-image-tag), [`detach:`](/docs/reference/yaml/steps/#the-detach-tag),
+**Key references:**
 
+[`name:`](/docs/reference/yaml/services/#the-name-key), [`image:`](/docs/reference/yaml/services/#the-image-key), [`detach:`](/docs/reference/yaml/steps/#the-detach-key),
diff --git a/content/tour/stages.md b/content/tour/stages.md
index 2aa6dc52a..22609fa97 100644
--- a/content/tour/stages.md
+++ b/content/tour/stages.md
@@ -8,7 +8,7 @@ description: >
 
 A stages pipelines are designed to parallelize one-to-many sets of step tasks.
 
-By design all of the stages will run at the same time unless the user uses a `needs:` YAML tag to control the flow of stage executions (see example).
+By design all of the stages will run at the same time unless the user uses a `needs:` YAML key to control the flow of stage executions (see example).
 
 Stages will also stop executing their steps if the build fails as a whole, by default. In other words, if stage 1 fails, the steps that have yet to execute in stage 2 will be skipped. The user can declare `independent: true` for any stage to change this behavior.
 
@@ -61,7 +61,7 @@ stages:
 ```
 
 {{% alert title="Note:" color="info" %}}
-Be aware that `needs:` references stages by their name, which can be overridden by the `name` tag in the stage definition.
+Be aware that `needs:` references stages by their name, which can be overridden by the `name` key in the stage definition.
 {{% /alert %}}
 
 ```sh
@@ -77,6 +77,6 @@ $ vela exec pipeline
 
 <!-- section break -->
 
-**Tag references:**
+**Key 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),
+[`name:`](/docs/reference/yaml/steps/#the-name-key), [`image:`](/docs/reference/yaml/steps/#the-image-key), [`commands:`](/docs/reference/yaml/steps/#the-commands-key),
diff --git a/content/tour/status.md b/content/tour/status.md
index 91a64e129..02992b4be 100644
--- a/content/tour/status.md
+++ b/content/tour/status.md
@@ -10,7 +10,7 @@ Vela will always publish build statuses to the source control management system.
 
 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.
+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` key.
 
 <!-- section break -->
 
@@ -35,6 +35,7 @@ Vela also supports up to 10 step-level statuses. These statuses will reflect the
 
 <!-- section break -->
 
-**Tag references:**
+**Key references:**
+
+[`name:`](/docs/reference/yaml/steps/#the-name-key), [`image:`](/docs/reference/yaml/steps/#the-image-key), [`commands:`](/docs/reference/yaml/steps/#the-commands-key), [`report_as:`](/docs/reference/yaml/steps/#the-report_as-key)
 
-[`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
diff --git a/content/tour/step.md b/content/tour/step.md
index fe105926c..38d445b61 100644
--- a/content/tour/step.md
+++ b/content/tour/step.md
@@ -10,7 +10,7 @@ A step declaration allows you to provide execution instructions for a pipeline.
 
 The following step is displaying an example of a minimal configuration for executing a simple echo linux command.
 
-The `name:` tag is the unique identifier for the step throughout the lifecycle of the execution.
+The `name:` key is the unique identifier for the step throughout the lifecycle of the execution.
 
 When `commands:` are provided they are converted to a shell script and executed as the Docker entrypoint for the container.
 
@@ -37,6 +37,7 @@ docker run --entrypoint=build.sh alpine:latest
 
 <!-- section break -->
 
-**Tag references:**
+**Key references:**
+
+[`name:`](/docs/reference/yaml/steps/#the-name-key), [`image:`](/docs/reference/yaml/steps/#the-image-key), [`commands:`](/docs/reference/yaml/steps/#the-commands-key),
 
-[`name:`](/docs/reference/yaml/steps/#the-name-tag), [`image:`](/docs/reference/yaml/steps/#the-image-tag), [`commands:`](/docs/reference/yaml/steps/#the-commands-tag), 
\ No newline at end of file
diff --git a/content/tour/steps.md b/content/tour/steps.md
index 246bde75d..b45f8422f 100644
--- a/content/tour/steps.md
+++ b/content/tour/steps.md
@@ -8,9 +8,9 @@ description: >
 
 A steps pipeline is designed to run a sequential set of tasks.
 
-These pipelines do not have a minimum defined length and steps will always execute in the order defined. 
+These pipelines do not have a minimum defined length and steps will always execute in the order defined.
 
-In this pipeline each step is shown with the minimum required YAML tags to execute a step. 
+In this pipeline each step is shown with the minimum required YAML keys to execute a step.
 
 Both steps are pulling a [Alpine Linux](https://alpinelinux.org/) image from [Docker Hub](https://hub.docker.com/) and executing echo statements.  
 
@@ -22,7 +22,6 @@ Both steps are pulling a [Alpine Linux](https://alpinelinux.org/) image from [Do
 * [Maven](/docs/usage/examples/java_maven/)
 * [Node](/docs/usage/examples/node/)
 
-
 <!-- section break -->
 
 ```yaml
@@ -53,6 +52,6 @@ $ vela exec pipeline
 ```
 <!-- section break -->
 
-**Tag references:**
+**Key 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),
+[`name:`](/docs/reference/yaml/steps/#the-name-key), [`image:`](/docs/reference/yaml/steps/#the-image-key), [`commands:`](/docs/reference/yaml/steps/#the-commands-key),
diff --git a/content/tour/templates.md b/content/tour/templates.md
index 9ae412955..a3ecb5dbe 100644
--- a/content/tour/templates.md
+++ b/content/tour/templates.md
@@ -10,7 +10,7 @@ Templates help to create reusable workflows in order to make grouping tasks like
 
 Templates can solve duplicative tasks in a single workflow or be leveraged by any number of pipelines to make reusable tasks across multiple workflows.
 
-In this pipeline each step is shown with the minimum required YAML tags to execute a step. 
+In this pipeline each step is shown with the minimum required YAML keys to execute a step.
 
 Both steps are pulling a [Alpine Linux](https://alpinelinux.org/) image from [Docker Hub](https://hub.docker.com/) and executing echo statements.  
 
@@ -41,6 +41,7 @@ steps:
 
 <!-- section break -->
 
-**Tag references:**
+**Key references:**
+
+[`templates:`](/docs/reference/yaml/templates), [`vars:`](/docs/reference/yaml/steps/#the-template-key),
 
-[`templates:`](/docs/reference/yaml/templates), [`vars:`](/docs/reference/yaml/steps/#the-template-tag), 
\ No newline at end of file
diff --git a/content/usage/environment.md b/content/usage/environment.md
index da31cba4e..444d21769 100644
--- a/content/usage/environment.md
+++ b/content/usage/environment.md
@@ -82,7 +82,7 @@ secrets:
 By default global injection affects all containers ran within the pipeline. However, if you only want some container types to receive the configuration you can limit which types get them by adding the `environment` declaration into the metadata.
 
 {{% alert title="Note:" color="primary" %}}
-Valid values for metadata `environment:` YAML tag are `steps`, `services` and `secrets`.
+Valid values for metadata `environment:` YAML key are `steps`, `services` and `secrets`.
 {{% /alert %}}
 
 ```diff
diff --git a/content/usage/open_id_connect.md b/content/usage/open_id_connect.md
index 6673b8644..05cd745bc 100644
--- a/content/usage/open_id_connect.md
+++ b/content/usage/open_id_connect.md
@@ -68,7 +68,7 @@ steps:
 
 In this example, the `get credentials` step is using the Vela environment values of `VELA_ID_TOKEN_REQUEST_TOKEN` and `VELA_ID_TOKEN_REQUEST_URL` to retrieve a short-lived ID token that can be used to authenticate with the cloud service, so long as that service has an OpenID processing layer.
 
-The `id_request` tag being set to _anything_ will result in the injection of the request environment variables. The value of `id_request` becomes a claim in the eventual ID token.
+The `id_request` key being set to _anything_ will result in the injection of the request environment variables. The value of `id_request` becomes a claim in the eventual ID token.
 
 ### ID Token Claims
 
diff --git a/content/usage/pull_policies.md b/content/usage/pull_policies.md
index 33047c32b..df38913af 100644
--- a/content/usage/pull_policies.md
+++ b/content/usage/pull_policies.md
@@ -76,4 +76,5 @@ The following [pipeline concepts](/docs/tour) are being used in the pipeline bel
 * [Secrets](/docs/tour/secrets/)
   * [Origin](/docs/tour/secrets/)
 
-* [`Pull` YAML Tag](/docs/reference/yaml/steps/#the-pull-tag)
\ No newline at end of file
+* [`Pull` YAML Key](/docs/reference/yaml/steps/#the-pull-key)
+
diff --git a/content/usage/repo_settings.md b/content/usage/repo_settings.md
index 313e1f1b2..d5979ade9 100644
--- a/content/usage/repo_settings.md
+++ b/content/usage/repo_settings.md
@@ -65,7 +65,7 @@ The four settings are:
 - **Require Admin Approval for First Time Contributors**: users that have contributed to the repository before will be able to run pull request builds without admin approval. Note: it may take a few hours for a user to be marked as a prior contributor after they have contributed to the repository.
 - **Never Require Approval**: any user will be able to run pull request builds by opening a PR against the repository.
 
-When a build is awaiting approval, the SCM will be updated with the status `pending` with the description `build needs approval from repo admin to run`. 
+When a build is awaiting approval, the SCM will be updated with the status `pending` with the description `build needs approval from repo admin to run`.
 
 Repository admins can approve a build in the UI or by using the [CLI](/docs/reference/cli/build/approve).
 
@@ -83,7 +83,7 @@ The Build Timeout setting determines the time limit for any given build for a re
 
 ### Build Counter
 
-This number is a tally of all builds that have ran for the repository. This number can be adjusted to be larger but _NOT_ smaller. 
+This number is a tally of all builds that have ran for the repository. This number can be adjusted to be larger but _NOT_ smaller.
 
 Occasionally, due to various compilation errors, this counter can fall behind resulting in a SQL collision error found in the audit page for new builds. To fix this, ensure the counter matches the actual build count.
 
@@ -111,7 +111,7 @@ Note: by default, templates are treated with `Go` syntax. In order to match that
 
 ## Pipeline Settings
 
-Below are high-level pipeline settings that are pulled directly from the `metadata` tag.
+Below are high-level pipeline settings that are pulled directly from the `metadata` key.
 
 ### Auto Cancel
 
@@ -122,7 +122,7 @@ metadata:
         default_branch: true
 ```
 
-Auto canceling builds is a build strategy that will prioritize the most recent status of the source code by canceling obsolete running/pending builds. More information can be found [here](/docs/reference/yaml/metadata/#the-auto_cancel-tag).
+Auto canceling builds is a build strategy that will prioritize the most recent status of the source code by canceling obsolete running/pending builds. More information can be found [here](/docs/reference/yaml/metadata/#the-auto_cancel-key).
 
 ### Render Inline
 
@@ -145,4 +145,4 @@ metadata:
     clone: false
 ```
 
-Setting the `clone` tag to `false` will override Vela's default behavior of cloning the repository at the start of the build. More information can be found [here](/docs/tour/cloning/).
+Setting the `clone` key to `false` will override Vela's default behavior of cloning the repository at the start of the build. More information can be found [here](/docs/tour/cloning/).
diff --git a/content/usage/stage_orchestration.md b/content/usage/stage_orchestration.md
index e308c088a..5c3e107ae 100644
--- a/content/usage/stage_orchestration.md
+++ b/content/usage/stage_orchestration.md
@@ -5,10 +5,11 @@ description: >
   Learn how to orchestrate pipelines with stages.
 ---
 
-This page will focus on [`stages`](/docs/tour/stages) and how to effectively leverage the orchestration options given to users. These options are: the [`ruleset`](/docs/tour/rulesets) tag, the [`needs`](/docs/reference/yaml/stages/#the-needs-tag) tag, and the [`independent`](/docs/reference/yaml/stages/#the-independent-tag) tag.
+This page will focus on [`stages`](/docs/tour/stages) and how to effectively leverage the orchestration options given to users. These options are: the [`ruleset`](/docs/tour/rulesets) key, the [`needs`](/docs/reference/yaml/stages/#the-needs-key) key, and the [`independent`](/docs/reference/yaml/stages/#the-independent-key) key.
 
 ### Step Rulesets in Stages
-To begin, let's focus on the `ruleset` tag. While this is not a tag at the stages level, each stage has a collection of steps, which can all be given rulesets. There are two kinds of rules within Vela: compile-time rules (path, event, branch, comment, tag, target, and repo) and a runtime rule (status). When Vela compiles a pipeline, it will purge any steps that do not meet the compile-time rules.
+
+To begin, let's focus on the `ruleset` key. While this is not a key at the stages level, each stage has a collection of steps, which can all be given rulesets. There are two kinds of rules within Vela: compile-time rules (path, event, branch, comment, tag, target, and repo) and a runtime rule (status). When Vela compiles a pipeline, it will purge any steps that do not meet the compile-time rules.
 
 For example, let's consider a pipeline written as such:
 
@@ -75,9 +76,9 @@ stages:
 
 Notice how the `deploy` stage has been pruned completely, rather than being a stage with empty steps. Further, since the `notify` stage normally waits on both `build` and `deploy`, in this situation, it only waits on `build`. The `notify` stage is still part of the build since its ruleset consists of only a runtime rule.
 
-### Understanding the `needs` tag
+### Understanding the `needs` key
 
-While there isn't a sure-fire way of running stages in order, the `needs` tag introduces a level of dependency that can be used to order stages. However the `needs` tag can become tricky when combined with pruning, as shown in the example above. Let's take a look at a theoretical pipeline:
+While there isn't a sure-fire way of running stages in order, the `needs` key introduces a level of dependency that can be used to order stages. However the `needs` key can become tricky when combined with pruning, as shown in the example above. Let's take a look at a theoretical pipeline:
 
 ```yaml
 version: "1"
@@ -131,7 +132,7 @@ stages:
 ```
 
 {{% alert title="Note:" color="info" %}}
-Be aware that `needs:` references stages by their name, which can be overridden by the `name` tag in the stage definition.
+Be aware that `needs:` references stages by their name, which can be overridden by the `name` key in the stage definition.
 {{% /alert %}}
 
 Consider a Vela build triggered by a `push` to `main`. We know that `run-first` will indeed run first, followed by `runtime-ruleset-stage` since it cannot be pruned due to its runtime rule. However, if we recall from our first example, when the _entirety_ of a stage's step collection is pruned at compile-time, the stage disappears completely:
@@ -177,13 +178,13 @@ stages:
           - echo $VELA_REPO_FULL_NAME
 ```
 
-So in fact, in this scenario, the `run-first` stage and the `y-stage` begin simultaneously, even though `y-stage` "needed" `compile-time-ruleset-stage` which "needed" `run-first` in the original pipeline. 
+So in fact, in this scenario, the `run-first` stage and the `y-stage` begin simultaneously, even though `y-stage` "needed" `compile-time-ruleset-stage` which "needed" `run-first` in the original pipeline.
 
 ### Leveraging Stage independence
 
 With the increasing popularity of monorepos, some Vela pipelines may want to simultaneously execute very different build flows based on modules within the repository. Since by nature Vela stages will skip the remainder of the build if a single stage fails its pipeline, this could potentially cause issues, such as half-done deployments.
 
-For example, say we have a repo that has back-end _and_ front-end code written together. Let's assume all the back-end code is in `org/repo/back-end` and the front-end code is in `org/repo/front-end`. We can leverage the [`path`](/docs/reference/yaml/steps/#the-ruleset-tag) ruleset with the [`independent`](/docs/reference/yaml/stages/#the-independent-tag) stage tag to compartmentalize Vela builds:
+For example, say we have a repo that has back-end _and_ front-end code written together. Let's assume all the back-end code is in `org/repo/back-end` and the front-end code is in `org/repo/front-end`. We can leverage the [`path`](/docs/reference/yaml/steps/#the-ruleset-key) ruleset with the [`independent`](/docs/reference/yaml/stages/#the-independent-key) stage key to compartmentalize Vela builds:
 
 ```yaml
 version: "1"
@@ -259,7 +260,7 @@ stages:
           - node build
 ```
 
-We can extend this example to deployments, and it's easy to see where a team may want one module to complete its build flow even if there's a failure in another module. 
+We can extend this example to deployments, and it's easy to see where a team may want one module to complete its build flow even if there's a failure in another module.
 
 ### In Summary