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.
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:
- 1Check Xcode version — prints the Xcode version via
/usr/bin/xcodebuild -version. Make sure the runner's version is compatible with your project. - 2Checkout repository — checks out the repo to
$GITHUB_WORKSPACEso subsequent steps can access it. - 3Run tests — executes all unit tests. If they pass execution continues; otherwise the workflow stops.
-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.
- 1Go to Xcode → Settings → General, select your certificate, then click Manage Certificates.
- 2Right-click the certificate and export it. Save it to a folder named
Local Filesthat is listed in.gitignore— this file contains sensitive information that must never be committed. - 3Choose a strong password when exporting. You will need it in the next step.
- 4In Terminal, encrypt and copy the certificate to your clipboard:bash
base64 -i iOS_DevCertificate.p12 | pbcopy - 5In 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. - 6Add a second secret named
P12_PASSWORDwith the password you used to export the certificate.
4. Export Provisioning Profile
- 1On the Apple Developer page go to Identifiers and create a new ID.
- 2Select type App.
- 3Register an App ID.
- 4Add 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. - 5From the main page select Profiles to begin creating the Provisioning Profile used by the runner to build a debug app.
- 6On the Profiles page click + to create a new profile.
- 7Select iOS App Development.
- 8Select the Identifier created in step 4 from the dropdown.
- 9Select the certificates to associate with this Provisioning Profile.
- 10Select which devices are eligible for running the debug app.
- 11Give the profile a name and click Generate.
- 12Download the profile and place it in the
Local Filesfolder alongside the certificate. - 13In Terminal, encrypt and copy the Provisioning Profile:bash
base64 -i iOS_CICD_Provisioning_Profile.mobileprovision | pbcopy - 14Add a new secret named
BUILD_PROVISION_PROFILE_BASE64in GitHub repository secrets and paste the result. - 15In 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.
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
- 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\ ProfilesThe 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
- 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' \
archiveThe 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 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><none></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:
security cms -D -i <path-to-profile>.mobileprovision | grep -A1 UUID- 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.plist5.4 — Upload IPA Artifact
- 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.ipaThis 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.
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