<!-- Add the related story/sub-task/bug number, like Resolves#123, or
remove if NA -->
**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.md`**
- `labels` section: 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 the `labels` key leaves existing labels
intact. Since #42191, `computeLabelChanges`
(`cmd/fleetctl/fleetctl/gitops.go:947`) branches on
`len(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 a
`label` / `labels` typo.
- `gitops` section: added a note that exceptions can't be set in YAML.
`Client.DoGitOps` strips the `exceptions` key defensively
(`server/service/client.go:726`), so this was worth stating explicitly.
**`articles/gitops-mode.md`**
- Added an "Exceptions" section covering the three exception types, what
an exception does to both the UI and `fleetctl gitops`, and the enroll
secrets default. Upgrade behavior is left to the release notes. It notes
that exceptions affect `fleetctl gitops` whether or not GitOps mode is
on, since neither the apply-path check nor `computeLabelChanges` reads
`gitops_mode_enabled`.
- "Still available" no longer lists "Add and edit labels"
unconditionally. It now points at the exceptions section for labels,
software, and enroll secrets.
Behavior the docs now match:
- UI gating is `GitOpsModeTooltipWrapper` with `entityType="labels"`
(`frontend/pages/labels/components/LabelForm/LabelForm.tsx:172`,
`NewLabelPage.tsx:676`, `HostsFilterBlock.tsx:223`). `useGitOpsMode`
treats an enabled exception as GitOps mode being off for that entity.
- Apply-path enforcement is in `server/service/client.go:2219-2242`
(premium only).
- Defaults: `server/fleet/app.go:1216` for new installs, migration
`20260323144117_AddGitOpsExceptionsToAppConfig.go` for upgrades.
The backend is unchanged and was already correct. `ModifyLabel` applies
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
- [x] Changes file added for user-visible changes in `changes/`,
`orbit/changes/` or `ee/fleetd-chrome/changes`.
Not applicable: documentation-only change, no product behavior change.
## Testing
- [x] QA'd all new/changed functionality manually
Verified the described behavior against the UI gating, the `fleetctl
gitops` apply path, and the exception defaults in code (references
above).
Related to: [#25943](https://github.com/fleetdm/fleet/issues/25943)
Changes:
- Updated filenames of images in the website/assets/images/articles/
folder to match website naming conventions
- Updated links to images in articles.
kitzy