Support

Help with Ground Crew

• Creating an API key
• Which access to choose
• Setting up a new app
• Notifications
• Common problems

Creating an API key

Ground Crew uses an App Store Connect API key, which you create in App Store Connect. To create a team key you need to be the Account Holder or an Admin on the team. If no one on your team has used the API before, the Account Holder may first need to tap Request Access on the same page.

1. Sign in to App Store Connect and go to Users and Access → Integrations → App Store Connect API.
2. Under Team Keys, choose to generate a new key.
3. Give it a name you'll recognise, such as Ground Crew, and set Access to App Manager. See which access to choose below.
4. Generate the key, then download it. The file is called AuthKey_<KEYID>.p8. Apple only lets you download it once, so keep it somewhere safe.
5. Note the two IDs. The Issuer ID is shown above the list of team keys, with a button to copy it. The Key ID is in the key's row, next to its name, and is also the part of the file name after AuthKey_.
6. In Ground Crew, tap Add App Store Connect Key. Enter the issuer ID and key ID, then choose the .p8 file. If the file isn't on your iPhone yet, AirDrop it or save it to iCloud Drive or Files first. You can also open the file on your Mac and paste its contents in.

Ground Crew stores the key in this device's Keychain and only uses it to sign requests to App Store Connect. Once it's added, you can delete the .p8 file from Files if you like.

Individual keys

Individual keys work too. They belong to your own user and act with your role, rather than one chosen for the key. You'll find them under Individual Keys in App Store Connect. In Ground Crew, turn on Individual Key when adding it. Individual keys don't need an issuer ID.

Which access to choose

You can't change a team key's access after creating it. To change it, create a new key, edit the team in Ground Crew's settings, and revoke the old key in App Store Connect.

Turning on Xcode Cloud for a new app

1. Open your project or workspace in Xcode, and make sure you're signed in with an Apple Account on the team in Xcode → Settings → Accounts.
2. Check the scheme you want to build is shared: Product → Scheme → Manage Schemes, tick Shared, then commit and push the change.
3. Choose Product → Xcode Cloud → Create Workflow and pick the app.
4. Xcode suggests a first workflow. You can keep it as it is and change it later in Ground Crew.
5. When Xcode asks, grant Xcode Cloud access to your repository on GitHub, GitLab or Bitbucket. This opens a page in your browser where you approve access.
6. If the app isn't in App Store Connect yet, Xcode offers to add it for you.
7. Xcode starts the first build. Pull to refresh in Ground Crew and the app appears, ready for Flight Plans, edits and builds.

What else to set up outside Ground Crew

These aren't part of Apple's API, so set them in Xcode or App Store Connect:

• Environment variables and secrets: in the workflow's Environment section in Xcode or App Store Connect.
• External TestFlight groups: add a TestFlight post-action to the workflow, or add builds to groups in App Store Connect.
• Post-action notifications, such as Slack or email: add them to the workflow in Xcode or App Store Connect.

Ground Crew leaves these alone when you edit a workflow.

Notifications

In Ground Crew's settings, choose Failures Only or Every Finished Build under Notify Me About. Ground Crew has no server, so it checks App Store Connect for finished builds whenever iOS lets it run in the background. That's usually every 15 minutes to an hour, and iOS decides exactly when.

If notifications don't arrive, check that notifications for Ground Crew are allowed and that Background App Refresh is on in iOS Settings. Low Power Mode, and not opening the app for a while, both make iOS check less often.

Face ID

In Ground Crew's settings, set Require Face ID to For Changes to confirm before starting builds or changing workflows, or to To Open Ground Crew to lock the whole app whenever you leave it. On devices without Face ID it uses Touch ID or your passcode.

Common problems

• "App Store Connect didn't accept this API key": check the issuer ID and key ID match the key, and that it hasn't been revoked. Edit the team in Ground Crew's settings to fix them.
• "This API key's role isn't allowed to do that": the key's access is too low for that change. Create a new key with App Manager access.
• "No Xcode Cloud apps yet": Xcode Cloud hasn't been turned on for any of your apps. Set up the first one in Xcode.
• An app is missing: it doesn't use Xcode Cloud yet, or the key belongs to a different team. Add a key for each team you work with.
• A workflow won't save: check the scheme is shared and pushed, and that the project or workspace path is relative to the top of your repository, such as MyApp.xcodeproj.
• "Locked: only Admins can change this workflow": the workflow was locked in Xcode or App Store Connect. Use a key with Admin access, or unlock it there.
• "App Store Connect is limiting requests from this key": Apple caps how many requests a key can make each hour. Wait a minute and try again.

Try it without a key

Tap Explore the demo team on the welcome screen to load a simulated team with apps, builds and workflows. Nothing you do in the demo touches a real account.

Removing your key

Remove a team in Ground Crew's settings to delete its key from your device. The key keeps working in App Store Connect until you revoke it there, under Users and Access → Integrations → App Store Connect API.