iOS Builds

Build and submit iOS apps to TestFlight and the App Store using Capgo’s dedicated Mac infrastructure.

What you will learn

• You will learn how to upload your app via Capgo Native build
• You will learn how to configure the certificates for Capgo Native Build

Prerequisites

• A Capgo account with an active subscription
• Your app already registered in Capgo (run npx @capgo/cli@latest app add if not)
• A Mac computer with Xcode installed (it’s possible to setup the build on a linux/windows machine, but it’s not yet documented)
• Valid Apple Developer account ($99/year) (You must have admin or owner rights on the Apple Developer account)
• Your app must be able to build successfully via Xcode
• A Capacitor app
• A configured icon for the app. Apps without an icon cannot be uploaded to the App Store.

Note

I will use the following app for the tutorial: https://github.com/Cap-go/capgo-native-build-tutorial-app

The first manual build

Before we can start thinking about building the app with Capgo, we should first set it up, and do a first TestFlight build by hand. There are some advantages to doing a manual build first:

• You will setup the distribution certificate on your local machine
• You will create the App Store record if you haven’t done it yet
• You will be able to figure out any issues with the build process linked to your app code

Before we can begin, you must have the distribution certificate installed on your local machine. This is quite a bit complex, but I will explain it below.

Setting up the distribution certificate

1. Open Xcode

2. Click on Xcode -> Settings... Alternatively, you can use the shortcut Cmd + ,

   

3. Go to Accounts

4. Find the Apple Account that is added to the Apple Developer Account

5. Find the team that you will use to deploy the app

6. Click on the Manage Certificates... button

7. Make sure you can see the distribution certificate in the list

8. If you do not, you need to create a new certificate

   Note

   Apple limits the number of distribution certificates you can have to 3. If you have more than 3 certificates, you need to delete one in order to create a new one. I will not cover that in the tutorial.

   1. Click on the + button and then on Apple Distribution
   2. The certificate will be created automatically. You can see it in the list. Look at the previous step to confirm that you see it.

Now that you have the distribution certificate installed, you can begin the build process.

Manual build to TestFlight

1. Open the app in Xcode

   Run npx cap open ios to open the app in Xcode.

2. Find and click on the archive button

   In the Xcode toolbar, find and click on the product -> archive button.

   

3. Wait for the build to complete

4. Click on the Distribute App button

   

5. Select TestFlight Internal Only as the distribution method and click on Distribute button

   

6. Configure the app record

   Fill in the following fields:

   1. Name: The name of your app - visible in the App Store
   2. SKU - the SKU of your app - this is used to identify your app in the App Store
   3. The primary language - the primary language of your app

   Then, click on the next button

   

7. If the creation of the app record fails, try to close the window and try to archive the app again.

8. Wait for the upload to complete

9. If everything went well, you should see the following screen

10. Click on the Done button

You may instinctively think that all is good now and that you will be able to see your app in TestFlight now, but there are a few more things needed to be done before you can see your app in TestFlight:

1. You need to add yourself to TestFlight
2. You need to promise Apple that your app doesn’t use any non-standard (like a custom algorithm) encryption. If your app does use any non-standard encryption, I suggest reading the Apple documentation on how to handle this.

Let’s start with the first one:

Adding yourself to TestFlight

1. Go to the App Store Connect page

2. Sign in with your Apple Developer account

3. Select the team that you used when you created the app record. If you are only in one developer account, can skip this step.

4. Click on the Apps button

5. Find the app you created in the previous step and click on it

6. Click on the TestFlight button

7. Click on the Internal Testers plus button

8. Create a new group

   I like to name the group “internal”. You can name it whatever you want.

   

9. Click on Invite testers button

10. Add yourself to the group

    Find yourself in the list and select the checkbox next to your name. (You may need to refresh the page to see yourself) Then, click on the Add button.

    

11. Verify that you are added to the group

    Now, you should see yourself in the group.

    

Congratulations 🎉 You have added yourself to TestFlight. Now, there is just one more thing you need to do before you can configure Capgo Native Build.

Setting up the compliance information

You now need to promise Apple that your app doesn’t use any non-standard (like a custom algorithm) encryption. If your app does use any non-standard encryption, I suggest reading the Apple documentation on how to handle this. There are two ways to do this:

1. You can do this by hand every time you build your app.
2. You can configure your plist file to automatically set this value to false.

Let’s start with the first one:

1. Follow all the steps from the previous section to find the TestFlight section in App Store Connect

2. Click on Builds -> iOS

3. Find the build with missing compliance information and click on Manage

4. Select the option that best describes your app

   For me, this is none, but it might be different for you. After, click save

   

5. Your app should now say ready to test

   

As for the second one, here are the steps:

1. Open the Info.plist file

