DEV Community: Matt Catalfamo

Bedrock

Matt Catalfamo — Sun, 16 Feb 2025 15:37:00 +0000

How to Build and Manually Sign an iOS App with Fastlane

Matt Catalfamo — Mon, 11 May 2020 04:48:34 +0000

This post will cover how to build and manually code sign an iOS app with Fastlane. Why would you need to do this? If you want/need to distribute an app to different Apple App Store accounts. For example if you have an Enterprise App Store account and want/need to sign the QA build of your app with the enterprise account to distribute internally and then sign the Release build with a normal/publicly available account to distribute to the public.

TL;DR

How to build an iOS app using Fastlane
How to manually code sign your iOS app using Fastlane

Prerequisites:

Knowledge of iOS build process
Knowledge of iOS code signing process
Basic understanding of Fastlane
Install Fastlane following their recommended setup

Assumptions:

You are building your app on a macOS image that doesn't have your signing certificates or provisioning profiles installed.
You have password encrypted signing certificate downloaded to directory on your build machine
You have a mobile provisioning profile downloaded to a directory on your build machine
Automatic code signing is disabled in your Xcode project

For the record, I would recommend if you have a simple iOS project that you use Fastlane match and Xcode automatic code signing. But sometimes in the real world there are restrictions and external reasons to have to do manual code signing, so we will go through the process of building and signing manually. Here is the process.

Lets get started

Create a new Fastfile, this can be done by using Fastlane's cli tool
fastlane init

This creates a Fastlane directory with a Fastfile.

Your fastfile will look something like this:

default_platform(:ios)

platform :ios do
  desc "Description of what the lane does"
  lane :custom_lane do
    # add actions here: https://docs.fastlane.tools/actions
  end
end

I am going to rename the default lane that was created to "build" and I will add the command line options array |options| so we can have access to that later on.

platform :ios do
  desc "Build app"
  lane :build do |options|

  end
end

Now that the setup is done we can continue on. First we need to create a new keychain, second install our provisioning profiles, and lastly import the certificates.

Since we may have different profiles or certificates for different builds of our app, let's create a function called setupCodeSigning. The function will take 4 parameters- keychainPassword, certificatePassword, profilePath, and certificatePath.

keychainPassword: Made up password to set for your keychain you are creating on the Mac you are building your iOS app.

certificatePassword: The certificate password you used to encrypt your signing certificate

profilePath: Path to the provisioning profile (ie: ./dependencies/profile-release.mobileprovision) on your build machine

certificatePath: Path to the certificate (ie: ./dependencies/certificate.p12)

def setupCodeSigning(keychainPassword, certificatePassword, profilePath, certificatePath)

end

Now let's create the keychain. We can use the create_keychain plugin.

Make sure you set a name for the keychain because we will reference it when importing the certificates. If your use case needs other parameters, refer to the create_keychain plugin documentation for more details.

def setupCodeSigning(keychainPassword, certificatePassword, profilePath, certificatePath)
  create_keychain(
    name: "CI",
    password: keychainPassword,
    default_keychain: true,
    unlock: true,
    timeout: 3600,
    lock_when_sleeps: false
  )
end

Now that we have the keychain created we need to install the provisioning profile(s). We can use the install_provisioning_profile plugin. Be sure to pass the profilePath parameter as the path variable to the plugin.

def setupCodeSigning(keychainPassword, certificatePassword, profilePath, certificatePath)
  create_keychain(
    name: "CI",
    password: keychainPassword,
    default_keychain: true,
    unlock: true,
    timeout: 3600,
    lock_when_sleeps: false
  )
  install_provisioning_profile(path: profilePath)
end

Last, import the certificate(s) to the keychain by passing the certificate path, keychain name that we called our keychain, and the password we made up for the keychain.

The setupCodeSigning function should look like this:

def setupCodeSigning(keychainPassword, certificatePassword, profilePath, certificatePath)
  create_keychain(
    name: "CI",
    password: keychainPassword,
    default_keychain: true,
    unlock: true,
    timeout: 3600,
    lock_when_sleeps: false
  )
  install_provisioning_profile(path: profilePath)
  import_certificate(
    certificate_path: certificatePath,
    certificate_password: certificatePassword,
    keychain_name: "CI",
    keychain_password: keychainPassword
  )
end

Now that the hard part is over we can call the setupCodeSigning function in the build lane before we build the app. The build lane will now look like this:

lane :build do |options|
    begin
      setupCodeSigning(ENV["MATCH_PASSWORD"], ENV["CERTIFICATE_PASSWORD"], './path-to-your-profile/your-profile.mobileprovision', './path-to-your-certificate/certificate.p12')

      cocoapods(clean_install: true, use_bundle_exec: false, error_callback: true)

      build_app(
        scheme: "your-scheme", 
        configuration: 'Release'
      )

      upload_to_testflight(
        username: options[:appStoreEmail],
        skip_waiting_for_build_processing: true,
        skip_submission: true)

    rescue => exception
      on_error(options[:slackUrl], "Build Failed", "#slack-channel", exception)
    end
  end

