Codemagic

Die Build Station baut lokal. Manche Builds laufen aber in Codemagic: automatisch bei einem Push auf einen Release-Branch, oder weil für Windows-Builds eine Windows-Maschine nötig ist. Der Projekt-Tab Codemagic holt diese Builds ins selbe Fenster. Du siehst Status und Logs, startest neue Builds, lädst Artefakte herunter und lässt die codemagic.yaml prüfen.

API-Token hinterlegen

1. In Codemagic unter Account settings › API token das Token kopieren.
2. In der Station unter Einstellungen › Codemagic ins Feld Neues API-Token einfügen und Im Schlüsselbund speichern klicken.
3. Verbindung testen zeigt, wie viele Apps mit dem Token sichtbar sind.

Das Token liegt im macOS-Schlüsselbund, nicht in der config.json. Ist die Umgebungsvariable CM_API_TOKEN gesetzt, hat sie Vorrang. Die Station zeigt das an.

Das Token hat die Rechte deines Codemagic-Kontos, kann also auch Builds starten und abbrechen. Zum Wechseln widerrufst du es in Codemagic, erzeugst ein neues und ersetzt es hier. Entfernen löscht es vom Mac.

Ein Projekt verknüpfen

Im Tab Codemagic eines noch nicht verknüpften Projekts gibt es zwei Wege.

Vorhandene App verknüpfen

Vorhandene App verknüpfen … im Tab oder Verknüpfen … im Projekt-Editor unter Codemagic öffnet den Dialog Mit Codemagic verknüpfen. Die Station lädt die Apps des Kontos und markiert die, die über die Remote-URL des Repositorys passt zum Repo, sonst über den Namen. Ohne Token trägst du die App-ID von Hand ein. Sie steht in der Adresse codemagic.io/app/<App-ID>/settings.

Die codemagic.yaml sucht die Station im Projektordner und von dort aufwärts bis zur Repository-Wurzel. Liegt die App in einem Unterordner eines Monorepos, wird die Datei an der Wurzel also gefunden. Liegt sie woanders, trägst du den Pfad in der Verknüpfung ein.

Bei Codemagic einrichten

Bei Codemagic einrichten … legt die App in Codemagic an und sorgt dafür, dass jeder Push auf den gewählten Branch automatisch baut. Bei einem schon verknüpften Projekt heißt derselbe Dialog Auto-Builds …. Er erledigt in einem Durchgang:

1. App anlegen für die Remote-URL des Repositorys. Gibt es schon eine App für dasselbe Repository, schlägt der Dialog sie vor, statt eine zweite anzulegen. Optional mit Team-ID.
2. codemagic.yaml: Fehlt sie, legt der Dialog eine Vorlage an der Repository-Wurzel an, mit einem Workflow für die Plattformen des Projekts, ohne Signierung. Gibt es sie, bekommt der gewählte Workflow einen Auslöser für Pushes auf den Branch. Muster wie release/* sind erlaubt. Workflows, die schon Auslöser haben oder YAML-Anker nutzen, bleiben unangetastet.
3. codemagic.yaml committen und pushen: nur diese Datei, auf den aktuell ausgecheckten Branch. Abwählbar.
4. Webhook: Von einem Push erfährt Codemagic nur über einen Webhook. Ist Codemagic über die GitHub-App mit dem Repository verbunden, legt es ihn selbst an. Sonst legt die Station ihn über die GitHub-CLI an (brew install gh und gh auth login, Admin-Rechte am Repository nötig). Ohne gh oder bei GitLab und Bitbucket steht die Webhook-Adresse am Ende zum Kopieren da.

Private Repositorys ohne Git-Integration in Codemagic brauchen einen SSH-Schlüssel, am besten einen Deploy-Key mit Lesezugriff. Er geht einmalig an Codemagic und wird nirgends gespeichert.

Die Verknüpfung wird gespeichert, sobald die App feststeht, auch wenn ein späterer Schritt scheitert. Dann öffnest du den Dialog einfach noch einmal.

Die Vorlage baut ohne Signierung. Für signierte Builds und Veröffentlichung hinterlegst du die Zugangsdaten in Codemagic selbst.

Der Tab „Codemagic”

• Builds in Codemagic: neueste zuerst, mit Status, Workflow, Branch, Commit und Dauer. Läuft ein Build, fragt der Tab alle 15 Sekunden nach. Ein Filter zeigt nur Builds des aktuellen Branches.
• Detail eines Builds: Schritte, Artefakte, die Meldung von Codemagic und bei einem Fehlschlag das Log der gescheiterten Schritte, die letzten 300 Zeilen pro Schritt, zum Kopieren.
• Build starten …: Workflow aus der codemagic.yaml, Branch oder Tag, optional Variablen nur für diesen Build. Der Dialog zeigt, wann der Workflow ohnehin von selbst läuft. In Codemagic starten schickt den Auftrag ab.
• Codemagic öffnet die App in der Codemagic-Weboberfläche.
• Ein laufender Build lässt sich abbrechen.

Was vor dem Start geprüft wird

Prüfung	Warum
Workflow steht in der codemagic.yaml	sonst lehnt Codemagic ab
Branch ist auf origin	Codemagic baut nur Gepushtes
keine ungepushten Commits	sonst baut Codemagic einen älteren Stand
codemagic.yaml ohne lokale Änderungen	Codemagic liest die Datei aus dem Repository

Verglichen wird mit dem Stand des letzten git fetch. Die Station holt nicht selbst, das würde ohne Netz hängen. Im Tab Build aktualisierst du den Stand mit Remote prüfen (git fetch).

Artefakte herunterladen

Herunterladen neben einem Artefakt lädt es mit deinem Token in den Sammelordner der lokalen Builds:

<Sammelordner>/<Projekt-ID>/codemagic/<Nummer>_<Build-ID>/<Datei>

Danach öffnet Im Finder den Ordner. Das Aufräumen erfasst diese Ordner wie die lokalen Builds.

In den Store lädt die Datei herunter und reiht den Upload in den eingerichteten Store ein. Das geht für IPA, AAB, APK und MSIX. Für Windows-Apps ist das der übliche Weg, siehe Microsoft Store.

codemagic.yaml prüfen und reparieren

Im Tab steht eine Zeile zur gefundenen Datei. Prüfen & reparieren … zeigt alle Befunde. Gibt es keine, heißt der Knopf Ansehen. Geprüft wird:

• Syntax mit Zeilennummer, auch doppelte Schlüssel
• Struktur: workflows vorhanden, unbekannte Schlüssel (Tippfehler), max_build_duration zwischen 1 und 120, Scripts mit Befehl, artifacts als Liste, Auslöser und branch_patterns
• cd ins Leere: Das erste cd eines Scripts muss auf einen Ordner im Repository zeigen.
• Flutter-Version: Weicht environment.flutter von .fvmrc bzw. der Projekt-Einstellung ab, ist das die häufigste Ursache für „lokal geht es”.
• Veraltetes, das bei einem Update der Build-Maschinen zuerst bricht: flutter packages pub get, flutter pub run und eingebaute FCI_*-Variablen, die heute CM_* heißen. Selbst definierte Variablen bleiben, wie sie sind.
• Verschlüsselte Werte (Encrypted(…)): nur ein Hinweis, dass sie nur für die App gelten, in der sie verschlüsselt wurden.

Korrekturen erscheinen als Vorher und Nachher und werden nur auf Klick geschrieben, Zeile für Zeile. Kommentare und Reihenfolge bleiben erhalten. Hat sich eine Zeile seit der Prüfung geändert, bricht die Korrektur ab, statt das Falsche zu überschreiben.

Danach musst du die Datei committen und pushen, denn Codemagic liest sie aus dem Repository. Das geht direkt im Tab Build mit Commit & Push.

Die Prüfung ersetzt nicht die von Codemagic, die das vollständige Schema kennt. Sie fängt ab, was sich ohne Codemagic sicher sagen lässt, und zwar vor dem Push statt nach einem gescheiterten Build.

Grenzen

• Workflows, die nur in der Codemagic-Weboberfläche (Workflow Editor) definiert sind, zeigt der Tab an. Starten kann die Station sie nicht, weil sie ihre Workflows aus der codemagic.yaml liest.
• Gefiltert nach Branch oder Workflow reicht die Build-Liste höchstens 120 Builds zurück.

Codemagic für KI-Assistenten

Dieselben Funktionen bietet der MCP-Server einem KI-Assistenten an, etwa Claude Code. Der kann dann einen gescheiterten Codemagic-Build selbst untersuchen und reparieren. Siehe MCP-Server für KI-Assistenten.