2. Add the following key:

   <key>ITSAppUsesNonExemptEncryption</key>
   <false/>

3. Save the file

Note

Here is the official Apple documentation on how to inform Apple of your compliance with encryption export regulations.

Installing the TestFlight app and accepting the invitation

Now, you are ALMOST ready to test your app in TestFlight. Before, you need to do the following things:

1. Download the TestFlight app from the App Store on your iOS/iPadOS device
2. Accept the invitation to test your app

I will skip the details of how to install the TestFlight app on your device. If you are not sure how to install an app, Google has some great guides on how to do it.

As for accepting the invitation, you will receive an email from Apple with a link to accept the invitation.

1. Open the email from Apple with the link to accept the invitation

2. Click on View in TestFlight button

3. Click on the Install button

4. Install the app on your device

   If you have installed the app previously using Xcode, you may see the following screen. Please click on the install button.

5. Wait for the app to install

6. Click on the Open button and click it

Congratulations 🎉 You have accepted the invitation to test your app in TestFlight. Now, you can configure Capgo Native Build to build and submit your app to TestFlight.

Configuring Capgo Native Build

There are a few things you need to configure in Capgo Native Build to be able to build and submit your app to TestFlight. Here is a list of the things you will pass to the Capgo CLI:

Parameter	Description
--platform	The platform to build for (ios)
--apple-team-id	Your Apple Developer Team ID (found in Apple Developer Portal)
--apple-key	Path to your App Store Connect API Key file (.p8 file)
--apple-key-id	The Key ID of your App Store Connect API Key
--apple-issuer-id	Your App Store Connect Issuer ID
--certificate	Path to your distribution certificate (.p12 file)
--provisioning-profile	Path to your provisioning profile (.mobileprovision file)
--apple-profile-name	The name of your provisioning profile

Example command:

npx @capgo/cli@latest build credentials save \
  --platform ios \
  --apple-team-id YOUR_TEAM_ID \
  --apple-key '/path/to/AuthKey_XXXXX.p8' \
  --apple-key-id YOUR_KEY_ID \
  --apple-issuer-id YOUR_ISSUER_ID \
  --certificate '/path/to/certificate.p12' \
  --provisioning-profile '/path/to/profile.mobileprovision' \
  --apple-profile-name your-profile-name

Team ID

Let’s start with the team ID. Finding it is quite easy.

1. Go to Apple Developer Account and scroll down

2. Find the Team ID

   

Apple key, Apple key ID and Apple issuer ID

Now, let’s move on to the Apple key.

1. Go to App Store Connect user and access page

   Note

   For me the link sometimes doesn’t work. Reload the page if it doesn’t work for you.

2. Select the correct team in the dropdown

   1. Click on your name in the top right corner
   2. Click on the team you want to use

3. Click on the Integrations button

4. Find the issuer

   Caution

   This IS TO BE SAVED - you will need it later

   Click on the copy button to copy the issuer

5. Click on the plus button

6. Set the name of the key and set the access to App manager and click on the Generate button

7. Save the key ID

   Caution

   This IS TO BE SAVED - you will need it later

   

8. Download the key

   Caution

   This IS TO BE SAVED - you will need it later

   Danger

   NEVER SHARE THE KEY WITH ANYONE - USE IT ONLY IN THE CAPGO CLI

   

   

Congratulations 🎉 You have created the Apple key, Apple key ID and Apple issuer ID.

Certificate

Now, you are ready to export the certificate. As you remember, one of the first steps of this guide was setting up the distribution certificate.

However, Apple in their infinite wisdom, decided that the way you export the certificate is quite different from the way you create them 🙃 Let’s get into setting it up:

1. Open Keychain Access

   1. Click Command + Space to open the search bar
   2. Search for Keychain Access
   3. Click on the Keychain Access app

2. Select the login category and click on the My Certificates button

3. Find your certificate in the list

   The certificate should be named Apple Distribution: [Your Name/Company] (your team ID)

4. Right-click on the certificate and select Export

5. Save the certificate as a .p12 file

   Caution

   This IS TO BE SAVED - you will need it later

   1. Make sure to select a good name for the certificate file
   2. Make sure the file format is set to Personal Information Exchange (.p12)
   3. Click on the Save button

   

6. When asked for the password, you can either:

   • Skip the password (recommended for simplicity): Click OK without entering a password
   • Set a password: If you prefer to protect your certificate with a password, you can set one here. Password-protected .p12 files are fully supported by the Capgo CLI - just provide the password using the --p12-password option when running configuration command.

   

7. When asked for the “login keychain password”, give the password you use to login to your Mac

   Give the password you use to login to your Mac. Then, click on the Allow button.

   

Congratulations 🎉 You have exported the certificate.

