Signing macOS apps

How to set up macOS code signing in codemagic.yaml

All macOS applications have to be digitally signed before they can be installed on devices or made available to the public via the Mac App Store or outside of the Mac App Store.

Automatic vs Manual code signing

Signing macOS apps requires a Signing certificate (App Store development or distribution certificate in .p12 format) and a Provisioning profile. In Manual code signing you save these files as Codemagic Environment variables and manually reference them in the appropriate build steps.

In Automatic code signing, Codemagic takes care of Certificate and Provisioning profile management for you. Based on the certificate private key that you provide, Codemagic will automatically fetch the correct certificate from the App Store or create a new one if necessary.

Certificate types

There are several certificate types you can choose to sign your macOS app, depending on the distribution method you plan to use.

• MAC_APP_DEVELOPMENT certificate allows you to build your app for internal testing and debugging.
• MAC_APP_DISTRIBUTION certificate is used to sign a Mac app before submitting it to the Mac App Store
• MAC_INSTALLER_DISTRIBUTION is used to sign and submit a Mac Installer Package to the Mac App Store
• DEVELOPER_ID_APPLICATION is used to sign a Mac app before distributing it outside the Mac App Store
• DEVELOPER_ID_INSTALLER is used to sign a Mac Installer Package before distributing it outside the Mac App Store

For example, in order to publish to Mac App Store, the application must be signed with a Mac App Distribution certificate using a Mac App Store provisioning profile. If you want to create a .pkg Installer package, you must use a Mac Installer Distribution certificate.

Obtaining the certificate private key

To enable Codemagic to automatically fetch or create the correct signing certificate on your behalf, you need to provide the corresponding certificate private key. You then have to save that key as a Codemagic environment variable.

• Create a new key
• Use an existing key

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

openssl pkcs12 -in MAC_DISTRIBUTION.p12 -nodes -nocerts | openssl rsa -out mac_distribution_private_key

Automatic code signing

When automatic code signing is used, then most up-to-date signing files are obtained directly from Apple during the build time. This requires that Codemagic has access to your Apple Developer portal account, which is achieved by using App Store Connect API key.

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 > Integrations » App Store Connect API.
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 App Manager access rights, 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.

Configuring environment variables

Provisioning profiles and code signing certificates are obtained from Apple Developer portal with the command app-store-connect fetch-signing-files. App Store Connect API key information can be passed to it via environment variables APP_STORE_CONNECT_KEY_IDENTIFIER, APP_STORE_CONNECT_ISSUER_ID, APP_STORE_CONNECT_PRIVATE_KEY.

• Use App Store Connect integration
• Define environment variables by yourself

cat ios_distribution_private_key | pbcopy

workflows:
  ios-workflow:
    environment:
        groups:
            - code-signing
    integrations:
        app_store_connect: <App Store Connect API key name>

   cat mac_distribution_private_key | pbcopy
 

cat codemagic_api_key.p8 | pbcopy

workflows:
  macos-workflow:
    name: macOS Workflow
    environment:
      groups:
        - appstore_credentials

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:
      - name: Set up keychain to be used for code signing using Codemagic CLI 'keychain' command
        script: keychain initialize
      - name: Fetch signing files
        script: | 
          app-store-connect fetch-signing-files "$BUNDLE_ID" \
            --platform MAC_OS \
            --type MAC_APP_STORE \
            --create
      - name: Fetch Mac Installer Distribution certificates
        script: |  
            app-store-connect certificates list --type MAC_APP_DISTRIBUTION --save || \
            app-store-connect certificates create --type MAC_APP_DISTRIBUTION --save
      - name: Set up signing certificate
        script: keychain add-certificates
      - name: Set up code signing settings on Xcode project
        script: xcode-project use-profiles

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, you need the following:

• Signing certificate: Your development or distribution certificate in .P12 format.
• Certificate password: The certificate password if the certificate is password-protected.
• Provisioning profile: You can get it from Apple Developer Center > Certificates, Identifiers & Profiles > Profiles and select the provisioning profile you would like to export and download.

1. Open your Codemagic app settings, and go to the Environment variables tab.
2. Enter CM_CERTIFICATE as the Variable name.
3. Run the following command on the certificate file to base64 encode it and copy to clipboard:

   cat ios_distribution_certificate.p12 | base64 | pbcopy

4. Paste into the Variable value field.
5. Enter a variable group name, e.g. appstore_credentials.
6. Make sure the Secure option is selected so that the variable can be protected by encryption.
7. Click the Add button to add the variable.
8. Repeat steps 2 - 7 to create variables CM_PROVISIONING_PROFILE and INSTALLER_CERTIFICATE. Paste the base64 encoded values for both of these files.
9. Add the CM_CERTIFICATE_PASSWORD and INSTALLER_CERTIFICATE_PASSWORD variables, make them Secure and add them to the same variable group.

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:
      - 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 ${CM_PROVISIONING_PROFILE} | base64 --decode > "$PROFILE_PATH"
            echo "Saved provisioning profile $PROFILE_PATH"
      - name: Set up signing certificate
        script: | 
            echo $CM_CERTIFICATE | base64 --decode > /tmp/certificate.p12
            if [ -z ${CM_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 $CM_CERTIFICATE_PASSWORD
            fi

            echo $INSTALLER_CERTIFICATE | base64 --decode > /tmp/installer_certificate.p12
            if [ -z ${INSTALLER_CERTIFICATE_PASSWORD+x} ]; then
                # when using a certificate that is not password-protected
                keychain add-certificates --certificate /tmp/installer_certificate.p12
            else
                # when using a password-protected certificate
                keychain add-certificates --certificate /tmp/installer_certificate.p12 --certificate-password $INSTALLER_CERTIFICATE_PASSWORD
            fi
      - name: Set up code signing settings on Xcode project
        script: xcode-project use-profiles

Creating the Installer package

To package your application into an .pkg Installer package and sign it with the Mac Installer Distribution certificate, use the following script:

  scripts:
    - name: Package application
      script: | 
      set -x
    
      # Command to find the path to your generated app, may be different
      APP_NAME=$(find $(pwd) -name "*.app")  
      cd $(dirname "$APP_NAME")
    
      PACKAGE_NAME=$(basename "$APP_NAME" .app).pkg
      xcrun productbuild --component "$APP_NAME" /Applications/ unsigned.pkg  # Create and unsigned package

      # Find the installer certificate common name in keychain
      INSTALLER_CERT_NAME=$(keychain list-certificates \
        | jq '.[]
        | select(.common_name
        | contains("Mac Developer Installer"))
        | .common_name' \
        | xargs)
      
      xcrun productsign --sign "$INSTALLER_CERT_NAME" unsigned.pkg "$PACKAGE_NAME" # Sign the package
    
      rm -f unsigned.pkg                                                       # Optionally remove the not needed unsigned package

Notarizing macOS applications

Notarization is a process where Apple verifies your application to make sure it has a Developer ID code signature and does not contain malicious content. All apps distributed outside the Mac App Store have to be notarized.

Notarizing an app during the Codemagic build process is possible using the altool command as follows:

xcrun altool --notarize-app -f <file> --primary-bundle-id <bundle_id>
           {-u <username> [-p <password>] | --apiKey <api_key> --apiIssuer <issuer_id>}
           [--asc-provider <name> | --team-id <id> | --asc-public-id <id>]