Tutorial: Build iOS apps with GitLab Mobile DevOps - Gitlabhq

In this tutorial, you'll create a pipeline by using GitLab CI/CD that builds your iOS mobile app, signs it with your credentials, and distributes it to app stores.

To set up mobile DevOps:

Set up your build environment
Configure code signing with fastlane
Set up app distribution with Apple Store integration and fastlane

Before you begin

Before you start this tutorial, make sure you have:

A GitLab account with access to CI/CD pipelines
Your mobile app code in a GitLab repository
An Apple Developer account
fastlane installed locally

Set up your build environment

Use GitLab-hosted runners, or set up self-managed runners for complete control over the build environment.

Create a .gitlab-ci.yml file in your repository root.

Add a supported macOS images to run a job on a macOS GitLab hosted runners (beta):

yaml

test:
  image: macos-14-xcode-15
  stage: test
  script:
    - fastlane test
  tags:
    - saas-macos-medium-m1

Configure code signing with fastlane

To set up code signing for iOS, upload signed certificates to GitLab by using fastlane:

Initialize fastlane:
shell
```
fastlane init
```
Generate a Matchfile with the configuration:
shell
```
fastlane match init
```
Generate certificates and profiles in the Apple Developer portal and upload those files to GitLab:
shell
```
PRIVATE_TOKEN=YOUR-TOKEN bundle exec fastlane match development
```
Optional. If you have already created signing certificates and provisioning profiles for your project, use fastlane match import to load your existing files into GitLab:
shell
```
PRIVATE_TOKEN=YOUR-TOKEN bundle exec fastlane match import
```

You are prompted to input the path to your files. After you provide those details, your files are uploaded and visible in your project's CI/CD settings. If prompted for the git_url during the import, it is safe to leave it blank and press <kbd>enter</kbd>.

The following are sample fastlane/Fastfile and .gitlab-ci.yml files with this configuration:

fastlane/Fastfile:

ruby

default_platform(:ios)

platform :ios do
  desc "Build and sign the application for development"
  lane :build do
    setup_ci

    match(type: 'development', readonly: is_ci)

    build_app(
      project: "ios demo.xcodeproj",
      scheme: "ios demo",
      configuration: "Debug",
      export_method: "development"
    )
  end
end

.gitlab-ci.yml:

yaml

build_ios:
  image: macos-12-xcode-14
  stage: build
  script:
    - fastlane build
  tags:
    - saas-macos-medium-m1

Set up app distribution with Apple Store integration and fastlane

Signed builds can be uploaded to the Apple App Store by using the Mobile DevOps Distribution integrations.

Prerequisites:

You must have an Apple ID enrolled in the Apple Developer Program.
You must generate a new private key for your project in the Apple App Store Connect portal.

To create an iOS distribution with the Apple Store integration and fastlane:

Generate an API Key for App Store Connect API. In the Apple App Store Connect portal, generate a new private key for your project.
Enable the Apple App Store Connect integration:
1. In the top bar, select Search or go to and find your project.
2. Select Settings > Integrations.
3. Select Apple App Store Connect.
4. Under Enable integration, select the Active checkbox.
5. Provide the Apple App Store Connect configuration information:
  - Issuer ID: The Apple App Store Connect issuer ID.
  - Key ID: The key ID of the generated private key.
  - Private key: The generated private key. You can download this key only once.
  - Protected branches and tags only: Enable to set variables on protected branches and tags only.
6. Select Save changes.
Add the release step to your pipeline and fastlane configuration.

The following is a sample fastlane/Fastfile:

ruby

default_platform(:ios)

platform :ios do
  desc "Build and sign the application for distribution, upload to TestFlight"
  lane :beta do
    setup_ci

    match(type: 'appstore', readonly: is_ci)

    app_store_connect_api_key

    increment_build_number(
      build_number: latest_testflight_build_number(initial_build_number: 1) + 1,
      xcodeproj: "ios demo.xcodeproj"
    )

    build_app(
      project: "ios demo.xcodeproj",
      scheme: "ios demo",
      configuration: "Release",
      export_method: "app-store"
    )

    upload_to_testflight
  end
end

The following is a sample .gitlab-ci.yml:

yaml

beta_ios:
  image: macos-12-xcode-14
  stage: beta
  script:
    - fastlane beta

Congratulations! Your app is now set up for automated building, signing, and distribution. Try creating a merge request to trigger your first pipeline.

Sample projects

Sample Mobile DevOps projects with pipelines configured to build, sign, and release mobile apps are available for:

Android
Flutter
iOS

View all projects in the Mobile DevOps Demo Projects group.