Labels

Overview

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.

updatecli.yaml

name: "docs: update Golang version throughout the documentation"

# Pipeline labels: key/value pairs used to filter and organize pipelines in Updatecli and Udash.
labels:
  ecosystem: golang

actions:
  default:
    kind: github/pullrequest
    spec:
      # PR labels: applied to the pull request on the SCM (e.g. GitHub). Different from pipeline labels above.
      labels:
        - dependencies

These labels can be used for two main purposes:

Filtering pipeline execution — Use labels to run only specific pipelines matching given criteria.
For example, only apply pipelines tagged with ecosystem: golang:
```
updatecli compose apply --labels="ecosystem:golang"
```
Pipelines matching the filter will execute. Pipelines without the label or with a different value will be skipped.
Filtering pipeline reports in Udash

Naming Conventions

Use descriptive, lowercase keys that identify a dimension. Here are common patterns:

By Ecosystem or Dependency

labels:
  ecosystem: golang

Pipelines with --labels="ecosystem:golang" will match. Pipelines without that label or with a different value will be skipped.

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.

By Team or Domain

labels:
  team: backend
  domain: infrastructure

By Policy Type

labels:
  policy: autodiscovery

By Environment

labels:
  environment: staging
  approval: required

By Monitor Mode

Use monitor to signal how urgently a pipeline should be executed.

# Always run — detect updates as soon as possible
labels:
  monitor: active

# Run periodically — some drift is acceptable
labels:
  monitor: passive

# Intentionally frozen — assert this version stays locked
labels:
  monitor: pinned

# Human-triggered only — never run in automated CI
labels:
  monitor: manual

To avoid

Too generic to be useful

update, dependency, pipeline — these describe what Updatecli does by definition; they add no filtering value.

Free-form / inconsistent spellings

Mixing github-actions, GithubActions, github_actions — pick one convention (kebab-case is common) and stick to it. Inconsistency breaks filtering.

Status-like labels

done, pending, failed — Updatecli and Udash already track state natively; encoding status in labels leads to stale metadata.

Highly volatile values

version:1.2.3 — versions change constantly; labels should be stable identifiers, not point-in-time values.

Overly broad owner labels without structure

john, alice — person names become stale when teams change. Prefer team: or squad: prefixes.

Pull request labels in pipeline labels

dependencies, automerge, bug — these are pull request labels and belong in action.spec.labels, not in the pipeline labels field. They are applied to the SCM pull request (GitHub, GitLab, etc.) and have no effect on pipeline filtering or Udash dashboards. See Actions for the correct location.

By CI/CD platform or integration

These labels should be avoided: the risk is executing pipelines outside the expected CI/CD platform. If needed, this information can be detected at runtime. Feel free to open an issue or a PR to implement this feature.

Conclusion

Labels are a powerful tool for organizing and filtering pipelines, but they require thoughtful design to be effective. Use clear, consistent naming conventions that reflect stable dimensions of your projects, teams, and policies.

Last modified on March 23, 2026

Edit this page on GitHub