In diesem Artikel
Eine iOS-App lokal auf einem entsprechend eingerichteten Mac zu bauen, ist die eine Sache. Einen reproduzierbaren Release-Build unabhängig von diesem einzelnen Rechner zu erstellen, ist die andere.
Gerade beim iOS Signing kommen einige Bestandteile zusammen: ein Zertifikat mit privatem Schlüssel, eine passende Bundle ID, ein Provisioning Profile und der Zugriff auf Apples Schnittstellen.
Sobald diese Voraussetzungen vorbereitet sind, können wir den eigentlichen Build mit GitHub Actions automatisieren.
In diesem Beitrag zeige ich Schritt für Schritt, wie wir eine .NET MAUI iOS App innerhalb einer GitHub Action bauen und signieren. Am Ende erhalten wir eine .ipa-Datei, die wir direkt über den Workflow-Run herunterladen können.
Unser Ziel ist also:
- die benötigten iOS Secrets in GitHub hinterlegen
- Zertifikat und Provisioning Profile während des Builds bereitstellen
- eine .NET MAUI iOS App bauen und signieren
- die erzeugte
.ipa-Datei als Artifact des Workflows bereitstellen
Für das Beispiel verwende ich .NET 10, .NET MAUI und einen macOS-basierten GitHub Actions Runner.
Falls ihr die Apple-Ressourcen noch nicht erstellt habt, schaut euch zunächst meinen Beitrag Vor der IPA: iOS Signing für .NET MAUI vorbereiten an. Dort geht es unter anderem um App ID, Distribution Certificate, Provisioning Profile und App Store Connect API Key.
Für Android haben wir einen ähnlichen Workflow bereits im Beitrag Von Commit zu AAB/APK umgesetzt.
Warum sollten wir iOS Builds mit GitHub Actions automatisieren?
Ein automatisierter Build bietet uns auch bei iOS einige Vorteile.
Wir können die verwendete .NET SDK-Version und die Xcode-Version vorgeben, das Signing wiederholbar ausführen und das Provisioning Profile während des Workflow-Runs von Apple herunterladen.
Außerdem wird die fertige .ipa direkt zusammen mit dem Workflow-Run gespeichert. Dadurch können wir nachvollziehen, welcher Build zu welchem Durchlauf gehört.
Vor allem reduzieren wir aber die Abhängigkeit von einem einzelnen Mac und seiner lokalen Konfiguration. Wichtig ist dafür, dass die Versionen und Signing-Ressourcen auch langfristig gepflegt werden.
Voraussetzungen
Bevor wir mit unserer GitHub Action beginnen, benötigen wir:
- eine .NET MAUI App mit
net10.0-ios - ein GitHub Repository mit unserer Anwendung
- eine
global.jsonfür die Auswahl der .NET SDK-Version - ein Apple Distribution Certificate mit privatem Schlüssel als
.p12-Datei - eine passende App ID beziehungsweise Bundle ID
- ein gültiges App Store Provisioning Profile bei Apple
- einen App Store Connect API Key mit den benötigten Berechtigungen
Das Provisioning Profile muss bereits bei Apple vorhanden sein und zur Bundle ID sowie zu unserem Zertifikat passen. Der Workflow lädt es später herunter, erstellt es aber nicht für uns.
In meinem Beispiel-Repository befindet sich das .NET MAUI Projekt unter folgendem Pfad:
src/MyAwesomeMauiApp/MyAwesomeMauiApp.csproj
Schritt 1: .NET SDK und iOS Target Framework prüfen
Zunächst sollte unser .NET MAUI Projekt iOS mit .NET 10 als Target Framework verwenden. In der .csproj-Datei muss dafür net10.0-ios enthalten sein.
Außerdem legen wir im Root-Verzeichnis unseres Repositories eine global.json an:
{
"sdk": {
"version": "10.0.200",
"rollForward": "latestFeature"
}
}
Die Datei legt fest, welche SDK-Version mindestens verwendet werden soll und wie die Auswahl auf neuere Feature-Bands weitergerollt werden darf. Mit latestFeature kann daher auch ein neueres passendes SDK gewählt werden.
GitHub Actions verwendet die Datei später über actions/setup-dotnet. Zusätzlich wählen wir im Workflow eine Xcode-Version aus, die zur verwendeten .NET MAUI Workload passen muss.
Die hier gezeigten Versionen entsprechen dem Beispiel-Repository. Prüft bei einer Übernahme, ob die ausgewählte Xcode-Version auf dem GitHub Runner noch verfügbar und mit eurer SDK- und Workload-Version kompatibel ist.
Schritt 2: .p12-Datei nach Base64 konvertieren
GitHub Secrets speichern Text und keine Binärdateien.
Daher konvertieren wir unsere exportierte .p12-Datei zunächst in einen Base64-String. Auf einem Mac können wir dafür beispielsweise folgenden Befehl verwenden:
base64 -i ios_distribution.p12 | tr -d '\n' > ios.p12.base64.txt
Die erzeugte Textdatei enthält anschließend den Wert für unser GitHub Secret.
Unser App Store Connect API Key liegt dagegen bereits als Text in einer .p8-Datei vor. Hier benötigen wir keine Base64-Konvertierung. Wir hinterlegen später den vollständigen Inhalt der Datei.
Wichtig: Base64 ist keine Verschlüsselung. Sowohl die .p12-Datei als auch ihr Base64-Inhalt und der .p8-Key müssen geschützt werden. Diese Dateien gehören nicht in das Repository oder in Build-Logs. Die temporäre Base64-Textdatei solltet ihr nach dem sicheren Übertragen wieder entfernen.
Schritt 3: GitHub Secrets anlegen
Nun öffnen wir unser GitHub Repository und wechseln unter Settings → Secrets and variables → Actions zu den Repository-Secrets.
Für unseren iOS Build benötigen wir sechs Secrets:
IOS_P12_BASE64: der vollständige Base64-Inhalt unserer exportierten.p12-DateiIOS_P12_PASSWORD: das Passwort, das wir beim Export der.p12-Datei vergeben habenIOS_BUNDLE_ID: die Bundle ID unserer Anwendung, beispielsweisecom.companyname.myawesomemauiappAPP_STORE_CONNECT_ISSUER_ID: die Issuer ID aus App Store ConnectAPP_STORE_CONNECT_KEY_ID: die Key ID unseres App Store Connect API KeysAPP_STORE_CONNECT_PRIVATE_KEY: der vollständige Textinhalt der heruntergeladenen.p8-Datei
Die ersten beiden Secrets benötigen wir, um das Zertifikat inklusive privatem Schlüssel auf dem Runner zu importieren.
Die Bundle ID muss zu unserer App ID und zum Provisioning Profile bei Apple passen. Die drei App-Store-Connect-Werte verwendet der Workflow anschließend, um sich bei Apple zu authentifizieren und das Profil herunterzuladen.
Der API Key signiert unsere Anwendung nicht selbst. Das Signing erfolgt mit dem importierten Apple Distribution Certificate und dem zugehörigen privaten Schlüssel.
Schritt 4: GitHub Action erstellen
Jetzt können wir unsere eigentliche GitHub Action erstellen.
Dafür legen wir folgende Datei an:
.github/workflows/ios-build.yml
Der folgende Workflow basiert auf meinem Beispiel-Repository. Zusätzlich geben wir die IPA-Erzeugung ausdrücklich an und lassen den Upload fehlschlagen, wenn keine Datei gefunden wurde:
name: Build .NET MAUI iOS App (.ipa)
on:
workflow_dispatch:
jobs:
build-ios:
runs-on: macos-26
env:
PROJECT_PATH: src/MyAwesomeMauiApp/MyAwesomeMauiApp.csproj
steps:
- name: Checkout repository
uses: actions/checkout@v6
- name: Setup .NET from global.json
uses: actions/setup-dotnet@v5
with:
global-json-file: global.json
- name: Select Xcode 26.2
run: |
sudo xcode-select -s /Applications/Xcode_26.2.app/Contents/Developer
xcode-select -p
- name: Install MAUI Workload
run: dotnet workload install maui
- name: Import P12 File
uses: apple-actions/import-codesign-certs@v6
with:
p12-file-base64: ${{ secrets.IOS_P12_BASE64 }}
p12-password: ${{ secrets.IOS_P12_PASSWORD }}
keychain: build
create-keychain: true
keychain-password: buildpass
- name: Activate build.keychain
run: |
security list-keychains -s ~/Library/Keychains/build.keychain-db
security default-keychain -s ~/Library/Keychains/build.keychain-db
security unlock-keychain -p buildpass ~/Library/Keychains/build.keychain-db
- name: Extract signing identity
run: |
identities="$(security find-identity -v -p codesigning)"
identity="$(printf '%s\n' "$identities" | awk -F\" '/Apple Distribution/ {print $2; exit}')"
if [ -z "$identity" ]; then
echo "::error::No valid Apple Distribution signing identity found."
exit 1
fi
echo "CODE_SIGN_IDENTITY=$identity" >> "$GITHUB_ENV"
- name: Download Provisioning Profiles
uses: apple-actions/download-provisioning-profiles@v5
with:
bundle-id: ${{ secrets.IOS_BUNDLE_ID }}
profile-type: IOS_APP_STORE
issuer-id: ${{ secrets.APP_STORE_CONNECT_ISSUER_ID }}
api-key-id: ${{ secrets.APP_STORE_CONNECT_KEY_ID }}
api-private-key: ${{ secrets.APP_STORE_CONNECT_PRIVATE_KEY }}
- name: Set version variables
run: |
buildNumber="${{ github.run_number }}"
echo "VERSION_DISPLAY=1.0.$buildNumber" >> "$GITHUB_ENV"
echo "VERSION_CODE=$((10000 + buildNumber))" >> "$GITHUB_ENV"
- name: Restore packages
run: dotnet restore "$PROJECT_PATH"
- name: Publish iOS app
run: |
dotnet publish "$PROJECT_PATH" -f net10.0-ios -c Release \
-p:RuntimeIdentifier=ios-arm64 \
-p:ArchiveOnBuild=true \
-p:ApplicationVersion="$VERSION_CODE" \
-p:ApplicationDisplayVersion="$VERSION_DISPLAY" \
-p:ApplicationId="${{ secrets.IOS_BUNDLE_ID }}" \
-p:CodesignKey="$CODE_SIGN_IDENTITY"
- name: Copy .ipa to output
run: |
projectDir="$(dirname "$PROJECT_PATH")"
publishDir="$projectDir/bin/Release/net10.0-ios/ios-arm64/publish"
mkdir -p output
cp "$publishDir"/*.ipa output/
- name: Upload final IPA only
uses: actions/upload-artifact@v6
with:
name: ios-build
path: output/*.ipa
if-no-files-found: error
Den Wert von PROJECT_PATH müsst ihr an den Pfad eures eigenen Projekts anpassen.
Das Passwort buildpass gehört hier nur zu dem temporären Schlüsselbund auf dem GitHub-gehosteten Runner, nicht zu eurer .p12-Datei. Für eigene, dauerhaft betriebene Runner solltet ihr diesen Beispielwert nicht verwenden und den Schutz sowie die Bereinigung des Schlüsselbunds entsprechend eurer Umgebung konfigurieren.
Schritt 5: Was macht unser Workflow?
Schauen wir uns noch einmal kurz an, was innerhalb unserer GitHub Action passiert.
- Repository auschecken
- .NET SDK anhand der
global.jsoneinrichten - Xcode-Version auswählen
- .NET MAUI Workload installieren
- Zertifikat aus den Secrets importieren und den Schlüsselbund aktivieren
- Apple Distribution Signing Identity ermitteln
- passendes App Store Provisioning Profile von Apple herunterladen
- Versionsnummern aus der Workflow-Run-Nummer erzeugen
- Anwendung bauen, signieren und als
.ipaveröffentlichen - IPA-Datei als Artifact bereitstellen
Über RuntimeIdentifier=ios-arm64 bauen wir für iOS-Geräte. ArchiveOnBuild=true gibt ausdrücklich vor, dass ein Archiv beziehungsweise eine .ipa erzeugt werden soll.
Die Versionsnummern sind ein einfaches Beispiel. Für die spätere Veröffentlichung müsst ihr sicherstellen, dass eure Version und Build-Nummer zu euren bereits in App Store Connect vorhandenen Builds passen. Ein erneuter Versuch desselben Workflow-Runs verwendet beispielsweise dieselbe Run-Nummer.
Schritt 6: Workflow ausführen
Aktuell verwenden wir in unserem Workflow ausschließlich:
on:
workflow_dispatch:
Dadurch wird der Build nicht automatisch bei jedem Commit gestartet.
Nachdem wir die Workflow-Datei in unser Repository gepusht haben, können wir in GitHub in den Bereich Actions wechseln und den Workflow dort manuell starten.
Das eignet sich sehr gut, um die Pipeline zunächst zu testen.
Sobald alles funktioniert, können wir den Trigger natürlich erweitern und den Workflow beispielsweise bei einem Push, einem Tag oder bei der Erstellung eines Releases ausführen.
Nach einem erfolgreichen Run sollten wir ein Artifact mit dem Namen ios-build sehen. Dieses enthält unsere signierte .ipa-Datei.
Der Workflow lädt die Datei nicht automatisch zu App Store Connect oder TestFlight hoch. Außerdem ist das verwendete IOS_APP_STORE-Profil für die App-Store-Verteilung vorgesehen: Die erzeugte .ipa ist damit nicht wie eine Ad-hoc-Version direkt auf beliebigen Testgeräten installierbar.
Typische Probleme
Auch wenn unser Workflow insgesamt überschaubar ist, gibt es einige typische Fehlerquellen.
Falsche Bundle ID
IOS_BUNDLE_ID muss zur App ID und zum Provisioning Profile bei Apple passen. Der Workflow verwendet diesen Wert sowohl beim Herunterladen des Profils als auch beim Veröffentlichen der Anwendung.
Stimmen die Werte nicht überein, schlägt das Signing fehl.
Fehler beim Import der .p12-Datei
Ein unvollständiger Base64-Wert oder ein falsches Passwort verhindert den Import des Zertifikats.
Prüft außerdem, ob eure .p12-Datei neben dem Distribution Certificate auch den dazugehörigen privaten Schlüssel enthält.
Provisioning Profile kann nicht heruntergeladen werden
In diesem Fall solltet ihr zunächst Issuer ID, Key ID und den vollständigen Inhalt der .p8-Datei kontrollieren.
Der API Key benötigt außerdem passende Berechtigungen. Das App Store Provisioning Profile muss bereits existieren, gültig sein und zur Bundle ID und zum Zertifikat gehören.
Falls mehrere passende Profile oder Signing Identities vorhanden sind, prüft die Auswahl und gebt bei Bedarf das gewünschte Profil beziehungsweise die Signing Identity ausdrücklich in eurer Build-Konfiguration vor.
Xcode- und Workload-Version passen nicht zusammen
Ein aktualisiertes Runner-Image kann dazu führen, dass der angegebene Xcode-Pfad nicht mehr vorhanden ist. Ebenso kann eine Xcode-Version nicht zur installierten .NET MAUI Workload passen.
Prüft in diesem Fall die verfügbaren Versionen auf dem Runner und wählt eine zur verwendeten SDK- und Workload-Version passende Kombination.
Es wird keine .ipa gefunden
Kontrolliert den Projektpfad und die Ausgabe von dotnet publish. Für die IPA-Erzeugung setzen wir im Beispiel ArchiveOnBuild=true und suchen anschließend im publish-Verzeichnis für ios-arm64.
Wenn eure Projektkonfiguration ein anderes Ausgabeverzeichnis verwendet, müsst ihr den Kopierschritt entsprechend anpassen.
Fazit
Das automatisierte Bauen einer .NET MAUI iOS App muss nicht kompliziert sein, sobald die benötigten Apple-Ressourcen vorbereitet sind.
Wenn Zertifikat, Bundle ID, Provisioning Profile und App Store Connect API Key zusammenpassen, kann unsere GitHub Action diese Informationen während des Builds verwenden und eine signierte .ipa erzeugen.
Und genau das ist für mich der eigentliche Vorteil einer solchen Pipeline.
Es geht nicht nur darum, einen manuellen Schritt zu automatisieren. Wir schaffen vielmehr einen nachvollziehbaren und wiederholbaren Prozess für unsere iOS Release-Builds, ohne dafür jedes Mal denselben lokal eingerichteten Mac zu benötigen.
Ein vollständiges Beispiel mit einer einfachen .NET MAUI Anwendung und den entsprechenden GitHub Actions findet ihr in meinem Repository . Der hier verwendete Stand des iOS-Workflows ist dort ebenfalls verlinkt.