<pa.dev/>
← Back to Tutorials
ToolsIntermediate

CI/CD for iOS Projects

A complete guide to setting up Continuous Integration and Continuous Delivery for iOS projects using Xcode and GitHub Actions — from running unit tests automatically to building and distributing a development IPA.

Alexandropoulos Panagiotis

Mobile Developer

1. Create a New Xcode Project

Start by creating a new iOS project in Xcode. This tutorial uses a project named iOS_CI_CD. Once the project is set up, initialise a Git repository and push it to GitHub on the main branch.

2. GitHub Actions for Unit Tests

Create a hidden folder .github/workflows at the project root. Inside it, add a *.yml file describing the workflow. This tutorial uses iosCICDActions.yml.

yaml
name: "Test - Build - Debug Publish iOS app"
on:
  push:
    branches: [main]
jobs:
  build_with_signing:
    runs-on: macos-latest
    steps:
      - name: check Xcode version
        run: /usr/bin/xcodebuild -version
      - name: checkout repository
        uses: actions/checkout@v3
      - name: Run tests
        run: xcodebuild test -scheme iOS_CI_CD -project iOS_CI_CD.xcodeproj -destination 'platform=iOS Simulator,name=iPhone 15,OS=18.1' -allowProvisioningUpdates CODE_SIGNING_ALLOWED=NO | xcpretty && exit ${PIPESTATUS[0]}

The on block defines when the workflow runs — here, every push to main.

The jobs block defines the three steps:

  1. 1Check Xcode version — prints the Xcode version via /usr/bin/xcodebuild -version. Make sure the runner's version is compatible with your project.
  2. 2Checkout repository — checks out the repo to $GITHUB_WORKSPACE so subsequent steps can access it.
  3. 3Run tests — executes all unit tests. If they pass execution continues; otherwise the workflow stops.
⚠
The -destination argument is whitespace-sensitive. 'platform=iOS Simulator,name=iPhone 15,OS=18.1' and 'platform=iOS Simulator,name=iPhone 15,OS=18.1 ' (trailing space) produce different results — the latter will fail. Also avoid spaces after commas. If the specified simulator OS version is unavailable the runner will fail but will log all available simulators so you can pick the right one.

3. Export Development Certificate

A paid Apple Developer Account is required for this and all following steps.

  1. 1
    Go to Xcode → Settings → General, select your certificate, then click Manage Certificates.
  2. 2
    Right-click the certificate and export it. Save it to a folder named Local Files that is listed in .gitignore — this file contains sensitive information that must never be committed.
  3. 3
    Choose a strong password when exporting. You will need it in the next step.
  4. 4
    In Terminal, encrypt and copy the certificate to your clipboard:
    bash
    base64 -i iOS_DevCertificate.p12 | pbcopy
  5. 5
    In your GitHub repository go to Settings → Secrets and variables → Actions and add a new secret named BUILD_CERTIFICATE_BASE64. Paste the clipboard value. Once saved the value is hidden for security.
  6. 6
    Add a second secret named P12_PASSWORD with the password you used to export the certificate.

4. Export Provisioning Profile

  1. 1
    On the Apple Developer page go to Identifiers and create a new ID.
  2. 2
    Select type App.
  3. 3
    Register an App ID.
  4. 4
    Add a description, set a unique bundle identifier using the format com.domain.appName, then select the Capabilities and App Services your app needs. Click Continue to save.
  5. 5
    From the main page select Profiles to begin creating the Provisioning Profile used by the runner to build a debug app.
  6. 6
    On the Profiles page click + to create a new profile.
  7. 7
    Select iOS App Development.
  8. 8
    Select the Identifier created in step 4 from the dropdown.
  9. 9
    Select the certificates to associate with this Provisioning Profile.
  10. 10
    Select which devices are eligible for running the debug app.
  11. 11
    Give the profile a name and click Generate.
  12. 12
    Download the profile and place it in the Local Files folder alongside the certificate.
  13. 13
    In Terminal, encrypt and copy the Provisioning Profile:
    bash
    base64 -i iOS_CICD_Provisioning_Profile.mobileprovision | pbcopy
  14. 14
    Add a new secret named BUILD_PROVISION_PROFILE_BASE64 in GitHub repository secrets and paste the result.
  15. 15
    In Xcode, under the project signing settings, select Manual Signing. Use the bundle identifier from step 4 and import the Provisioning Profile downloaded in step 12.
✓ These are all the secrets needed to build a development app.

5. GitHub Actions — Build Development IPA

Add the following steps to your workflow YAML to build and export the IPA.

5.1 — Install Certificate & Provisioning Profile

