| name | add-device |
| description | Registers a new iOS device for the Pathways Field Companion ad-hoc build and ships an IPA that installs on it. Use this whenever someone wants to get the app onto a new iPhone/iPad for testing — phrases like "add a device", "register my phone for the build", "add a UDID to the provisioning profile", "get a build that installs on <person>'s phone", or when handed a `.mobileprovision` file and asked to "get a build out for the new device". Covers the full path: Apple Developer portal registration (guided, human-driven), updating the signing secret, and cutting the rebuild release. If a profile path is provided, the portal steps are assumed done — jump straight to shipping the build. |
Add a device to the iOS ad-hoc build
The iOS build of Pathways Field Companion is distributed ad-hoc: it only installs on devices whose UDID is baked into the provisioning profile. Adding a new tester's device therefore means two things have to happen — the device gets registered in the profile (a manual step in Apple's portal, which only a human signed into the team can do), and a fresh build gets cut against the updated profile (which you can fully automate).
The signing identity is fixed and worth knowing so you can sanity-check what you're handed:
- App ID:
us.jarv.pathwaysFieldCompanion
- Team: Jarvus Innovations LLC (
64TVJXTLTT)
- Ad-hoc profile name:
Pathways Field Companion Ad Hoc
A key detail that saves work: ios/ExportOptions.plist references the profile by name, and regenerating a profile keeps the same name (only its UUID changes). So adding a device never requires editing any file in the repo — the build just needs the refreshed profile bytes, which live in the APPLE_PROVISIONING_PROFILE_BASE64 GitHub Actions secret.
Two entry modes
If the user gave you a path to a .mobileprovision file, assume the portal work is already done — skip Phase 1 and go straight to Phase 2.
Otherwise, the device still needs to be registered. Walk the user through Phase 1 first; those are steps only they can do, in a browser, signed into the Jarvus team. Once they've downloaded the regenerated profile, continue with Phase 2.
Phase 1 — Register the device in the Apple Developer portal (human steps)
These happen in the browser under the Jarvus Innovations LLC team. You can't do them — guide the user clearly and wait for them to finish each one. Hand them the URLs as clickable links.
-
Get the device's UDID (skip if they already have it). The easiest way is to open https://udid.tech/ on the device itself — it walks the user through installing a temporary profile and shows the UDID, which they can copy or email to themselves. They'll need the UDID string plus a human-friendly device name.
-
Register the device. Go to https://developer.apple.com/account/resources/devices/list, click the + (Register a Device), choose platform iOS, and enter the name and UDID. Save.
-
Add the device to the ad-hoc profile and download it. Go to https://developer.apple.com/account/resources/profiles/review/77J35DQ49U, click Edit, tick the newly registered device in the device list, Save, then Download the regenerated profile. It lands in ~/Downloads (typically Pathways_Field_Companion_Ad_Hoc.mobileprovision, possibly with a (1) suffix if a copy already exists).
When they confirm the download is done, ask for the path (or just look in ~/Downloads) and move to Phase 2.
Phase 2 — Ship a build with the new device
This half is yours to run. Updating the secret and publishing a release are outward-facing actions — once the user has pointed you at a profile and asked for a build, that's your authorization for this run; you don't need to re-confirm each command, but do report what you did.
Step 1 — Locate and verify the profile
If the user gave a path, use it. Otherwise find the most recent download:
ls -t ~/Downloads/*.mobileprovision | head
Before pushing anything, decode it and confirm it's the right profile — this catches the common mistake of grabbing the development profile, an expired one, or a stale copy:
security cms -D -i "<path>" | plutil -p - | grep -iE "Name|application-identifier|TeamIdentifier|ExpirationDate|ProvisionedDevices" -A20
Check that:
- Name is
Pathways Field Companion Ad Hoc
- application-identifier ends with
us.jarv.pathwaysFieldCompanion
- TeamIdentifier is
64TVJXTLTT
- ExpirationDate is in the future
- the ProvisionedDevices list includes the new device (if the user gave you the UDID, grep for it; otherwise just confirm the count looks right and mention how many devices are in it)
If anything's off, stop and tell the user — don't push a wrong profile into the secret.
Step 2 — Update the signing secret
The build reads the profile from this secret, so overwrite it with the freshly downloaded one:
base64 -i "<path>" | gh secret set APPLE_PROVISIONING_PROFILE_BASE64
gh secret list | grep APPLE_PROVISIONING
Step 3 — Cut a quick rebuild release
The IPA is built only in CI, triggered when a GitHub release is published (.github/workflows/builds-publish.yml). To get a new IPA without shipping any new code, tag the next patch version on the latest release's exact commit — byte-identical code, just rebuilt with the updated profile. The build number is derived in CI from the tag count, so it increments automatically.
git fetch --tags --quiet
gh release list --limit 1
git rev-list -n1 <latest-tag>
Compute the next patch version (e.g. v0.3.0 → v0.3.1) and create the release on that commit:
gh release create <new-tag> \
--target <commit> \
--title "<new-tag>" \
--notes "Rebuild of <latest-tag> to add a new device to the ad-hoc provisioning profile. No code changes."
If the user actually wants to ship pending changes from develop along with the device addition, this quick-rebuild shortcut is the wrong tool — point them at the normal /release flow instead, which drafts notes and bumps the version properly.
Step 4 — Watch the build and confirm the IPA
Publishing the release fires the workflow. Confirm it started, then watch it to completion:
gh run list --workflow=builds-publish.yml --limit 1
gh run watch <run-id> --exit-status
On success, confirm the signed IPA was uploaded:
gh release view <new-tag> --json assets --jq '.assets[] | "\(.name) \(.size) bytes \(.state)"'
You're looking for PathwaysFieldCompanion.ipa (alongside the Android .apk). Give the user the release URL and tell them to install that IPA on the new device (Apple Configurator, Finder drag-install, or their usual ad-hoc method).
If the build fails, surface the cause rather than guessing:
gh run view <run-id> --log-failed
A signing failure at the Build signed IPA step usually means the profile in the secret doesn't match the cert or the device wasn't actually saved into the profile — re-check Step 1's decode against the portal.
