Code Signing for iOS Projects#
This guide describes how to set up code signing in CI/CD for your iOS project on Semaphore using Fastlane Match.
If you'd like Semaphore to push new builds for distribution to HockeyApp, Fabric Beta or TestFlight, then CI must have access to the code signing certificate and provisioning profiles that are required to build the app for such distribution.
Below we show you how to do that.
Basic configuration of iOS projects#
We assume you have a working iOS project configured to run on Semaphore. If you're new to Semaphore or not sure how to configure your iOS project, see the open source demo project and associated tutorial for an example.
In addition, we assume that you installed and configured Fastlane. If not, please visit the Fastlane setup guide to learn how to configure Fastlane for your project.
If you are new to code signing, we recommend you to visit the Code Signing Guide and read it.
The Match tool has extensive documentation on how to configure and use it, which you can find at Fastlane Docs.
In a nutshell, what we are aiming at is:
- Your iOS project configured with Fastlane and Match.
- You have a separate private Git repository that stores code signing certificates and provisioning profiles.
- Your CI/CD project on Semaphore works with these two repositories.
Setting up Fastlane Match#
Before setting up provisioning profiles and distributing builds, you need an App ID for your app and App Store Connect application. If you don't have them yet, you can either create them manually in the Apple developer account and App Store Connect website, or you can use Fastlane's produce
action to create both from command line.
Once you have your App ID and App Store Connect Application, you can proceed to configuring code signing for your project.
To set up the match
, you'll need a private Git repository.
Follow the documentation: run the init
command from the root
directory of your iOS project and follow the prompts:
$ bundle exec fastlane match init
This will configure match
with your private Git URL and password locally on your computer. With this, you are now ready to create provisioning profiles for your app.
The following will generate a 'development' provisioning profile so that you can run your app on the device connected to Xcode:
$ bundle exec fastlane match development
This will generate an 'adhoc' provisioning profile so that other people can run your app on their devices through non-App Store distribution like HockeyApp or Fabric Beta:
$ bundle exec fastlane match adhoc
This will generate an 'appstore' provisioning profile so that your app can be distributed through TestFlight and App Store:
$ bundle exec fastlane match appstore
Preparing your Xcode project for use with Fastlane Match#
By default, the Xcode uses "automatic" code signing that uses Xcode's preferences to manage the signing certificates and provisioning profiles. While this works on your local computer, it won't work in the CI environment. That's why the project should switch to the "manual" code signing.
To do this, in the "General" tab of your app target in Xcode, uncheck the "Automatically manage signing" and then select the provisioning profiles generated by match for each "Provisioning Profile" dropdowns for each configuration (Sections "Signing (Debug)" and "Signing (Release)").
Adding Semaphore Plugin to Fastlane#
In order to configure Fastlane for the CI/CD environment, please install the Semaphore plugin:
$ bundle exec fastlane add_plugin semaphore
The plugin provides setup_semaphore
action that configures temporary Keychain and switches match
to 'readonly' mode.
Adding Match to the Fastlane Lane#
As mentioned earlier, CI doesn't have access to your developer account unless you provide the credentials in the configuration for the match
. To make this work, we need to add a match
action to the lanes that will publish your app for distribution.
# fastlane/Fastfile
default_platform(:ios)
platform :ios do
before_all do
setup_semaphore
end
desc "Build and run tests"
lane :test do
scan
end
desc "Ad-hoc build"
lane :adhoc do
match(type: "adhoc")
gym(export_method: "ad-hoc")
end
desc "TestFlight build"
lane :build do
match(type: "appstore")
gym(export_method: "app-store")
end
end
Adding a deploy key to the Semaphore project#
Now that we have configured our tools to use appropriate configuration, we must also provide a way for Semaphore to access the Git certificates repo, and the Apple Developer portal.
To allow Semaphore to download certificates from your private certificates repository, you need to create a deploy key and add it to Semaphore secrets. Adding a deploy key is described in Using private dependencies.
If you have not installed the sem
command line tool, this is a good time to install it - see the sem reference.
To store the deploy key as a secret file in the Semaphore environment:
$ sem create secret ios-cert-repo -f id_rsa_semaphore:/Users/semaphore/.keys/ios-cert-repo
Mounting the ios-cert-repo
secret in your pipeline configuration will create the deploy key file in the ~/.keys
directory when your CI/CD jobs run on Semaphore.
For an introduction to secrets on Semaphore, see the guided tour on secrets.
Adding the Match passphrase to a secret#
Next, add the URL for the certificates repository and the encryption password as environment variables that will be accessible in CI. We recommend also adding the App Store developer account's credentials to the same secret:
$ sem create secret fastlane-env \
-e MATCH_GIT_URL="<your ssh git url>" \
-e MATCH_PASSWORD="<password for decryption>" \
-e FASTLANE_USER="<App Store developer's Apple ID>" \
-e FASTLANE_PASSWORD="<App Store developer's password>"
⚠️ As a security note, it is highly advisable to create a separate App Store "developer" account that will be used only in the CI/CD environment. The same approach is advisable for accessing the private Git certificates repository.
In a similar fashion, you can also add API keys for another distribution platform that you use, such as HockeyApp or Fabric Beta. Consult with the respective platform's documentation to see which environment variables and secrets you need to include.
With these secrets and configuration in place, Semaphore will be able to access the code signing certificates and provisioning profiles in order to build and distribute your app in your CI/CD workflow.
Sample configuration files#
After you have configured Match, Fastlane and environment variables, you are ready to build your app on Semaphore. The following are the examples of 'Fastfile' and semaphore.yml
configuration files that will run test and build on every code push.
For Fastlane:
# fastlane/Fastfile
default_platform(:ios)
platform :ios do
before_all do
# install the semaphore plugin with `fastlane add_plugin semaphore`
setup_semaphore
end
desc "Run Tests"
lane :test do
scan
end
desc "Build"
lane :build do
match(type: "appstore")
gym(export_method: "app-store")
end
desc "Ad-hoc build"
lane :adhoc do
match(type: "adhoc")
gym(export_method: "ad-hoc")
end
end
For Semaphore:
# .semaphore/semaphore.yml
version: v1.0
name: Semaphore iOS example
agent:
machine:
type: a1-standard-4
os_image: macos-xcode12
blocks:
- name: Run tests
task:
env_vars:
- name: LANG
value: en_US.UTF-8
prologue:
commands:
- checkout
- cache restore
- bundle install --path vendor/bundle
- cache store
jobs:
- name: Fastlane test
commands:
- bundle exec fastlane ios test
secrets:
- name: fastlane-env
- name: Build app
task:
env_vars:
- name: LANG
value: en_US.UTF-8
prologue:
commands:
- checkout
- cache restore
- bundle install --path vendor/bundle
jobs:
- name: Fastlane build
commands:
- chmod 0600 ~/.keys/*
- ssh-add ~/.keys/*
- bundle exec fastlane build
secrets:
- name: fastlane-env
- name: ios-cert-repo
Example application on GitHub#
To see how an iOS project can be configured on Semaphore, see the semaphore-demo-ios-swift-xcode
GitHub repository.