Provisioning profile

Now, you are ready to export the provisioning profile. I promise, this is the last thing you will need to get from Apple.

1. Go to Apple Developer Profiles

2. Select the correct team in the dropdown

   1. Click on your name in the top right corner
   2. Click on the team you want to use

3. Make sure you are on the correct page It should look like this, if it doesn’t click on profiles in the sidebar

   

4. Click on the + button

5. Select the profile type Select App Store Connect and click on the Continue button

   

6. Select the app you want to build

   Find your app in the dropdown and click on the Continue button

   

7. Select the correct distribution certificate

   Select the certificate you exported in the previous step and click on the Continue button

   

   If you are unsure which certificate to select, come back to Keychain Access and find the certificate you exported. Then look at the expiration date.

   

8. Name the profile

   Give the profile a name and click on the Generate button

   Caution

   This name IS TO BE SAVED - you will need it later

   

9. Download the profile

   Click on the Download button to download the profile

   Caution

   This file IS TO BE SAVED - you will need it later

   

Congratulations 🎉 You have now got everything you need to configure Capgo Native Build.

Caution

Never commit the credentials you just created to your repository. Keep them safe! 🔒

Running the configuration command

You have done it! You have now got everything you need to configure Capgo Native Build.

The command you will need to run is:

npx @capgo/cli@latest build credentials save \
  --platform ios \
  --apple-team-id UVTJ336J2D \
  --apple-key ./capgo-tutorial/AuthKey_66FGQZB566.p8 \
  --apple-key-id 66FGQZB566 \
  --apple-issuer-id 0cd4db4a-5598-45b8-9d32-75cdf127d005 \
  --certificate ./capgo-tutorial/capgo-build-tutorial-certificate.p12 \
  --provisioning-profile ./capgo-tutorial/capgo_native_build_tutorial.mobileprovision \
  --apple-profile-name capgo_native_build_tutorial

Replace placeholder values

Replace the placeholder values above with your actual credentials gathered in the previous steps:

• --apple-team-id: Your Apple Team ID
• --apple-key: Path to your downloaded .p8 key file
• --apple-key-id: Your Apple Key ID
• --apple-issuer-id: Your Apple Issuer ID
• --certificate: Path to your exported .p12 certificate
• --provisioning-profile: Path to your downloaded .mobileprovision file
• --apple-profile-name: The provisioning profile name you set previously

If all went well, you will see the following output:

CI/CD setup (GitHub Actions)

If you already completed Team ID, Apple key, Apple key ID and Apple issuer ID, Certificate, and Provisioning profile, you already have everything needed for CI/CD. This section only covers how to pass those values as GitHub Actions secrets and environment variables.

1) Convert credential files to single-line base64

# Distribution certificate (.p12)
base64 -i ./capgo-tutorial/capgo-build-tutorial-certificate.p12 | tr -d '\n' > certificate_base64.txt

# Provisioning profile (.mobileprovision)
base64 -i ./capgo-tutorial/capgo_native_build_tutorial.mobileprovision | tr -d '\n' > profile_base64.txt

# App Store Connect API key (.p8)
base64 -i ./capgo-tutorial/AuthKey_66FGQZB566.p8 | tr -d '\n' > apple_key_base64.txt

Tip

GitHub secrets should be single-line values. tr -d '\n' removes line breaks from base64 output.

2) Create repository secrets

In GitHub > Repository > Settings > Secrets and variables > Actions, add:

Secret name	Value
CAPGO_TOKEN	Your Capgo API token
APP_STORE_CONNECT_TEAM_ID	Team ID from Team ID
APPLE_KEY_ID	Key ID from Apple key, Apple key ID and Apple issuer ID
APPLE_ISSUER_ID	Issuer ID from Apple key, Apple key ID and Apple issuer ID
BUILD_CERTIFICATE_BASE64	Content of certificate_base64.txt
BUILD_PROVISION_PROFILE_BASE64	Content of profile_base64.txt
APPLE_KEY_CONTENT	Content of apple_key_base64.txt
APPLE_PROFILE_NAME	Provisioning profile name from Provisioning profile. Required unless you pass --apple-profile-name; otherwise builds fail.
P12_PASSWORD (optional)	Your .p12 password if set during export

3) Use env vars in your GitHub Actions workflow

.github/workflows/ios-build.yml

name: iOS Cloud Build

on:
  workflow_dispatch:
  push:
    branches: [main]