Optional: I like to add a "begin, rescue" block around the build to catch any errors and send them to a slack channel if anything fails for convenience. slack plugin

Our complete fast file should look like this:

platform :ios do
  desc "Build app"
  lane :build do |options|
    begin
      setupCodeSigning(ENV["KEYCHAIN_PASSWORD"], ENV["CERTIFICATE_PASSWORD"], './path-to-your-profile/your-profile.mobileprovision', './path-to-your-certificate/certificate.p12')

      cocoapods(clean_install: true, use_bundle_exec: false, error_callback: true)

      build_app(
        scheme: "your-scheme", 
        configuration: 'Release'
      )

      upload_to_testflight(
        username: options[:appStoreEmail],
        skip_waiting_for_build_processing: true,
        skip_submission: true)

    rescue => exception
      on_error(options[:slackUrl], "Build Failed", "#slack-channel", exception)
    end
  end
end


def setupCodeSigning(keychainPassword, certificatePassword, profilePath, certificatePath)
  create_keychain(
    name: "CI",
    password: keychainPassword,
    default_keychain: true,
    unlock: true,
    timeout: 3600,
    lock_when_sleeps: false
  )
  install_provisioning_profile(path: profilePath)
  import_certificate(
    certificate_path: certificatePath,
    certificate_password: certificatePassword,
    keychain_name: "CI",
    keychain_password: keychainPassword
  )
end

def on_error(slackUrl, message, channel, exception)
  slack(
    slack_url: slackUrl,
    channel: channel,
    message: "iOS App :appleinc: " + message,
    success: false,
    payload: {},
    default_payloads: [],
    attachment_properties: { # Optional, lets you specify any other properties available for attachments in the slack API (see https://api.slack.com/docs/attachments).
      color: "#FC100D",
      fields: [
        {
          title: "Error",
          value: exception.to_s,
        },
      ]
    }
  )

  raise exception
end

Runtime Configurations with React

Matt Catalfamo — Thu, 10 Oct 2019 02:55:04 +0000

Most of the time using custom build time environment variables are suitable but runtime variables can be valuable in addition to or in place of environment variables.

Runtime configurations or variables, can be beneficial when you need to change a configuration at run time. Some examples of variables you could load at runtime is theme data or api urls.

Do not store any secrets (such as private API keys) in your environment or runtime variables!

Why runtime variables?

Build app only once and deploy the same build to multiple environments (i.e. dev, qa, prod)
Configurations can be changed/updated after the app is deployed
Load configurations from an external source
Save time - Build pipelines can take long periods of time some with many steps (i.e. infrastructure steps, build steps, tests, etc). Loading configurations during runtime can help reduce the amount of times your app is built.

How do runtime variables work?

Runtime variables get loaded into the browser's window object when the index.html of a single page application gets loaded.

In the <head> or <body> of the html file we can run a Javascript snippet that sets up the configurations on the window object.

Javascript code in the index.html file will get loaded synchronously from top to bottom as long as the async flag is not present. By placing the code to load our snippet before the main bundle it can be guaranteed that the values will be set on the window object and accessible when your main javascript bundle is loaded.

Let’s look at how this can be accomplished.

Create a new file called runtime-config.js and setup some variables

// runtime-config.js
window['runConfig'] = {
    apiUrl: 'test.com/api'
}

To load the script in the index.html file add the script tag to the file inside either the <head> or <body> tag. If you are starting with Create React App the file will be located at <project_root>/public/index.html

<script src="%PUBLIC_URL%/runtime-config.js"></script>

// index.html
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    <meta name="theme-color" content="#000000">
    <link rel="manifest" href="%PUBLIC_URL%/manifest.json">
    <link rel="shortcut icon" href="%PUBLIC_URL%/favicon.ico">

    <!-- runtime config -->
    <script src="%PUBLIC_URL%/runtime-config.js"></script>
    <!-- runtime config -->

    <title>React App</title>
  </head>
  <body>
    <noscript>
      You need to enable JavaScript to run this app.
    </noscript>
    <div id="root"></div>
  </body>
</html>

How to use in a React component

To access the variables that are setup in the runtime-config file, from your app files you can reference the window object.

window['runConfig']

Example usage in a React component:

export const MyComponent = () => {
  const { apiUrl } = window['runConfig'];
  return (
    <div>Runtime config apiUrl: {apiUrl}</div>
  )
}

Full Example:

https://github.com/mattcat10/react-runtime-config

Notes:

Don't use runtime configurations if your configurations are really large. They are loaded synchronously and could slow down your initial load time of your app
This post explains how to use runtime configurations in a react app, but the same concept can be applied to any SPA framework.