Labels

GitOps Promoter controllers set Kubernetes labels to associate resources, filter CommitStatus objects during promotion checks, and tie child objects back to their owning gate or policy. Label keys for built-in behavior are defined as constants in api/v1alpha1/constants.go. Gate controllers also use derived parent-gate label keys (see below).

Note

Branch names and other free-form strings are passed through utils.KubeSafeLabel() before they are stored as label values (slashes become hyphens, length is capped at 63 characters). When debugging, compare the label value to the sanitized form, not always the raw branch string from your spec.

Label reference

Promotion and change transfer

Label key	Kind(s)	Set by	Value	Purpose
`promoter.argoproj.io/promotion-strategy`	`ChangeTransferPolicy`, `PullRequest`	PromotionStrategy / ChangeTransferPolicy controllers	`KubeSafeLabel` of the owning `PromotionStrategy` name	Links CTPs and PRs to a promotion strategy; used to list and correlate objects per strategy.
`promoter.argoproj.io/environment`	`ChangeTransferPolicy`, `PullRequest`	PromotionStrategy, ChangeTransferPolicy controllers	`KubeSafeLabel` of the environment branch (for example `environment/development` → `environment-development`)	Identifies which environment branch the object applies to. (Also the second standard label on gate-created `CommitStatus`; see CommitStatus gating.)
`promoter.argoproj.io/change-transfer-policy`	`PullRequest`	ChangeTransferPolicy controller	`KubeSafeLabel` of the owning `ChangeTransferPolicy` name	Finds PRs for a specific CTP.

ChangeTransferPolicy objects receive promotion-strategy and environment when the PromotionStrategy controller creates or updates them. PullRequest objects receive all three labels when the ChangeTransferPolicy controller creates or updates them.

CommitStatus gating

Built-in gate controllers set three standard labels on each CommitStatus via utils.CommitStatusStandardLabels(parent, branch, key):

Label key	Value	Purpose
`promoter.argoproj.io/commit-status`	Gate `spec.key` (for example `argocd-health`, `timer`)	Must match the `key` in `PromotionStrategy` `activeCommitStatuses` or `proposedCommitStatuses`. ChangeTransferPolicy lists CommitStatuses by this label plus `.spec.sha`.
`promoter.argoproj.io/environment`	`KubeSafeLabel` of the environment branch	Identifies which environment branch this status applies to.
`promoter.argoproj.io/<gate-stem>-commit-status`	`KubeSafeLabel` of the parent gate CR name	Parent-gate label for orphan cleanup and ownership correlation. Key is derived from the parent Kind (see table below).

Built-in parent-gate label keys (derived from Kind):

Parent gate Kind	Label key
`TimedCommitStatus`	`promoter.argoproj.io/timed-commit-status`
`ArgoCDCommitStatus`	`promoter.argoproj.io/argo-cd-commit-status`
`WebRequestCommitStatus`	`promoter.argoproj.io/web-request-commit-status`
`GitCommitStatus`	`promoter.argoproj.io/git-commit-status`

The prefix promoter.argoproj.io/ is CommitStatusGateLabelPrefix; the middle segment is a kebab-case stem from the Kind (for example ArgoCDCommitStatus → argo-cd). Custom gate controllers should use the same pattern; see Commit Status Controller Best Practices.

Special key: promoter-previous-environment (PreviousEnvironmentCommitStatusKey) is used only on CommitStatuses created by the PromotionStrategy controller to represent the previous environment’s aggregate health on the proposed branch. Those objects typically carry only promoter.argoproj.io/commit-status, not a parent-gate label.

Annotation key	Kind(s)	Purpose
`promoter.argoproj.io/previous-environment-statuses`	`CommitStatus` (`promoter-previous-environment`)	YAML map of contributing commit-status keys and phases used to build the aggregated previous-environment status.

Integration labels (user- or operator-set)

Label key	Resource	Purpose
`promoter.argoproj.io/has-promotionstrategy`	Argo CD `Application`	When set to `"true"`, shows the GitOps Promoter UI extension tab even if no top-level `PromotionStrategy` appears in the application tree. Documented in Argo CD Integrations.

This label is not defined in constants.go; it is a convention for Argo CD Application metadata.

How controllers use labels

ChangeTransferPolicy evaluates activeCommitStatuses and proposedCommitStatuses by listing CommitStatus resources with promoter.argoproj.io/commit-status=<key> and field-selecting on .spec.sha.
Gate controllers (Argo CD, timed, web request, git commit) set all three standard labels via utils.CommitStatusStandardLabels(parent, branch, key) and use the parent-gate label when cleaning up orphaned CommitStatuses.
PromotionStrategy lists ChangeTransferPolicy objects with promoter.argoproj.io/promotion-strategy=<strategy> to remove orphaned policies when environments change.

Useful queries

List CommitStatuses for a gate key and inspect labels:

kubectl get commitstatus -A -l promoter.argoproj.io/commit-status=argocd-health
kubectl get commitstatus <name> -n <namespace> -o jsonpath='{.metadata.labels}' | jq .

List CommitStatuses owned by a TimedCommitStatus gate:

kubectl get commitstatus -n <namespace> -l promoter.argoproj.io/timed-commit-status=<gate-name>

List ChangeTransferPolicies for a promotion strategy:

kubectl get changetransferpolicy -n <namespace> -l promoter.argoproj.io/promotion-strategy=<strategy-name>

List PullRequests for a change transfer policy:

kubectl get pullrequest -n <namespace> \
  -l promoter.argoproj.io/change-transfer-policy=<ctp-name>,promoter.argoproj.io/promotion-strategy=<strategy-name>

Troubleshooting

Promotion blocked but CommitStatus looks correct

Confirm promoter.argoproj.io/commit-status on the CommitStatus equals the key in the PromotionStrategy (or CTP) selector—not only spec.name in the SCM.
Confirm .spec.sha matches the hydrated SHA the ChangeTransferPolicy is checking (labels do not include SHA; the controller field-selects on spec).
For gate-created statuses, confirm all three standard labels are present (commit-status, environment, and the parent-gate key) and that the parent-gate value points at the expected gate CR name (upgrades from older releases may lack parent-gate labels until the gate reconciles; Argo CD has additional legacy orphan cleanup—see Roadmap).

Label value does not match the branch in YAML

Branch labels use KubeSafeLabel (for example environment/staging → environment-staging). Use the sanitized value in -l selectors.

Missing labels on CommitStatus

If a third party creates CommitStatus objects by hand, they must set at least promoter.argoproj.io/commit-status (and usually promoter.argoproj.io/environment) or the ChangeTransferPolicy controller will not find them. Built-in gates set all three standard labels automatically via CommitStatusStandardLabels.

Reporting a bug: labels missing or wrong

Which object — Kind, name, namespace, and controller version / chart version.
Expected vs actual labels — kubectl get <kind> <name> -n <namespace> -o yaml (redact secrets), focusing on metadata.labels and relevant spec (branch, key, sha).
Owning gate or policy — Name of the ArgoCDCommitStatus, TimedCommitStatus, WebRequestCommitStatus, GitCommitStatus, PromotionStrategy, or ChangeTransferPolicy involved.
Controller logs — gitops-promoter manager logs around the reconcile window; related kubectl get events.
Open an issue on argoproj-labs/gitops-promoter with the label keys/values you expected and what you see instead.

For implementing custom gate controllers, see Development Best Practices. For how commit statuses drive promotion, see Gating Promotions.