jobs:
  ios-build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest
      - name: Request iOS build with Capgo
        run: bunx @capgo/cli@latest build request --platform ios
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}
          APPLE_KEY_ID: ${{ secrets.APPLE_KEY_ID }}
          APPLE_ISSUER_ID: ${{ secrets.APPLE_ISSUER_ID }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          BUILD_PROVISION_PROFILE_BASE64: ${{ secrets.BUILD_PROVISION_PROFILE_BASE64 }}
          APPLE_KEY_CONTENT: ${{ secrets.APPLE_KEY_CONTENT }}
          APPLE_PROFILE_NAME: ${{ secrets.APPLE_PROFILE_NAME }}
          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}

Astuce

With this setup, CI sends credentials through environment variables only. You do not need to commit signing files or upload them as workflow artifacts.

Running the build

Now, you are ready to run your first build.

Run the following command to build your app:

npx @capgo/cli@latest build request --platform ios

Congratulations 🎉 At this point, you have successfully built your app and it is ready to be submitted to the App Store.

Ad-Hoc Distribution Mode

By default, Capgo builds iOS apps for App Store distribution (TestFlight + App Store). If you need ad-hoc builds instead (for internal testing or CI artifact collection), you can use the --ios-distribution flag.

Note

Ad-hoc distribution is not the same as Enterprise (In-House) distribution. Enterprise distribution requires a separate Apple Developer Enterprise account and uses different provisioning profiles. Capgo currently supports app_store and ad_hoc modes only.

When to use ad-hoc mode

• You want to distribute IPAs directly to registered devices (no TestFlight)
• You don’t have or don’t want to use an App Store Connect API key
• You want to collect build artifacts via --output-upload without submitting to the App Store

Requirements

Ad-hoc builds have fewer requirements than App Store builds:

Credential	Required?
Distribution certificate (.p12)	Yes
Ad-hoc provisioning profile (.mobileprovision)	Yes
Team ID (--apple-team-id)	Yes
App Store Connect API key (.p8)	No
Apple Key ID / Issuer ID	No

Attention

Without an App Store Connect API key, build number auto-increment uses a timestamp-based fallback. To suppress the warning, pass --skip-build-number-bump.

Creating an ad-hoc provisioning profile

Follow the same steps as Provisioning profile, but in step 5, select Ad Hoc instead of App Store:

1. Go to Apple Developer Profiles
2. Click the + button
3. Select Ad Hoc and click Continue
4. Select your app and distribution certificate
5. Select the devices you want to register
6. Name and download the profile

Saving ad-hoc credentials

npx @capgo/cli@latest build credentials save \
  --platform ios \
  --ios-distribution ad_hoc \
  --apple-team-id YOUR_TEAM_ID \
  --certificate './certificate.p12' \
  --provisioning-profile './adhoc_profile.mobileprovision' \
  --apple-profile-name your-adhoc-profile-name

No --apple-key, --apple-key-id, or --apple-issuer-id needed.

Running an ad-hoc build

npx @capgo/cli@latest build request \
  --platform ios \
  --ios-distribution ad_hoc

To collect the IPA as a build artifact, add --output-upload:

npx @capgo/cli@latest build request \
  --platform ios \
  --ios-distribution ad_hoc \
  --output-upload

CI/CD with ad-hoc builds

For GitHub Actions, you need fewer secrets than App Store builds:

.github/workflows/ios-adhoc-build.yml

name: iOS Ad-Hoc Build

on:
  workflow_dispatch:

jobs:
  ios-adhoc:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest
      - name: Request iOS ad-hoc build
        run: bunx @capgo/cli@latest build request --platform ios --ios-distribution ad_hoc --output-upload
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          BUILD_PROVISION_PROFILE_BASE64: ${{ secrets.BUILD_PROVISION_PROFILE_BASE64_ADHOC }}
          APPLE_PROFILE_NAME: ${{ secrets.APPLE_PROFILE_NAME }}
          CAPGO_IOS_DISTRIBUTION: ad_hoc

Astuce

Notice that APPLE_KEY_ID, APPLE_ISSUER_ID, and APPLE_KEY_CONTENT are not needed for ad-hoc builds.

Troubleshooting

Provisioning profile doesn’t include the XYZ capability.

Sometimes, you might see the following error:

Provisioning profile "YOUR_PROVISIONING_PROFILE_NAME" doesn't include the XYZ capability. (in target 'App' from project 'App')"

This happens because you have enabled a new capability after the provisioning profile was created. The old provisioning profile does not include the new capability yet.

To fix this, you need to regenerate the provisioning profile.

1. Open Apple Developer Portal
2. Select the correct team in the dropdown
3. Click on the Profiles button
4. Find the provisioning profile you want to regenerate
5. Click on the Edit button
6. Click on the Save button
7. Click on the Download button
8. Re-run the Capgo Native Build setup command with the newly downloaded profile.

This should fix the issue.

Other issues

If for whatever reason you are having issues either with Capgo Native Build, configuring the credentials or building the app, please don’t hesitate to reach via our support.