Code signing identities

How to set up code signing identities

Teams can use code signing identities to manage their code signing files in Team settings > codemagic.yaml settings > Code signing identities and reference them from their codemagic.yaml configuration. This makes managing code signing files easier and reduces the number of scripts required in your configuration file.

Managing and uploading files

Team owner permissions are required to upload and edit files under the Code signing identities section. However, all team members can view the file info for any of the uploaded files.

iOS certificates

Codemagic lets you upload code signing certificates as PKCS#12 archives containing both the certificate and the private key which is needed to use it. When uploading, Codemagic will ask you to provide the certificate password (if the certificate is password-protected) along with a unique Reference name, which can then be used in the codemagic.yaml configuration to fetch the specific file.

In addition, if connection to the Apple Developer Portal is enabled in Team settings, Codemagic provides the option to generate a new Apple Development or Apple Distribution certificate. Click Generate certificate, provide a Reference name, select the type of certificate to create and the API key to use for that. Once the certificate has been created, Codemagic will allow you to download the certificate and provides the password for it.

The certificate can be downloaded just once right after creating it.

Note that Apple limits the number of Apple Distribution certificates to 3. If you have already reached the maximum number of certificates, the following error will be displayed:

There is a problem with the request entity - You already have a current Distribution certificate or a pending certificate request.

Similar errors can also arise in rarer cases with Apple Development certificates. To resolve the error, either remove some old certificate from the Apple Developer Portal or upload an existing certificate manually.

However, in the case of existing certificates generated by Codemagic, it is possible to automatically fetch them from the Apple Developer Portal based on your team’s App Store Connect API key.

Fetching certificates that Codemagic has not created is disabled because each certificate has a unique private key to which Codemagic has no access, thus rendering the certificate unusable.

The Reference name, certificate type, team, and expiration date are displayed for each added certificate.

iOS profiles

You can upload provisioning profiles with the .mobileprovision extension, providing a unique Reference name is required for each uploaded profile.

Alternatively, you can automatically fetch the provisioning profiles from the Apple Developer Portal based on your team’s App Store Connect API key. The bundle identifier is listed for every available profile along with it’s name. The profiles are displayed by category: Development profiles, Ad Hoc profiles, App Store profiles, and Enterprise profiles. For each selected profile, it is necessary to provide a unique Reference name, which can be later used in codemagic.yaml to fetch the profile.

The profile’s type, team, bundle id, and expiration date are displayed for each profile added to Code signing identities. Furthermore, Codemagic will let you know whether a matching code signing certificate is available in Code signing identities (a green checkmark in the Certificate field) or not.

Android keystores

Codemagic lets you upload your Android keystores. When uploading a keystore, it is required that the keystore password, key alias, and key password (if exists) are provided.

Furthermore, it is required that a unique Reference name is assigned to each uploaded keystore, which can be used to fetch the keystore during the build using the codemagic.yaml configuration file.

For each keystore, its common name, issuer, and expiration date are displayed.

Note that the uploaded keystore cannot be downloaded from Codemagic. It is crucial that you store a copy of the keystore file used in Codemagic as all subsequent builds released to Google Play should be signed with the same keystore.

Referencing files in codemagic.yaml

After uploading code signing files to Codemagic, these files can be fetched and used during the build by providing the reference names in the codemagic.yaml configuration.

Apple certificates and profiles

Codemagic provides two means of fetching the required certificates and provisioning profiles during the build with the use of codemagic.yaml. Fetching can either be configured by specifying the distribution type and bundle identifier, or for more advanced use-cases, individual files can be fetched by their reference names.

Fetching files by distribution type and bundle identifier

To fetch all uploaded signing files matching a specific distribution type and bundle identifier during the build, define the distribution_type and bundle_identifier fields in your codemagic.yaml configuration. Note that it is necessary to configure both of the fields.

environment:
    ios_signing:
        distribution_type: ad_hoc  # app_store | development | enterprise
        bundle_identifier: com.example.id

Note that when using the fields distribution_type and bundle_identifier, it is not allowed to configure provisioning_profiles and certificates fields.

When defining the bundle identifier com.example.id, Codemagic will fetch any uploaded certificates and profiles matching the extensions as well (e.g. com.example.id.NotificationService).

Fetching specific files by reference names

For a more advanced configuration, it is possible to pick out specific uploaded profiles and certificates for Codemagic to fetch during the build. To do so, list the references of the uploaded files under the provisioning_profiles and certificates fields, respectively. Note than when fetching individual files, the fields distribution_type and bundle_identifier are not allowed.

environment:
    ios_signing:
        provisioning_profiles:
            - profile_reference
            - ...
        certificates:
            - certificate_reference
            - ...

Codemagic saves the files to the following locations on the build machine:

  • Profiles: ~/Library/MobileDevice/Provisioning Profiles
  • Certificates: ~/Library/MobileDevice/Certificates

It is additionally possible to include names for environment variables that will point to the file paths on the build machine.

environment:
    ios_signing:
        provisioning_profiles:
            - profile: profile_reference
              environment_variable: THIS_PROFILE_PATH_ON_DISK
            - ...
        certificates:
            - certificate: certificate_reference
              environment_variable: THIS_CERTIFICATE_PATH_ON_DISK
            - ...

Using profiles

To apply the profiles to your project during the build, add the following script before your build scripts:

scripts:
    ... your dependencies installation
    - name: Set up code signing settings on Xcode project
        script: xcode-project use-profiles
    ... your build commands

Android keystores

To tell Codemagic to fetch the uploaded keystores from the Code signing identities section during the build, list the reference of the uploaded keystore under the android_signing field.

Fetching a single keystore file

environment:
    android_signing:
        - keystore_reference

Default environment variables are assigned by Codemagic for the values on the build machine:

  • Keystore path: CM_KEYSTORE_PATH
  • Keystore password: CM_KEYSTORE_PASSWORD
  • Key alias: CM_KEY_ALIAS
  • Key alias password: CM_KEY_PASSWORD

It is necessary to either set up a key.properties file in a separate script with these values or reference them in your build.gradle depending on how your Android code signing is configured.

Fetching multiple keystore files

When fetching multiple keystores during a build, it is necessary to include names for environment variables that will point to the file paths on the build machine.

environment:
    android_signing:
        - keystore: keystore_reference_1
          keystore_environment_variable: THIS_KEYSTORE_PATH_ON_DISK_1
          keystore_password_environment_variable: THIS_KEYSTORE_PASSWORD_1
          key_alias_environment_variable: THIS_KEY_ALIAS_1
          key_password_environment_variable: THIS_KEY_PASSWORD_1
        - keystore: keystore_reference_2
          keystore_environment_variable: THIS_KEYSTORE_PATH_ON_DISK_2
          keystore_password_environment_variable: THIS_KEYSTORE_PASSWORD_2
          key_alias_environment_variable: THIS_KEY_ALIAS_2
          key_password_environment_variable: THIS_KEY_PASSWORD_2