GitOps mode in the UI

[rachaelshaw]

Goal

User story
As a GitOps user,
I want to access the Fleet UI in a mode that disables any kind of edit you can do in GitOps
so that I can avoid my work being undone the next time fleetctl gitops runs.

Key result

GitOps mode in the Fleet UI

Original requests

• Read-only GitOps mode #25520

Context

• Product designer: @rachaelshaw

Changes

Product

• UI changes: Figma
• CLI (fleetctl) usage changes: No changes
• YAML changes: No changes
• REST API changes: PR PR
• Fleet's agent (fleetd) changes: No changes
• GitOps mode changes: No other changes. See the Figma wireframes here for GitOps mode changes.
• Activity changes: Draft PR
• Permissions changes: Only admins can edit the GitOps mode setting. (No changes to docs necessary.)
• Changes to paid features or tiers: Fleet Premium
• Transparency changes: No changes
• First draft of test plan added
• Other reference documentation changes: Update fleet-gitops README
• Once shipped, requester has been notified
• Once shipped, dogfooding issue has been filed: https://github.com/fleetdm/confidential/issues/9958

Engineering

• Test plan is finalized
• Feature guide changes: Yes. Need to add a guide for that. Find an existing guide for GitOps or write a new one for this feature.
• Database schema migrations: No need
• Load testing: No need

ℹ️  Please read this issue carefully and understand it. Pay special attention to UI wireframes, especially "dev notes".

QA

Risk assessment

• Requires load testing: No need
• Risk level: Medium
• Risk description: This is a massive frontend change. Could create bugs. Test-plan should address this risk.

Test plan

1. Enable GitOps mode from Settings > Integrations
   • Attempt to save without entering a repo URL. Should see a validation error.
   • Enter a repo URL and save.
2. Go through each item in the Configuration > YAML files docs. (These are the items that can be edited via GitOps.)
   • For each item, find the corresponding place in the UI to edit, and make sure it is disabled in GitOps mode.
   • Verify that the tooltip is readable (not cut off e.g. at the bottom of tables, in modals, etc.)
   • Verify that you can easily hover over the link (tooltip doesn't disappear before you hover over the link)
   • Verify that clicking the link navigates to the saved repository URL.
     • Note that this field is intentionally flexible - if a user saves a relative URL e.g. "a.b.cc", it will navigate to <current_domain>/a.b.cc. If a full path is provided, e.g. "https://a.b.cc", it will navigate accordingly.

Testing notes

Confirmation

1. Engineer: Added comment to user story confirming successful completion of test plan.
2. QA: Added comment to user story confirming successful completion of test plan.

[nonpunctual]

https://fleetdm.slack.com/archives/C044WQFPRCH/p1737043329013419

[noahtalerman]

Hey @rachaelshaw, I took a look at your early wireframes and recorded some feedback in a video here.

[iansltx]

Couple quick thoughts, one on where this could be turned on/off to minimize chances of someone bumping it by accident, one on temporary removal of GitOps mode.

Maybe it makes sense to have this toggle not in the UI, instead being a setting in YAML next to the other global config settings. That way, to push the system into GitOps mode you have to know how to run GitOps, so that's less chance of folks locking themselves out. Plus add a way to turn GitOps Mode off via fleetctl as a failsafe in case someone runs things via GitOps and then deletes the repo. Same underlying endpoint, just like with other global config.

For an override, maybe we throw a git icon top-right next to the user profile icon when a global admin is in the UI and gitOps mode is turned on. Clicking the icon shows a quick explanation for GitOps Mode, plus a button (potentially leading to a confirmation modal) to temporarily disable GitOps Mode for the rest of that user's session. We can throw a flag in sessionStorage to effect this override, and having one place to do the override should keep e.g. tooltips in the UI tidy.

[noahtalerman]

@sharon-fdm just a reminder that we want to prioritize this user story in the upcoming sprint.

Can you please complete the TO-DOs in the "Engineering" section so we can estimate with the team during #g-orchestration sprint kickoff?

[sharon-fdm]

@noahtalerman, Yes. We will put this on the front burner today and take it into the new sprint.

[sharon-fdm]

Please add your planning poker estimate with Zenhub @jacobshandling

[jacobshandling]

@rachaelshaw thanks for the diligent spec work here!

Since we are developing and updating specs in-flight, and since the designs are so wide-reaching, please ping me whenever you make updates to the Figma so I can be sure to note and get to implementing every added spec / change.

So far I see specs added since estimation for Disk encryption, New query, and Edit query sections, and want to be sure I don't miss anything.

[jacobshandling]

@rachaelshaw seems like we'll want to gate the Add and Edit users tables as well, since users can be added/removed from teams there:

Please confirm and note in this issue, thanks!

cc @sgress454

[sgress454]

Makes sense to me!

[jacobshandling]

Confirming the test plan in the description 👍

[fleet-release]

GitOps mode ascends,
Unfurls like cloud city spires,
Edits find their end.

[lukeheath]

@jacobshandling @sharon-fdm This story shipped without a guide. It was listed in the engineering TODOs but looks like it never translated to a sub-task. I think this is probably a update of our existing GitOps guide to call out that GitOps Mode exists in the UI.

@allenhouchins is a good resource on how we should document this.

[jacobshandling]

Thanks for the heads up @lukeheath

[sharon-fdm]

@jacobshandling, Gitops guide

[noahtalerman]

What goes in the guide?

• How to turn on/off
• What's still enabled in the UI when GitOps mode is on? https://fleetdm.com/docs/configuration/yaml-files

[noahtalerman]

@jacobshandling here's our stubbed out article: #27368

[noahtalerman]

Guide is merged! Thanks @jacobshandling :)

#27414

[fleet-release]

GitOps mode takes flight,
Work saved, not undone at night,
Peace in coder's sight.