Docs: correct GitOps mode label editing behavior and document exceptions - #50552
Merged
Conversation
Two pages stated that GitOps mode does not restrict label editing in the UI. Since 4.84 that is only true when the labels exception is enabled. Resolves #50551
Contributor
There was a problem hiding this comment.
Copilot wasn't able to review any files in this pull request.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Omitting the labels key deletes existing labels unless the labels exception is enabled (see computeLabelChanges). The previous text said omission preserved them, which stopped being true in #42191.
rachaelshaw
approved these changes
Aug 6, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Related issue: Resolves #50551
Two published pages still describe pre-4.84 behavior, telling users that GitOps mode doesn't restrict label editing in the UI. Since 4.84 that's only true when the labels exception is enabled. This PR corrects both pages and documents the exceptions framework.
docs/Configuration/yaml-files.mdlabelssection: rewrote the note around the two exception states. Beyond the sentence the issue flagged, the premise it rested on was also stale: the note said omitting thelabelskey leaves existing labels intact. Since Enforce GitOps exceptions #42191,computeLabelChanges(cmd/fleetctl/fleetctl/gitops.go:947) branches onlen(specifiedLabels) == 0, so omitting the key deletes every custom label in that scope unless the labels exception is enabled. Its own tests name this behavior ("labels omitted removes all regular labels when not excepted"). The note now spells out both states and fixes alabel/labelstypo.gitopssection: added a note that exceptions can't be set in YAML.Client.DoGitOpsstrips theexceptionskey defensively (server/service/client.go:726), so this was worth stating explicitly.articles/gitops-mode.mdfleetctl gitops, and the enroll secrets default. Upgrade behavior is left to the release notes. It notes that exceptions affectfleetctl gitopswhether or not GitOps mode is on, since neither the apply-path check norcomputeLabelChangesreadsgitops_mode_enabled.Behavior the docs now match:
GitOpsModeTooltipWrapperwithentityType="labels"(frontend/pages/labels/components/LabelForm/LabelForm.tsx:172,NewLabelPage.tsx:676,HostsFilterBlock.tsx:223).useGitOpsModetreats an enabled exception as GitOps mode being off for that entity.server/service/client.go:2219-2242(premium only).server/fleet/app.go:1216for new installs, migration20260323144117_AddGitOpsExceptionsToAppConfig.gofor upgrades.The backend is unchanged and was already correct.
ModifyLabelapplies no GitOps check, and the per-host label endpoints stay available regardless of GitOps mode or exception state, so this PR is docs-only.Checklist for submitter
changes/,orbit/changes/oree/fleetd-chrome/changes.Not applicable: documentation-only change, no product behavior change.
Testing
Verified the described behavior against the UI gating, the
fleetctl gitopsapply path, and the exception defaults in code (references above).