Match (Fastlane): What It Is, Certificate Management, and Setup in Development

What Is Match (Fastlane)?

Match (Fastlane) is a component of the Fastlane ecosystem designed for centralized management of Code Signing certificates and Provisioning Profiles for iOS development. It solves the problem of synchronizing signatures between team members and automates certificate setup in CI/CD pipelines without developer intervention.

Without Match, each team member manually generates certificates through Xcode or Apple Developer Portal, leading to build conflicts on different machines. Code Signing is the process of digitally signing an iOS application, which confirms its authorship and integrity before installation on a user’s device.

According to Apple Developer Documentation (2025), incorrect certificate configuration is one of the most common causes of rejection when submitting an app to the App Store. Match automatically checks certificate validity and warns about expiring certificates, reducing the risk of build rejection during the Apple verification stage.

Use Match in any project with two or more developers or when you have a CI/CD pipeline — it reduces the time to set up a new team member’s environment from 30 minutes to a single terminal command.

How Match Works: Encrypted Git Storage

Match Architecture is built on the concept of a single source of truth for all iOS team certificates. Instead of local storage in each developer’s keychain, Match consolidates certificates in a single Git repository with encryption of each file before storage.

The process consists of three stages. During the initialization stage, Match generates all necessary certificates and profiles through the Apple Developer Portal API. Each file is encrypted using the AES-256 algorithm with a key formed from a user-defined passphrase. Encrypted files are saved to the Git repository and synchronized with the remote server through standard Git push and pull operations.

Certificate Encryption Architecture

Match uses a combination of OpenSSL and a user-defined passphrase to encrypt certificates and profiles. The access key is set through the MATCH_PASSWORD environment variable and is not stored in the repository, preventing leaks even if the Git server is compromised or the repository is publicly accessible.

When requesting a certificate, Match downloads the encrypted file from the repository, decrypts it locally using the passphrase, and installs it into the current machine’s Keychain. After the build completes, certificates can be removed from the Keychain to comply with security policies of corporate environments — this prevents the use of outdated certificates in subsequent builds.

Each certificate is saved with a name containing the application identifier, profile type, and creation date. This structure allows Match to manage certificate versions and, if necessary, roll back changes to a previous state using standard Git revert and reset commands. This is especially useful when a profile is accidentally deleted or overwritten.

Match Setup and Configuration

Match is installed together with Fastlane via the Ruby package manager: gem install fastlane. After installation, initialize the certificate storage with the command fastlane match init, which creates an empty Git repository and generates a Matchfile with a basic configuration template.

# Initialize Match Repository
fastlane match init

Configuration via Matchfile

The Matchfile contains all connection parameters to the certificate storage: Git repository URL, default profile type, application identifiers, and Apple Developer credentials. Example of a typical configuration for a team of five developers:

# Matchfile configuration
git_url("https://github.com/company/certificates.git")
type(:development)
app_identifier(["com.company.app", "com.company.app.extension"])
username("developer@company.com")
team_id("TEAM123456")
git_branch("main")

The type parameter defines the profile type: :development for debugging on developer devices, :appstore for publishing to the App Store, :adhoc for testing on external devices, and :enterprise for corporate In-House distribution outside the App Store. Each type creates a separate directory in the repository, allowing profiles to be organized by target build scenarios.

Match supports several authentication methods for Apple Developer Portal: two-factor authentication via Apple ID, App-Specific Password, and App Store Connect API keys. For CI/CD, API keys are recommended — they do not require interactive confirmation code input and do not block automated builds when a developer’s device changes.

Profile Generation and Synchronization

After configuring the Matchfile, run the command fastlane match development or fastlane match appstore to generate and synchronize profiles. Match automatically creates or updates certificates through the Apple Developer Portal API and saves them to the repository. Apple Developer Portal is Apple’s web interface for managing certificates, application identifiers, and lists of approved developer devices.