yaml
- name: Install the Apple certificate and provisioning profile
  env:
    BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
    P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
    BUILD_PROVISION_PROFILE_BASE64: ${{ secrets.BUILD_PROVISION_PROFILE_BASE64 }}
    KEYCHAIN_PASSWORD: ${{ secrets.KEYCHAIN_PASSWORD }}
  run: |
    # create variables
    CERTIFICATE_PATH=$RUNNER_TEMP/build_certificate.p12
    PP_PATH=$RUNNER_TEMP/build_pp.mobileprovision
    KEYCHAIN_PATH=$RUNNER_TEMP/app-signing.keychain-db

    # import certificate and provisioning profile from secrets
    echo -n "$BUILD_CERTIFICATE_BASE64" | base64 --decode -o $CERTIFICATE_PATH
    echo -n "$BUILD_PROVISION_PROFILE_BASE64" | base64 --decode -o $PP_PATH

    # create temporary keychain
    security create-keychain -p "$KEYCHAIN_PASSWORD" $KEYCHAIN_PATH
    security set-keychain-settings -lut 21600 $KEYCHAIN_PATH
    security unlock-keychain -p "$KEYCHAIN_PASSWORD" $KEYCHAIN_PATH

    # import certificate to keychain
    security import $CERTIFICATE_PATH -P "$P12_PASSWORD" -A -t cert -f pkcs12 -k $KEYCHAIN_PATH
    security list-keychain -d user -s $KEYCHAIN_PATH

    # apply provisioning profile
    mkdir -p ~/Library/MobileDevice/Provisioning\ Profiles
    cp $PP_PATH ~/Library/MobileDevice/Provisioning\ Profiles

The env block maps stored secrets to environment variables. The run block creates a temporary keychain, decodes and imports both the certificate and the provisioning profile, making them available for the build steps that follow.

5.2 — Build Archive

yaml
- name: Build archive
  env:
    scheme: "iOS_CI_CD"
  run: |
    xcodebuild \
      -configuration Debug \
      -scheme "${{ env.scheme }}" \
      -archivePath $RUNNER_TEMP/iOS_CI_CD.xcarchive \
      -destination 'platform=iOS Simulator,name=iPhone 15' \
      archive

The scheme env variable must match the scheme name in your Xcode project — typically the same as the project name. Find it in Xcode under Product → Scheme.

5.3 — Build IPA

The project must include an exportOptions.plist file anywhere in the repository. This file describes the signing style and Provisioning Profile to use when exporting the archive.

xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>method</key>
  <string>debugging</string>
  <key>signingStyle</key>
  <string>manual</string>
  <key>stripSwiftSymbols</key>
  <false/>
  <key>provisioningProfiles</key>
  <dict>
    <key>com.domain.iOS-CI-CD</key>
    <string>YOUR_PROFILE_UUID</string>
  </dict>
  <key>teamID</key>
  <string>YOUR_TEAM_ID</string>
  <key>thinning</key>
  <string>&lt;none&gt;</string>
</dict>
</plist>

Replace YOUR_PROFILE_UUID with the UUID from your provisioning profile and YOUR_TEAM_ID with your Apple Developer team ID (visible on the Apple Developer website). To retrieve the UUID:

bash
security cms -D -i <path-to-profile>.mobileprovision | grep -A1 UUID
yaml
- name: Build IPA
  run: |
    plutil -p exportOptions.plist
    xcodebuild \
      -configuration Release \
      -exportArchive \
      -archivePath $RUNNER_TEMP/iOS_CI_CD.xcarchive \
      -exportPath $GITHUB_WORKSPACE/iOS_CI_CD.ipa \
      -exportOptionsPlist exportOptions.plist

5.4 — Upload IPA Artifact

yaml
- name: Upload IPA artifact (absolute path)
  uses: actions/upload-artifact@v3
  with:
    name: iOS_CI_CD.ipa
    path: /Users/runner/work/iOS_CI_CD/iOS_CI_CD/iOS_CI_CD.ipa

This uploads the built IPA to the GitHub Actions run artifacts, making it available for download from the Actions tab in your GitHub repository.

6. Commit and Push

The configuration is complete. Commit and push to the main branch. GitHub Actions will trigger automatically and run the full workflow — running tests, building the archive, exporting the IPA, and uploading it as a downloadable artifact.

⚠
At the time of writing, GitHub Actions runners use Xcode 15.4 while Apple has already released Xcode 16. This mismatch can cause the runner to fail because the project structure is not recognised. A quick fix is to create the Xcode project with an older Xcode version. If that older version does not run on your current macOS, refer to this Stack Overflow workaround.

Written by Alexandropoulos Panagiotis

© 2026 Alexandropoulos Panagiotis. All rights reserved. You're welcome to link to this tutorial, but please don't copy or republish it without permission.

← Back to all tutorials