Signing iOS apps

How to set up iOS code signing in codemagic.yaml

All iOS applications have to be digitally signed before they can be installed on real devices or made available to the public.

Prerequisites

Signing iOS applications requires Apple Developer Program membership. You can upload your signing certificate and distribution profile to Codemagic to manage code signing yourself or use the automatic code signing option where Codemagic takes care of code signing and signing files management on your behalf. Read more about the two options below.

Automatic code signing

In order to use automatic code signing and have Codemagic manage signing certificates and provisioning profiles on your behalf, you need to configure API access to App Store Connect.

Creating the App Store Connect API key

It is recommended to create a dedicated App Store Connect API key for Codemagic in App Store Connect. To do so:

1. Log in to App Store Connect and navigate to Users and Access > Keys.
2. Click on the + sign to generate a new API key.
3. Enter the name for the key and select an access level. We recommend choosing either Developer or App Manager, read more about Apple Developer Program role permissions here.
4. Click Generate.
5. As soon as the key is generated, you can see it added to the list of active keys. Click Download API Key to save the private key for later. Note that the key can only be downloaded once.

Saving the API key to environment variables

Save the API key and the related information in the Environment variables section in Codemagic UI. Click Secure to encrypt the values. Note that binary files (i.e. provisioning profiles & .p12 certificate) have to be base64 encoded locally before they can be saved to Environment variables and decoded during the build. Below are the following environment variables:

• APP_STORE_CONNECT_KEY_IDENTIFIER

  In App Store Connect > Users and Access > Keys, this is the Key ID of the key.

• APP_STORE_CONNECT_ISSUER_ID

  In App Store Connect > Users and Access > Keys, this is the Issuer ID displayed above the table of active keys.

• APP_STORE_CONNECT_PRIVATE_KEY

  This is the private API key downloaded from App Store Connect.

• CERTIFICATE_PRIVATE_KEY

  An RSA 2048 bit private key to be included in the signing certificate that Codemagic creates. You can use an existing key or create a new 2048 bit RSA key by running the command below in your terminal. Running the command line will create private and public keys. Note that you should select Secure to encrypt the contents of the private file in the Environment Variables Section.

ssh-keygen -t rsa -b 2048 -m PEM -f ~/Desktop/codemagic_private_key -q -N ""

Add the group in the codemagic.yaml as follows:

environment:
  groups:
    - appstore_credentials
  # Add the above mentioned group environment variables in Codemagic UI (either in Application/Team variables): 
    # APP_STORE_CONNECT_ISSUER_ID
    # APP_STORE_CONNECT_KEY_IDENTIFIER
    # APP_STORE_CONNECT_PRIVATE_KEY 
    # CERTIFICATE_PRIVATE_KEY

Specifying code signing configuration

To code sign the app, add the following commands in the scripts section of the configuration file, after all the dependencies are installed, right before the build commands.

scripts:
  ... your dependencies installation
  - name: Set up keychain to be used for code signing using Codemagic CLI 'keychain' command
    script: keychain initialize
  - name: Fetch signing files
    script: |
      # You can allow creating resources if existing are not found with `--create` flag
      app-store-connect fetch-signing-files "io.codemagic.app" \
        --type IOS_APP_DEVELOPMENT \
        --create      
  - name: Set up signing certificate
    script: keychain add-certificates
  - name: Set up code signing settings on Xcode project
    script: xcode-project use-profiles
  ... your build commands

Instead of specifying the exact bundle-id, you can use "$(xcode-project detect-bundle-id)".

Based on the specified bundle ID and provisioning profile type, Codemagic will fetch or create the relevant provisioning profile and certificate to code sign the build.

Manual code signing

In order to use manual code signing, save your signing certificate, the certificate password (if the certificate is password-protected) and the provisioning profile in the Environment variables section in Codemagic UI. Click Secure to encrypt the values. Note that binary files (i.e. provisioning profiles & .p12 certificate) have to be base64 encoded locally before they can be saved to Environment variables and decoded during the build.

environment:
  groups:
    - certificate_credentials
  # Add the above mentioned group environment variables in Codemagic UI (either in Application/Team variables): 
    # FCI_CERTIFICATE
    # FCI_CERTIFICATE_PASSWORD
    # FCI_PROVISIONING_PROFILE

Then add the code signing configuration and the commands to code sign the build in the scripts section, after all the dependencies are installed, right before the build commands.

scripts:
  ... your dependencies installation
  - name: Set up keychain to be used for code signing using Codemagic CLI 'keychain' command
    script: keychain initialize
  - name: Set up Provisioning profiles from environment variables
    script: |
      PROFILES_HOME="$HOME/Library/MobileDevice/Provisioning Profiles"
      mkdir -p "$PROFILES_HOME"
      PROFILE_PATH="$(mktemp "$PROFILES_HOME"/$(uuidgen).mobileprovision)"
      echo ${FCI_PROVISIONING_PROFILE} | base64 --decode > "$PROFILE_PATH"
      echo "Saved provisioning profile $PROFILE_PATH"      
  - name: Set up signing certificate
    script: |
      echo $FCI_CERTIFICATE | base64 --decode > /tmp/certificate.p12
      if [ -z ${FCI_CERTIFICATE_PASSWORD+x} ]; then
        # when using a certificate that is not password-protected
        keychain add-certificates --certificate /tmp/certificate.p12
      else
        # when using a password-protected certificate
        keychain add-certificates --certificate /tmp/certificate.p12 --certificate-password $FCI_CERTIFICATE_PASSWORD
      fi      
  - name: Set up code signing settings on Xcode project
    script: xcode-project use-profiles
  ... your build commands

Using multiple provisioning profiles

To set up multiple provisioning profiles, for example, to use app extensions such as NotificationService, the easiest option is to add the provisioning profiles to your environment variables with a similar naming convention:

environment:
  groups:
    - provisioning_profile
   # Add the above mentioned group environment variables in Codemagic UI (either in Application/Team variables): 
    # FCI_PROVISIONING_PROFILE_BASE
    # FCI_PROVISIONING_PROFILE_NOTIFICATIONSERVICE

Then, set the profiles up in the build by using the following script in your YAML file:

scripts:
  - name: Set up Provisioning profiles from environment variables
    script: |
      PROFILES_HOME="$HOME/Library/MobileDevice/Provisioning Profiles"
      mkdir -p "$PROFILES_HOME"
      for profile in "${!FCI_PROVISIONING_PROFILE_@}"; do
        PROFILE_PATH="$(mktemp "$HOME/Library/MobileDevice/Provisioning Profiles"/ios_$(uuidgen).mobileprovision)"
        echo ${!profile} | base64 --decode > "$PROFILE_PATH"
        echo "Saved provisioning profile $PROFILE_PATH"
      done