From 2dba119c5a425748e6e98cce808da922a08d5a9b Mon Sep 17 00:00:00 2001 From: Taylor Silva Date: Wed, 17 Jun 2026 17:02:15 -0400 Subject: [PATCH] document job and step-level tags Signed-off-by: Taylor Silva --- docs/docs/jobs.md | 13 +++++++++ docs/docs/steps/modifier-and-hooks/tags.md | 33 +++++++++++++++++++--- 2 files changed, 42 insertions(+), 4 deletions(-) diff --git a/docs/docs/jobs.md b/docs/docs/jobs.md index c2036aefe..20e207756 100644 --- a/docs/docs/jobs.md +++ b/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)" diff --git a/docs/docs/steps/modifier-and-hooks/tags.md b/docs/docs/steps/modifier-and-hooks/tags.md index 6f3fb237b..b5e31d002 100644 --- a/docs/docs/steps/modifier-and-hooks/tags.md +++ b/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 ```