kitzy
5d8f7e26e1
<!-- 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).
49 lines
2.5 KiB
Markdown
49 lines
2.5 KiB
Markdown
# GitOps mode
|
|
|
|
_Available in Fleet Premium_
|
|
|
|
GitOps mode helps users avoid unexpected changes by preventing manual updates of [GitOps-configurable features](https://fleetdm.com/docs/configuration/yaml-files) in the UI.
|
|
|
|
For example, if a user in the Fleet UI adds a report and then GitOps runs, the report will be deleted.
|
|
GitOps mode helps avoid this by preventing the user from saving or editing the report in the first place:
|
|
|
|
|
|
|
|
## Enabling
|
|
To turn GitOps mode on or off, navigate to **Settings** > **Integrations** > **Change management**:
|
|
|
|
|
|
|
|
## Exceptions
|
|
|
|
Exceptions let you opt a resource out of GitOps mode, so you can manage that resource in the Fleet UI while everything else stays in git. Under **Settings** > **Integrations** > **Change management**, you can add an exception for labels, software, or enroll secrets.
|
|
|
|
When a resource has an exception, three things happen:
|
|
- The Fleet UI stays editable for that resource, even with GitOps mode on.
|
|
- `fleetctl gitops` leaves your existing labels, software, or enroll secrets intact. Without the exception, omitting the key deletes them.
|
|
- `fleetctl gitops` fails if your YAML includes that resource's key. The error tells you to remove the key or disable the exception. This keeps the UI and git from overwriting each other.
|
|
|
|
Exceptions apply to `fleetctl gitops` whether or not GitOps mode is turned on.
|
|
|
|
Fleet enables the enroll secrets exception by default.
|
|
|
|
## Still available
|
|
|
|
GitOps mode prevents the UI user from editing [GitOps-configurable features](https://fleetdm.com/docs/configuration/yaml-files). They will still be able to, for example:
|
|
- Read any data presented in the UI
|
|
- Add and edit users
|
|
- Run live queries
|
|
- Add and edit labels, software, or enroll secrets, if that resource has an [exception](#exceptions)
|
|
|
|
## More
|
|
<!-- TODO - update to link to Allen's article, uncomment -->
|
|
<!-- - [Why use GitOps to configure Fleet?](https://www.example.com) -->
|
|
- [Preventing Mistakes with GitOps](https://fleetdm.com/guides/preventing-mistakes-with-gitops)
|
|
|
|
<meta name="articleTitle" value="GitOps mode">
|
|
<meta name="authorFullName" value="Jacob Shandling">
|
|
<meta name="authorGitHubUsername" value="jacobshandling">
|
|
<meta name="publishedOn" value="2025-03-21">
|
|
<meta name="category" value="guides">
|
|
<meta name="description" value="Help users avoid unexpected changes by preventing manual updates of GitOps-configurable features">
|