APRF: Documentation follow-up and engineering QA

[cdcme]

Related user story

#38504

Task

Updated 2026-06-12: docs PR #47274 has merged. The remaining docs work is a small follow-up against docs-v4.88.0 plus the audit-log + feature-guide updates. QA scope has expanded to 13 steps covering the new Library section, the Versions modal, and the Policies modal.

Final-gate sub-issue. Land the remaining docs and run end-to-end QA on a real device once the implementation PRs in #46726 and #46727 have merged.

1. REST API docs follow-up

PR #47274 (merged) added the version body parameter on PATCH /api/v1/fleet/software/titles/:id/package. Open a small follow-up PR against docs-v4.88.0 to:

• Document the extended GET /api/v1/fleet/software/titles/:id response. New fields under software_package:
  • pinned_version — string or null. null for Latest (auto-update), a literal version string for a specific pin, or a caret string like "^147" for a major-version pin.
  • fleet_maintained_versions — array of {version: string, is_active: bool, added_at: timestamp} (final field names per the implementation in APRF: Extend PATCH .../package with version, extend GET response #46726).
• Reconcile the version parameter description against the shipped UI. PR [API changes] Auto update, pin, and rollback Fleet-maintained apps via UI/API  #47274 currently says "Available versions are listed in the Fleet UI under Actions > Edit software" but the Figma Actions dropdown shows Versions as a distinct item from Edit software. Confirm with @marko-lisica which is correct, and update the doc to match.

2. Audit log reference

Update docs/Contributing/reference/audit-logs.md for the edited_software activity:

• Document the new pinned_version field with string or null semantics.
• Add an example payload showing pinned_version: "149.0.7827.54" (literal pin), pinned_version: "^147" (caret major), and pinned_version: null (Latest / unpinned).

3. Feature guide

Update articles/fleet-maintained-apps.md (published at https://fleetdm.com/guides/fleet-maintained-apps):

• Replace the existing "Update the app" delete-and-re-add instructions.
• Add an Auto-update section describing the default behavior (Latest).
• Add a Pin a version section covering both:
  • The UI workflow: Actions > Versions → pick a specific or major-version radio → Save.
  • The GitOps workflow: set version: under the FMA entry (already supported since 4.82).
• Add a Roll back section pointing readers to the same UI/API ("pin to the older version") with a callout that hosts already running the newer version will downgrade.
• Cross-link to the PATCH /api/v1/fleet/software/titles/:id/package REST docs.
• Remember: per the team's docs convention, this PR targets the docs-v4.88.0 branch, not main. Do not bundle into a code PR.

4. Engineering QA

Run end-to-end on a real macOS host enrolled to a Premium Fleet. Use https://carlo.ngrok.io (local dev) or dogfood for steps requiring multiple cached versions.

1. As admin, add Google Chrome (FMA, macOS) to the Workstations team. Verify the Library section shows one collapsed row with Latest + All hosts.
2. Populate a second cached version (via GitOps version: against dogfood, or by inserting a second software_installers row locally). Verify Library now shows two collapsed rows: the new active row with Latest + label-count badge; the older row greyed out with no badge and the rollback tooltip on hover (Select **Actions > Versions** and pin this version to rollback.).
3. Install Chrome on a test host (Self-service or auto-install). Verify the latest version installs and the active row's Installed count increments. Expand the row and verify the labels block, hash + copy, and download icon all render and function.
4. Click Actions ▾ → Versions. Verify the modal opens titled Versions with Automatically update to latest pre-selected. Select Pin to {older version} → Save. Verify: success flash, modal closes, the older row picks up the Pinned badge, the newer row loses Latest. On a different test host, trigger a fresh install → verify the host pulls the pinned older installer (downgrade behavior). Verify an edited_software activity with pinned_version: "{old version string}" appears in the activity feed.
5. Open Versions again → select Pin to major version (N). Verify: success flash, the Pinned badge sits on whichever cached row currently satisfies the major. Verify the activity feed shows pinned_version: "^N".
6. Open Versions again → select Automatically update to latest. Verify: success flash, the newest cached row picks up Latest. Verify the activity feed shows pinned_version: null.
7. Enable GitOps mode (or operate on a team configured for GitOps). Verify: Versions item in Actions dropdown is disabled with the GitOps tooltip; per-row trash icon is disabled with the tooltip; Edit appearance / Edit software / Patch keep their existing GitOps treatment.
8. Log in as observer. Verify the Versions action item is hidden in the dropdown and per-row trash icons are absent.
9. Disable Premium licensing (or hit a core build). Verify PATCH .../package with version returns 402 and the Versions action item is hidden in the UI.
10. Trigger ^999. Verify the error flash dispatches and the modal stays open with the previous selection still applied.
11. Click the Auto install > pill in the Info card. Verify the Policies modal opens with the linked patch policy names and the footer text Software will be installed when hosts fail these policies. Verify Done dismisses it.
12. API-level: as observer, observer+, and the gitops role, hit PATCH .../package directly with a version body field. Verify each returns 403 (or the correct gitops-role error), independent of the UI hiding the button.
13. GitOps precedence test: set a pin via UI, then run a fleetctl apply (or the equivalent) with a software: payload that omits the version field for the same FMA. Verify which wins and document the resulting source-of-truth behavior in the QA comment. (This will surface whether GitOps reconcile clears the UI-set pin or preserves it.)

Restore the pre-QA baseline once done: delete test cached versions, return the host to its original team, clean up dogfood Chrome state.

5. Confirmation on parent issue

Add a comment to #38504 confirming completion of the test plan. Move the status to "Ready for release" only after QA picks it up; do not move it there yourself.

6. Dogfooding issue

File a dogfooding issue covering the new Library / Versions / Policies surfaces so Engineering uses them on their own Fleet instance.

Condition of satisfaction

Docs:

• Follow-up PR against docs-v4.88.0 documenting pinned_version / fleet_maintained_versions[] on GET /software/titles/:id is merged.
• PR [API changes] Auto update, pin, and rollback Fleet-maintained apps via UI/API  #47274's Actions > Edit software reference is reconciled with the shipped dropdown menu item name (or updated if the shipped name differs).
• Audit log reference reflects the new pinned_version field with examples.
• Feature guide replaces "Update the app" with Auto-update / Pin a version / Roll back sections covering both the UI and GitOps workflows. (Separate PR against the docs branch.)

QA:

• All 13 QA steps above pass on a real device.
• Engineer confirmation comment on Auto update, pin, and rollback Fleet-maintained apps via UI/API #38504.
• Dogfooding issue filed.

Regression checks:

• MYSQL_TEST=1 REDIS_TEST=1 go test ./server/service/... ./ee/server/service/... passes.
• yarn test passes.