Document job and step-level tags

docs/docs/jobs.md

@@ -173,6 +173,19 @@ A pipeline's jobs are listed under [`pipeline.jobs`](pipelines/index.md#pipeline
     worker to finish before exiting. If this value is set to `true`, the worker will not wait on the builds of this job.
     You may want this if you have a self-deploying Concourse or long-running-but-low-importance jobs.
 
+??? info "`tags`: [`[string]`](config-basics.md#string-schema)"
+
+    ### `tags`
+    _⚠️ Only in v8.3.0 or higher_
+
+    _Default `[]`_. The tags by which to match workers. All steps and `on_*`
+    hook steps for the job will be placed within the pool of workers that match
+    all the given set of tags.
+
+    Child steps can override these `tags` with their own set of `tags`. Tags
+    cannot be cleared by child steps though. You'll need to create a more
+    granular job plan if you want certain steps to remain untagged.
+
 ### Job Hooks
 
 ??? info "`on_success`: [`step`](steps/index.md)"

docs/docs/steps/modifier-and-hooks/tags.md

@@ -13,6 +13,14 @@ title: Tags Step Modifier
     For example, if `[a, b]` is specified, only workers advertising the a and b
     tags (in addition to any others) will be used for running the step.
 
+    #### ⚠️ Only in v8.3.0 or higher:
+    When used with the `do` or `in_parallel` steps, all child steps will
+    receive the `tags` of the parent step.
+
+    Child steps can override these `tags` with their own set of `tags`. Tags
+    cannot be cleared by child steps though. You'll need to create a more
+    granular job plan if you want certain steps to remain untagged.
+
 ---
 
 ???+ example "Running in a private network"
@@ -24,13 +32,30 @@ title: Tags Step Modifier
     ```yaml
     plan:
       - get: my-repo
+      - task: acceptance-tests
+        tags:
+          - private
+        file: my-repo/ci/acceptance.yml
       - put: my-site
         tags:
           - private
         params:
           path: my-repo
-      - task: acceptance-tests
-        tags:
-          - private
-        file: my-repo/ci/acceptance.yml
+    ```
+
+???+ example "Tagging multiple steps"
+
+    If you have multiple steps to tag you can easily tag them all using `do` or
+    `in_parallel`.
+
+    ```yaml
+    plan:
+      - tags: ["private"]
+        do:
+          - get: my-repo
+          - task: acceptance-tests
+            file: my-repo/ci/acceptance.yml
+          - put: my-site
+            params:
+              path: my-repo
     ```