On the first run, Match will ask for a passphrase to encrypt the repository. This passphrase must be stored in the CI/CD secret manager (GitHub Actions Secrets, GitLab CI Variables, or Jenkins Credentials) and passed through the MATCH_PASSWORD environment variable. Without it, Match cannot decrypt certificates on other machines or in the CI environment.

Basic Match Commands for Certificate Management

Match Interface consists of a set of commands for creating, updating, synchronizing, and deleting certificates and profiles. Each command corresponds to a specific action in the Code Signing lifecycle: from generation to complete repository cleanup.

Commands for Daily Operations

The command fastlane match development downloads or creates development certificates and profiles for debugging on local devices. Provisioning Profile is a digital document from Apple that links a developer certificate with an application identifier and a list of devices authorized for installation.

For publishing to the App Store, use fastlane match appstore — it generates distribution certificates and AppStore profiles. The command fastlane match adhoc creates profiles for testing on external devices, and fastlane match enterprise for corporate In-House applications.

# Creating Development profiles for debugging
fastlane match development

# Creating AppStore profiles for release
fastlane match appstore

# Importing existing manually created certificates
fastlane match import

The command fastlane match import allows you to add existing certificates to the repository — useful when migrating from manual management to Match. The --readonly parameter blocks any changes to the repository, which is critical for CI environments where the pipeline should not create or delete certificates and profiles automatically.

For a complete repository cleanup, use the command fastlane match nuke. It removes all certificates from the Git storage, from Apple Developer Portal, and from the local machine — a complete reset of Code Signing state for the project. The command is used only in critical conflicts or when migrating to a new Apple Developer account.

Integrating Match into CI/CD Pipeline

CI/CD Integration of Match is one of the tool’s key advantages. In GitHub Actions, GitLab CI, Bitrise, or Jenkins pipelines, Match automatically downloads and installs the correct certificates without developer involvement. This enables fully automated build and signing of iOS applications from commit to a ready IPA.

A typical GitHub Actions configuration includes installing Fastlane, setting up the MATCH_PASSWORD variable, and running Match with the --readonly flag. GitHub Actions is GitHub’s CI/CD platform that automates building, testing, and publishing code based on repository events.

# Installing Fastlane in CI environment
gem install fastlane --no-document

# Running Match in read-only mode without modification rights
fastlane match development --readonly

Before running Match in CI, configure access to the certificate repository. Fastlane automatically clones it based on the git_url parameter from the Matchfile. Repository access is configured via an SSH key or personal access token, which are added to the CI system’s secrets — this ensures certificates are not compromised through public access.

Set the environment variables MATCH_PASSWORD and FASTLANE_APPLE_API_KEY in your CI provider’s secrets. The App Store Connect API key allows Match to authenticate with Apple Developer Portal without two-factor authentication, eliminating interactive prompts in automated builds and preventing pipeline blocking.

Common Errors When Working with Match

Even with correct Match configuration, errors can occur related to expired certificates, profile conflicts, or incorrect environment setup. Match Problem Diagnosis is based on analyzing command logs and checking the Git repository state for certificate relevance.

The most common error — «You need to provide a password for Match» — occurs when the MATCH_PASSWORD environment variable is not set on the machine or in the CI environment. Solution: add MATCH_PASSWORD to system environment variables or pass the password through the --keychain_password parameter when running the Match command.

The second most frequent issue is certificate conflicts when adding a new device to an AdHoc profile. It is resolved with the command fastlane match adhoc --force, which recreates profiles taking new devices into account. Apple Developer certificates are valid for one year, after which builds using them are rejected by App Store Connect. Match warns about expiration 30 days before the end of the validity period.

When the error «Multiple matches found for...» occurs, multiple versions of the same certificate exist in the repository. Use the fastlane match nuke command to completely clean the repository and remove all certificates from Apple Developer Portal. After cleanup, perform a fresh generation — this ensures a consistent profile state without duplicates or conflicting versions.