iOS/iPadOS in-house apps (`.ipa`): Support setup experience

[noahtalerman]

Goal

User story
As an IT admin,
I want to automatically install my company's in-house app (.ipa package) on iOS/iPadOS hosts when they enroll to Fleet.

Changes

Product

• UI changes:
  • Controls > Setup Experience > Install software: surface .ipa (in-house) software titles in the "Select software" modal for the iOS and iPadOS tabs.
• CLI (fleetctl) usage changes: No changes
• YAML changes: No changes
• REST API changes:
  • PUT /api/v1/fleet/setup_experience/software must accept .ipa software title IDs for the ios and ipados platforms.
• Fleet's agent (fleetd) changes: No changes
• Fleet server configuration changes: No changes
• Exposed, public API endpoint changes: No changes
• fleetdm.com changes: No changes
• GitOps mode UI changes: No changes
• GitOps generation changes:
  • fleetctl generate-gitops should emit setup_experience: true for .ipa packages that are selected for setup experience and setup_experience_platform if only selected for a single platform.
• Activity changes:
  • Use existing edited_setup_experience_software activity item.
• Permissions changes: No changes
• Changes to paid features or tiers: Premium
• My device and fleetdm.com/better changes: No changes
• Usage statistics: No changes
• Other reference documentation changes: No changes
• First draft of test plan added
• Once shipped, requester has been notified
• Once shipped, dogfooding issue has been filed

Engineering

• Test plan is finalized
• Contributor API changes: No changes
• Feature guide changes: No changes
• Database schema migrations: See subtasks

BYOD Devices

• Can a .ipa be installed(assuming it's built and properly allowlisted to the device's UUID, etc) on an account-driven-user-enrollment BYOD device? Communicate this result in #g-apple-at-work to product as soon as possible(before implementation if possible)

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

Risk assessment

• Risk level: Low

Test plan

Make sure to go through the list and consider all events that might be related to this story, so we catch edge cases earlier.

Core flow

• Upload an .ipa package via Software > Add software > Custom package (or API). Verify two software titles are created (one for iOS, one for iPadOS).
• Go to Controls > Setup experience > Install software. In the iOS and iPadOS tabs, verify the .ipa software title appears in the "Select software" modal. Add it to setup experience and save.
• Verify that GET /api/v1/fleet/setup_experience/software lists the .ipa title for ios and ipados platforms (previously filtered out).
• Automatically enroll an iPhone (or iPad) via ABM with Setup Assistant (AwaitingConfiguration==true). Verify that Fleet enqueues an InstallApplication MDM command with ManifestURL for the .ipa app.
• Verify that Fleet does not send DeviceConfigured (release the host from Setup Assistant) until the .ipa app is verified as installed(or fleet hits the existing timeout).
• Manually enroll an iPhone (or iPad) via ABM with Setup Assistant (AwaitingConfiguration==true). Verify that Fleet enqueues an InstallApplication MDM command with ManifestURL for the .ipa app.
• After Setup Assistant completes, verify the .ipa app is installed
• Verify that in both cases above, the host's software inventory shows the .ipa app with "Installed" status, and that the install activity appears on the Host details page.

Edge cases

iOS/iPadOS title split (one .ipa = two titles)

• Add only the iOS title to setup experience (leave iPadOS unselected). Verify an enrolling iPhone gets it and an enrolling iPad does not. Swap the selection and confirm the inverse.
• Verify the iOS and iPadOS titles toggle/persist independently (selecting one does not select the other), and both survive a page reload / re-GET.

Platform isolation (filter must stay tight)

• Confirm the .ipa title does not appear in the macOS, Windows, or Linux tabs of the "Select software" modal.
• Confirm GET .../setup_experience/software?platform=macos (and windows/linux) still excludes the .ipa title — only ios/ipados should surface it.

Install failure & host release

• Force the .ipa install to fail during Setup Assistant (e.g. incompatible OS version, corrupt/unsigned manifest which may require a special fleet build. Implementing engineer to provide instructions). Verify the host is still eventually released (does not hang in AwaitingConfiguration) if enrolling via ABM and the failure is surfaced in setup-experience results / Host details.
• Verify the ABM release timeout path still releases the device if the in-house install never reaches a terminal state (hard cap ~15m / ~30 attempts).

Coexistence / lifecycle

• Mixed setup-experience payload: .ipa in-house app + a VPP app on the same platform → both install during setup, in a deterministic order.
• Assign the .ipa to setup experience, then delete the software title → Verify the deletion is blocked and it can only be deleted if first unassigned from setup experience.
• Re-upload a new version of the .ipa while it is assigned to setup experience → verify it stays assigned (or the expected re-selection behavior) and the new version is what installs.
• Managed app configuration and any $FLEET_VAR_* in the config are correctly applied to the .ipa install during setup (not just for post-enrollment installs).

GitOps (generate + run)

• Configure .ipa setup experience in the UI and run fleetctl generate-gitops.
• Confirm the generated .yml emits setup_experience: true on the (deduped, single) in-house app entry — verify the flag survives the iOS+iPadOS title dedup.
  • Verify setup_experience boolean handling against this(TBD as of writing) https://github.com/fleetdm/fleet/pull/50632/changes#r3723639356
• Modify the generated .yml and run fleetctl gitops; confirm the configuration updates correctly in Fleet.
• Set setup_experience: true on an .ipa from scratch in YAML and apply → confirm it is accepted (this extension previously wasn't an allowed setup-experience platform).
• Enable GitOps mode and verify the feature behaves correctly (read-only UI).
• Validate that a .ipa can be applied to only iOS or iPadOS setup experience via gitops without applying to both by using setup_experience_platforms

Supplemental testing

Testing notes

Confirmation

1. Engineer: Added comment to user story confirming successful completion of test plan (include any special setup, test data, or configuration used during development/testing if applicable).
2. QA: Added comment to user story confirming successful completion of test plan.
3. QA: Determined whether this story needs Playwright automation.
   • Needs automation: Yes / No
   • If yes, filed a follow-up issue in the :help-qa project with status "Needs automation":

[noahtalerman]

@JordanMontgomery just double checking, I can't use .ipa packages for iOS/iPadOS setup experience?

cc @marko-lisica

[JordanMontgomery]

@noahtalerman From a quick test that appears to be correct. THe UI does not currently allow specifying a .ipa package for setup experience