Skip to main content

iOS code signing with automatic provisioning

Abstract

Automatic code signing means automatically managing the provisioning profiles that are available on your Apple Developer Portal account. If you set up some form of authentication to your Apple account, Bitrise can download and install the provisioning profile for your app during the build process.

On Bitrise, we're aiming to make iOS code signing as simple as possible for you. As such, we've done our best to automate a lot of the process. Several of our Steps have a built-in option for automatic code signing management to make configuration a lot more streamlined.

Automatic code signing in this context means automatically managing the provisioning profiles that are available on your Apple Developer Portal account. If you set up some form of authentication to your Apple account, Bitrise can download and install the provisioning profile for your app during the build process.

To use this feature, you need to:

Uploading iOS code signing certificates to Bitrise

All iOS code signing methods require you to export and upload your iOS code signing certificates to Bitrise.

Generating code signing files

If you don't have the necessary code signing files ready, you can generate new files: Generating iOS code signing files

To upload the certificates to Bitrise, first you need to export the files in the .p12 file format: you can do this manually or using Bitrise's open source codesigndoc tool. Once you successfully exported the files, you need to upload them to Bitrise. You have three options:

Upload the distribution AND the development signing certificates

We strongly recommend uploading BOTH the development and distribution signing certificates for your project. Without the different types of certificates, you will not be able to generate different types of signed IPA files.

To export your certificates and upload them to Bitrise in the Workflow Editor:

  1. Make sure you have your .p12 certificates exported and ready. You can export the files using either of two options:

  2. Open your app on Bitrise.

  3. Click the Workflows button on the main page.

    opening-workflow-editor.png
  4. Go to the Code Signing tab.

  5. Drag-and-drop or click the .p12 certificate(s) in the Add the private key (.p12) for signing field.

    upload-certificates.png

Apple services authentication for automatic provisioning

To take advantage of the Bitrise Steps that offer built-in, automated iOS code signing options, you need to set up Apple service authentication. For these Steps, you have two options.

Table 1. Apple services authentication options for iOS code signing

Authentication method

How it works

When to use

API key authentication (recommended)

You connect your App Store Connect account to Bitrise using an API key.

We recommend using this option unless you are using an account with Apple Developer Enterprise Program.

Apple ID authentication

You connect your Apple ID to Bitrise. If two-factor authentication is enabled on your Apple account, you will have to provide the App-specific password during this process. Your authentication expires in 30 days and you will have to refresh the connection.

You should only use this solution if:

  • You cannot access API key for any reason.

  • you are using an account with Apple Developer Enterprise Program.

You can also consider using manual provisioning.


Configuring the Steps for automatic provisioning

There are two ways to handle automatic provisioning on Bitrise:

  • Using the official Xcode Steps that can both manage code signing files and build your app.

  • Using the Manage iOS Code Signing Step.

Table 1, “Steps with automatic provisioning options describes the use cases for the two methods. To be able to configure the necessary Steps, check out either:

Don't use the Certificate and profile installer Step

If you use automatic provisioning, you never need to use the Certificate and profile installer Step.

Table 1. Steps with automatic provisioning options

Steps

How they work

When to use

Xcode Steps:

  • Xcode Archive and Export for iOS

  • Export iOS and tvOS Xcode Archive

  • Xcode build for testing for iOS

These Steps set up code signing in your Xcode project automatically with nearly zero configuration.

We recommend using these Steps in most scenarios.

Manage iOS Code Signing Step

This Step will set up code signing in your Xcode project before running a build.

You can use this dedicated Step if:

  • You are building the app from script or fastlane.

  • You have a cross-platform project. For example, React Native, Flutter, Ionic or Cordova.

  • You are building a macOS app.


Provisioning profiles only

These Steps will NOT automatically download .p12 signing certificates, only provisioning profiles. You must upload certificates to Bitrise yourself.

Using the Xcode Steps

You can use any of the Xcode Steps with built-in automatic management of code signing assets.

  1. Set up connection to Apple services.

    You can choose between API key authentication or Apple ID authentication. We generally recommend API key authentication.

  2. Add any of the following Steps to your Workflow, depending on what you need:

    • Xcode Archive and Export for iOS: Builds your Xcode app and exports an IPA of the type you choose.

    • Export iOS and tvOS Xcode Archive: Exports an IPA from an already existing archive.

    • Xcode build for testing for iOS: Builds your Xcode app with the build-for-testing action.

  3. Set the Automatic code signing method input to the Apple service authentication type you set up.

    For example, if you chose API key authentication, choose the api-key option.

Example 1. YAML example for setting code signing method

In this example, the Xcode Archive and Export for iOS Step is set to use API key authentication.

- xcode-archive@4:        
    inputs:        
    - automatic_code_signing: api-key

In most cases, the default values for all other inputs are sufficient if you set up your Apple connection correctly.


Using the Manage iOS Code Signing Step

Use our dedicated Step for automatically managing code signing assets if you do not use one of the Xcode Steps to build your iOS app, or if you have a cross-platform app.

  1. Add the Manage iOS Code Signing Step after any dependency installer Step in your Workflow, such as Run CocoaPods install or Carthage.

    manage-ios-code-signing-step.png
  2. Set the Automatic code signing input to the Apple service connection you want to use.

    You can choose between API key authentication or Apple ID authentication.

  3. If you use Apple ID authentication, you should also enter your team ID to The Developer Portal team ID input.

  4. Make sure you do NOT modify your Xcode project after this Step.

    For example, don't change the bundle ID.

  5. Add a Step that builds and archives the app, such as the fastlane Step.