Setup Fastlane MATCH for iOS
In this article I will be showing you how to create fastlane match to automate the process of building and releasing mobile apps.
Note: If you are looking to add existing certificates to match git repo, Go to step 9
What is fastlane?
Fastlane is an open source platform aimed at simplifying Android and iOS deployment.
fastlane lets you automate every aspect of your development and release workflow.
- Automate Screenshots — Automatically generate localized screenshots for the app store.
- Beta deployments — Easily distribute beta builds for testers.
- App store deployments — Publish a new release to the app store in seconds.
- Code signing — Reliably and consistently code sign your app, no more headaches.
— Setting up fastlane match:
What is fastlane match?
A new approach to iOS code signing: Share one code signing identity across your development team to simplify your codesigning setup and prevent code signing issues.
match creates all required certificates & provisioning profiles and stores them in a separate git repository. Every team member with access to the repo can use those credentials for code signing. match also automatically repairs broken and expired credentials. It’s the easiest way to share signing credentials across teams.
Before setting up fastlane match, Lets start by installing fastlane on the local machine,
sudo gem install fastlane
Step 1: Create a git repo.
Create a new, private Git repo (e.g in specific project in bitbucket.org/xxx) and you can name it certificates.
Note: Make sure the repository is set to private
Step 2: Apple developer account
Create a new, shared Apple developer account, (like projectname@company.com) that will be shared across your team from now on.
If you already have one, ignore this step. You can also add the username and password fields for the apple account within the match file( You’ll know about match file).
Step 3: Setup ssh key
Setup ssh key for your git account to clone the repository which will be used by fastlane match file.
This is important since match require username and password to access git repo. Without authentication the build fails.
Using SSH, You can authenticate for the repository where certificates and provisioning profiles will be stored.
Step 4: Initiate fastlane
Initiate fastlane for your project folder (Which contains .xcworkspace or .xcodeproj)
fastlane initproject1$: fastlane init[17:13:06]: Detected iOS/Mac project in current directory...
[17:13:06]: This setup will help you get up and running in no time.
[17:13:06]: fastlane will check what tools you're already using and set up
[17:13:06]: the tool automatically for you. Have fun!
[17:13:06]: Created new folder './fastlane'.
[17:13:06]: $ xcodebuild -list -workspace ./project1.xcworkspace
2017-06-20 17:13:07.122 xcodebuild[65932:6932431] [MT] PluginLoading: Required plug-in compatibility UUID DFFB3951-EB0A-4C09-9DAC-5F2D28CC839C for plug-in at path '~/Library/Application Support/Developer/Shared/Xcode/Plug-ins/SwiftLintXcode.xcplugin' not present in DVTPlugInCompatibilityUUIDs
[17:13:08]: $ xcodebuild -showBuildSettings -workspace ./project1.xcworkspace -scheme project1
2017-06-20 17:13:08.331 xcodebuild[65937:6932494] [MT] PluginLoading: Required plug-in compatibility UUID DFFB3951-EB0A-4C09-9DAC-5F2D28CC839C for plug-in at path '~/Library/Application Support/Developer/Shared/Xcode/Plug-ins/SwiftLintXcode.xcplugin' not present in DVTPlugInCompatibilityUUIDs
[17:13:09]: Your Apple ID (e.g. fastlane@krausefx.com): member@project.com
Verifying that app is available on the Apple Developer Portal and iTunes Connect...
[17:15:49]: Starting login with user 'member@project.com'
A folder with name fastlane is created inside the project folder. It contains three files initially out of which two are important.
- Appfile — The
Appfile
stores useful information that are used across allfastlane
tools like your Apple ID or the application Bundle Identifier, to deploy your lanes faster and tailored on your project needs
Appfile
2. Fastfile — Defines the “lanes” that drive the behavior of fastlane
Step 5: Update fastfile
Update the fastfile with required lanes such as
beta
,appstore
etc.
If you want to know about these commands. Click here.
In this example, we are using beta
for uploading the build to crashlytics
.
There are few additional things that are shown in this example. (e.g: Bumping the build version
, configuring slack
etc.)
Step 6: Setting up a match
— To setup match
fastlane match init
You need to provide url
for the git private repo. (Recommended to use ssh instead of https, Follow step 1 and step 3)
This will create a matchfile
in current directory (or in your ./fastlane/folder)
By default, it contains git URL, App Identifier, git username.
Update the file with the following commands.
Fastlane will automatically take the
username
,password
for git repo and authenticate.MATCH_PASSWORD is password for the p.12 files that will be stored in the repo.
Step 7: Generating certificates
Run the following command in the terminal.
fastlane match appstore
You can also use development
, adhoc
, enterprise
depending on your purpose.
This will create a new certificate and provisioning profile (if required) for the type selected (
development
,adhoc
,enterprise, appstore
)and store them in your Git repo. If you previously ranmatch
, it will automatically install the existing profiles from the Git repo.
The provisioning profiles are installed in ~/Library/MobileDevice/Provisioning Profiles
while the certificates and private keys are installed in your local keychain.
Note: To get a more detailed output of what match
is doing, use
fastlane match --verbose
You are all done!!!!!!!!!!!!!!!!
Step 8: Uploading build to crashlytics (optional)
Try uploading the build to fabric from local machine to make sure everything is working as expected.
Make sure you have the api_key
and build_secret
for the application in fabric to upload.
Since we have already configured beta
lane in fastfile
to upload build to crashlytics.
Run the following command from the project folder.
fastlane beta
Step 9(Optional): Manually adding existing certificates to git repository.
Warning: Manually editing your match repo can introduce unexpected behavior and is not recommended. Proceed with caution.
NOTE: GitHelper doesn't work anymore. Fastlane has recently updated the process.
Run the following commands in your terminal:
$ bundle console
Then, require match and set the appropriate parameters:
irb(main):001:0> require 'match'
irb(main):002:0> git_url = 'https://github.com/fastlane/example-certificate-repo'
=> "https://github.com/fastlane/example certificate-repo"
irb(main):003:0> shallow_clone = false
=> false
irb(main):004:0> ENV["MATCH_PASSWORD"] = 'example-password'
=> "example-password"
irb(main):005:0> branch = 'master'
=> "master"
Now create an instance of Storage
and Encryption
. The download
method on Storage
will clone the repo and the decrypt_files
method on Encryption
will decrypt the repo for you. Assign the return values to storage
and encrypt
, which we'll need later when we re-encrypt:
irb(main):006:0> storage = Match::Storage.for_mode("git", { git_url: git_url, shallow_clone: shallow_clone, git_branch: branch, clone_branch_directly: false}) irb(main):007:0> storage.download irb(main):008:0> encryption = Match::Encryption.for_storage_mode("git", { git_url: git_url, working_directory: storage.working_directory}) irb(main):009:0> encryption.decrypt_files
[14:24:42]: 🔓 Successfully decrypted certificates repo
irb(main):010:0> storage.working_directory
=> "/var/folders/ql/4rgq9x7j51n_971xb332w9lc0000gn/T/d20181105-65220-1oalh6v"
The directory beginning with /var/folders
contains the decrypted git repo. Modify it as needed.
If you are updating a .p12
file, ensure it's exported from the keychain without a password since match doesn't support importing private keys with a password.
Warning: Do not commit your changes. Allow fastlane to do that for you.
In the Ruby console, call encryption.encrypt
and storage.save_changes!
. For example:
irb(main):010:0> encryption.encrypt_files irb(main):011:0> files_to_commit = Dir[File.join(storage.working_directory, "**", "*.{cer,p12,mobileprovision}")]irb(main):012:0> storage.save_changes!(files_to_commit: files_to_commit)
Or If you don't want to specify the files_to_commit then :
irb(main):010:0> encryption.encryptirb(main):011:0> storage.save_changes!
Your changes will be encrypted, committed, and pushed
Note: If your keychain doesn’t include the encryption passcode, you may be prompted for it. If so, just enter the same password you used to decrypt it.
For additional information: Click here
Conclusion:
Fastlane takes care of
- Authenticating apple developer account.
- Authenticating git repo.
- Installing certificates (if not available, it creates required certificates and provisioning profiles).
- Compiling the project.
- Code signing.
- Uploading the .ipa to the fabric.
Issues:
During this process, you might face a few issues. I’ve covered some of them that I encountered during this setup.
- Authentication error to an apple developer account.
- Certificates not found for codesigning (Setup the project in xcode with installed certificates and provisioning profiles from git repo.)
- No matching code signing entities.
- If you manually update these certificates in apple developer portal, then the certificates in git repo will be outdated and are of no use. Make sure you manually update the git repo.
- Cloning the git repo and updating the certificates and provisioning profiles won’t work, since the git repo is encrypted and password protected.
Please don’t forget to clap, if you find this article helpful.
Thanks!!