GitOps mode: Add custom packages

[eugkuo]

Goal

User story
As an IT admin using GitOps mode,
I want to add a custom package on the Software page
so that I can copy/paste the YAML for my custom packages that can't be referenced by a public URL (like CrowdStrike).

Key result

Customer request

Original requests

• Manage software via GitOps with Fleet hosting custom packages #26407

Context

• Design: @eugkuo
• Dev: @mostlikelee

Changes

Product

• UI changes:
  • Prototype
  • Figma design file
• CLI (fleetctl): No changes
• YAML changes: [YAML design] Include hash-only example of software YAML #28297
• REST API changes: No changes
• Fleet's agent (fleetd) changes: No changes
• GitOps mode changes: No changes
• Activity changes: No changes
• Permissions changes: No changes
• Changes to paid features or tiers: Fleet Premium
• My device and fleetdm.com/better changes: No changes
• First draft of test plan added
• Other reference documentation changes: see YAML changes
  • PR for redirect: Adding redirect to teach users how to use YAML for software management #28545
• Once shipped, requester has been notified
• Once shipped, dogfooding issue has been filed: Dogfood: GitOps mode: Add custom packages #30212

Engineering

• Article: New guide: Manage software using GitOps #30047
• Test plan is finalized
• Contributor API changes: No changes

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

QA

Risk assessment

• Risk level: Low

Test plan

Note: Test this for maintainers and admins.
0. This story is only for GitOps mode. In non-GitOps mode, none of this should show up.

1. Upload a custom package
   1. Verify that options and targets have been removed from the custom package upload page.
   2. Verify that on completion you're taken to the software title page and a modal appears showing the YAML.
      1. Verify that the Software successfully added flash message does not appear
      2. Verify that the repository link goes to the repository defined in settings.
   3. Verify that downloading the scripts and queries downloads files with the appropriate titles and content.
   4. Verify that the "How to use YAML" links go to correct locations and instructions.
2. Edit the package
   1. Verify that the YAML modal appears after successful edit.
      1. Verify that the success flash message does not appear over the modal.
   2. Verify that the downloaded scripts and queries download the files with the approriate titles and content.
   3. Verify that the copy in the purple banner matches the copy of the post-save YAML modal in the design and prototype.
   4. Verify that the 'next' text at the bottom of the YAML modal has updated to reflect the modal state as shown in the prototype and figma design file.
   5. Verify that only the hash and title show in the YAML to be copied.
   6. Verify that the first step copy changes to reflect that only the hash need be copied.
   7. Verify that the next step copy changes to reflect that the files should be downloaded and that they should replace the existing ones in their scripts directory.
   8. Verify that the scripts change if there are updates to Advanced options3.. Verify that the "View YAML" button opens the YAML modal with the correct content.
3. Copy the scripts and YAML to your repository and run the fleetctl GitOps command and confirm that the installer changes and or advanced options change sare applied successfully.
   1. If you upload software and don't update the YAML initially, verify that the software package is removed on GitOps run.
   2. If you upload software and don't update the YAML during edit, verify that there is a GitOps failure (this is b/c the hash no longer matches).
4. Additional things to test/look out for
   1. In the YAML modal, downloads and paths only show if items are populated or have been changed. If the items are empty or set to default the downloads shouldn't show nor should their paths in the YAML example.

Non-gitops mode test plans

1. Adding a FMA, VPP, and custom package in non-gitops mode also redirects the user now to the software title details page for that added software instead of the main software titles page

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.

[eugkuo]

Notes from 14 April design review

• @iansltx
  • Use API endpoint for custom uploading a package in the UI.
  • Incorporate this into fleetctl with command upload x file to y team as a package.
  • Can edit it in UI or via GitOps if have GitOps on.
  • When file is uploaded the hash comes back or return the YAML to paste into the team's GitOps file
  • Documentation change for GitOps
  • In fleetctl upload a package easily and documenting that.

[eugkuo]

From 15 April design review:

@mostlikelee Looks like there’s going to be fleetctr changes to upload a package. So from requirements perspective will figure out what that looks like. Probably just 2 params. Path to package and the team.

Also needs to return the hash in the response (so small API change).

[iansltx]

@eugkuo @mostlikelee That API change is already handled as part of #23497 :)

[eugkuo]

Notes from 16 April 2025 DR

1. When reading YAML how will I know what a hash is?
   1. Ian to sketch out what YAML will look like.
      1. Can have line for hash and a comment line with this package name, this version, this file name that fleetctr will spit out that can be copied and pasted.
      2. @iansltx to open a YAML PR to prove out the idea for tomorrow's DR.
2. When run the fleetctr what do you see in the UI?
   1. Same as add software in custom package.