Skip to content

Commit 9595121

Browse files
olblakolblak
authored
feat: add label doc (#2764)
* feat: add label doc Signed-off-by: Olblak <me@olblak.com> * chore: update label suggestion Signed-off-by: Olblak <me@olblak.com> --------- Signed-off-by: Olblak <me@olblak.com>
1 parent d5244c2 commit 9595121

1 file changed

Lines changed: 165 additions & 0 deletions

File tree

‎content/en/docs/core/label.adoc‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
---
2+
title: "Labels"
3+
description: "Label Updatecli policies"
4+
draft: false
5+
images: []
6+
menu:
7+
docs:
8+
parent: "core"
9+
weight: 130
10+
toc: true
11+
---
12+
// <!-- Required for asciidoctor -->
13+
:toc:
14+
// Set toclevels to be at least your hugo [markup.tableOfContents.endLevel] config key
15+
:toclevels: 4
16+
17+
== Overview
18+
19+
Pipeline labels are arbitrary key/value pairs attached to a pipeline manifest that allow you to categorize, organize, and filter pipelines during execution and reporting.
20+
21+
.updatecli.yaml
22+
[source,yaml]
23+
----
24+
name: "docs: update Golang version throughout the documentation"
25+
26+
# Pipeline labels: key/value pairs used to filter and organize pipelines in Updatecli and Udash.
27+
labels:
28+
ecosystem: golang
29+
30+
actions:
31+
default:
32+
kind: github/pullrequest
33+
spec:
34+
# PR labels: applied to the pull request on the SCM (e.g. GitHub). Different from pipeline labels above.
35+
labels:
36+
- dependencies
37+
----
38+
39+
These labels can be used for two main purposes:
40+
41+
1. **Filtering pipeline execution** — Use labels to run only specific pipelines matching given criteria.
42+
+
43+
For example, only apply pipelines tagged with `ecosystem: golang`:
44+
+
45+
[source,bash]
46+
----
47+
updatecli compose apply --labels="ecosystem:golang"
48+
----
49+
+
50+
Pipelines matching the filter will execute. Pipelines without the label or with a different value will be skipped.
51+
52+
2. **Filtering pipeline reports** in link:https://github.com/updatecli/udash/[Udash]
53+
54+
== Naming Suggestion
55+
56+
Use descriptive, lowercase keys that identify a dimension. Here are common patterns:
57+
58+
=== By Ecosystem or Dependency
59+
60+
[source,yaml]
61+
----
62+
labels:
63+
ecosystem: golang
64+
----
65+
66+
Pipelines with `--labels="ecosystem:golang"` will match. Pipelines without that label or with a different value will be skipped.
67+
68+
Pipelines with `--labels="ecosystem:"` will match all pipelines with an `ecosystem` label, regardless of its value. Pipelines without that label or with a different value will be skipped.
69+
70+
=== By Team or Domain
71+
72+
[source,yaml]
73+
----
74+
labels:
75+
team: backend
76+
domain: infrastructure
77+
----
78+
79+
=== By Policy Type
80+
81+
[source,yaml]
82+
----
83+
labels:
84+
policy: autodiscovery
85+
----
86+
87+
=== By Environment
88+
89+
[source,yaml]
90+
----
91+
labels:
92+
environment: staging
93+
approval: required
94+
----
95+
96+
=== By Monitor Mode
97+
98+
Use `monitor` to signal how urgently a pipeline should be executed.
99+
100+
[source,yaml]
101+
----
102+
# Always run — detect updates as soon as possible
103+
labels:
104+
monitor: active
105+
----
106+
107+
[source,yaml]
108+
----
109+
# Run periodically — some drift is acceptable
110+
labels:
111+
monitor: passive
112+
----
113+
114+
[source,yaml]
115+
----
116+
# Intentionally frozen — assert this version stays locked
117+
labels:
118+
monitor: pinned
119+
----
120+
121+
[source,yaml]
122+
----
123+
# Human-triggered only — never run in automated CI
124+
labels:
125+
monitor: manual
126+
----
127+
128+
== To avoid
129+
130+
=== Too generic to be useful
131+
132+
update, dependency, pipeline — these describe what Updatecli does by definition; they add no filtering value.
133+
134+
=== Free-form / inconsistent spellings
135+
136+
Mixing github-actions, GithubActions, github_actions — pick one convention (kebab-case is common) and stick to it. Inconsistency breaks filtering.
137+
138+
=== Status-like labels
139+
140+
done, pending, failed — Updatecli and Udash already track state natively; encoding status in labels leads to stale metadata.
141+
142+
=== Highly volatile values
143+
144+
version:1.2.3 — versions change constantly; labels should be stable identifiers, not point-in-time values.
145+
146+
=== Overly broad owner labels without structure
147+
148+
john, alice — person names become stale when teams change. Prefer `team:` or `squad:` prefixes.
149+
150+
=== Pull request labels in pipeline labels
151+
152+
`dependencies`, `automerge`, `bug` — these are pull request labels and belong in `action.spec.labels`, not in the pipeline `labels` field.
153+
They are applied to the SCM pull request (GitHub, GitLab, etc.) and have no effect on pipeline filtering or Udash dashboards.
154+
See link:/docs/core/action[Actions] for the correct location.
155+
156+
=== By CI/CD platform or integration
157+
158+
These labels should be avoided: the risk is executing pipelines outside the expected CI/CD platform.
159+
If needed, this information can be detected at runtime. Feel free to open an issue or a PR to implement this feature.
160+
161+
== Conclusion
162+
163+
Labels are a powerful tool for organizing and filtering pipelines, but they require thoughtful design to be effective.
164+
Use clear, consistent naming conventions that reflect stable dimensions of your projects, teams, and policies.
165+

0 commit comments

Comments
 (0)