CircleCI zu GitHub Actions migrieren: Schritt für Schritt
Zuletzt aktualisiert am
Die Migration von CircleCI zu GitHub Actions ist größtenteils eine Übersetzungsaufgabe: Jobs bleiben Jobs, Workflows werden zu needs, Orbs werden zu Actions aus dem Marketplace und save_cache wird zu actions/cache. Eine kleine Pipeline lässt sich an einem Nachmittag umstellen. Die schwierigen Teile sind Secrets, Kontexte und alles, was auf CircleCI-spezifischen Funktionen wie resource_class oder dem Aufteilen von Tests beruht. Dieser Leitfaden behandelt die Zuordnung, eine konkrete Übersetzung, den automatisierten Importer und einen Umstellungsplan ohne Ausfallzeit.
Den Vergleich auf Produktebene finden Sie unter CircleCI vs GitHub Actions und CircleCI-Alternativen.
Zuordnung der Konzepte
| CircleCI | GitHub Actions |
|---|---|
.circleci/config.yml | .github/workflows/*.yml (eine Datei pro Workflow) |
workflows: mit requires | jobs.<id>.needs |
jobs: | jobs: |
docker: / machine:-Executor | runs-on: plus container:, wenn Sie ein Job-Image möchten |
Zusätzliche docker:-Images | services: |
resource_class | Runner-Label, zum Beispiel ein größerer Runner oder ein selbst gehostetes Label |
steps: - run | steps: - run |
checkout | actions/checkout |
save_cache / restore_cache | actions/cache oder cache: in setup-*-Actions |
persist_to_workspace / attach_workspace | actions/upload-artifact / actions/download-artifact |
store_artifacts | actions/upload-artifact |
store_test_results | Eine Action für Testberichte oder upload-artifact der JUnit-Dateien |
parallelism: N + Aufteilen der Tests | strategy.matrix; siehe Test-Sharding |
| Orbs | Actions aus dem Marketplace, Composite Actions, wiederverwendbare Workflows |
| Kontexte | Environments, Organisations-Secrets und -Variablen |
| Umgebungsvariablen des Projekts | Repository-Secrets und -Variablen |
filters: branches | on.push.branches / if:-Bedingungen |
Geplante Workflows (triggers: schedule) | on.schedule; siehe Cron-Zeitpläne |
when: / unless: | if:-Ausdrücke |
Eine realistische Pipeline im direkten Vergleich
CircleCI: eine Node-App mit Postgres, Build und Tests, danach Deployment von main:
# .circleci/config.yml
version: 2.1
orbs:
node: circleci/node@5
jobs:
test:
docker:
- image: cimg/node:22.11
- image: cimg/postgres:16.4
environment:
POSTGRES_PASSWORD: postgres
resource_class: large
parallelism: 4
steps:
- checkout
- restore_cache:
keys:
- npm-v1-{{ checksum "package-lock.json" }}
- npm-v1-
- run: npm ci
- save_cache:
key: npm-v1-{{ checksum "package-lock.json" }}
paths: [~/.npm]
- run:
command: |
TESTS=$(circleci tests glob "test/**/*.test.js" | circleci tests split --split-by=timings)
npm test -- $TESTS
environment:
DATABASE_URL: postgres://postgres:postgres@localhost:5432/postgres
- store_test_results:
path: reports
deploy:
docker:
- image: cimg/node:22.11
steps:
- checkout
- run: ./scripts/deploy.sh
workflows:
ci:
jobs:
- test
- deploy:
requires: [test]
context: production
filters:
branches:
only: main
Entsprechung in GitHub Actions:
# .github/workflows/ci.yml
name: CI
on:
push:
branches: [main]
pull_request:
jobs:
test:
runs-on: ubuntu-latest # or [self-hosted, Linux, compiler-ci]
strategy:
fail-fast: false
matrix:
shard: [1, 2, 3, 4]
services:
postgres:
image: postgres:16.4
env:
POSTGRES_PASSWORD: postgres
ports: ["5432:5432"]
options: >-
--health-cmd "pg_isready -U postgres"
--health-interval 5s --health-retries 10
env:
DATABASE_URL: postgres://postgres:postgres@localhost:5432/postgres
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v7
with:
node-version: 22
cache: npm
- run: npm ci
- run: npx jest --shard=${{ matrix.shard }}/4 --ci --reporters=default --reporters=jest-junit
- uses: actions/upload-artifact@v4
if: always()
with:
name: test-results-${{ matrix.shard }}
path: reports
deploy:
needs: test
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
runs-on: ubuntu-latest
environment: production
steps:
- uses: actions/checkout@v6
- run: ./scripts/deploy.sh
env:
DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
Was sich geändert hat und warum:
- Das primäre Docker-Image wird zum Runner selbst. Verwenden Sie
setup-nodeanstelle voncimg/nodeoder behalten Sie ein Image mitcontainer:bei. - Zusätzliche Images werden zu
services:. Der Service ist überlocalhostmit dem Port-Mapping erreichbar, wenn der Job direkt auf dem Runner läuft, und über den Servicenamen, wenn der Job selbstcontainer:nutzt. Fügen Sie einen Health-Check hinzu, damit die Tests nicht starten, bevor Postgres bereit ist. parallelism: 4pluscircleci tests splitwird zu einer Matrix. CircleCI teilt anhand aufgezeichneter Laufzeiten auf; das integrierte--shardvon Jest teilt nach Dateireihenfolge auf und berücksichtigt keine Laufzeiten. Wenn eine ausgewogene Laufzeitverteilung wichtig ist, lesen Sie Test-Sharding.- Der Kontext
productionwird zu einemenvironment: production, das zusätzlich Freigaben verlangen und Secrets auf sich beschränken kann.
Secrets und Umgebungsvariablen
Projektvariablen von CircleCI werden zu Repository-Secrets. Kontexte, die über mehrere Projekte geteilt werden, werden zu Organisations-Secrets (eingeschränkt auf Repositories) oder zu Environment-Secrets. Die Werte von Secrets lassen sich in der Oberfläche von CircleCI nicht auslesen. Exportieren Sie sie daher von dem Ort, an dem Sie sie ursprünglich gespeichert haben; planen Sie das frühzeitig ein. Nicht vertrauliche Werte gehören in Repository- oder Organisationsvariablen und werden als ${{ vars.NAME }} referenziert.
Für den Cloud-Zugriff sind kurzlebige Zugangsdaten gespeicherten Schlüsseln vorzuziehen; siehe GitHub Actions OIDC mit AWS und GitHub Actions absichern. Secrets werden an Workflows, die von Forks ausgelöst werden, standardmäßig nicht übergeben.
Caching und Artefakte
restore_cache mit einer Schlüsselliste lässt sich direkt auf key plus restore-keys abbilden. Die meisten Setups vereinfachen sich zu cache: bei setup-node, setup-python, setup-go und ähnlichen Actions. Siehe die Anleitungen je Ökosystem: npm, pip, Gradle, Go sowie den allgemeinen Caching-Leitfaden. Das Cache-Limit pro Repository beträgt 10 GB; siehe Cache-Limits.
Für persist_to_workspace laden Sie die Dateien in einem Job hoch und im nächsten Job herunter:
- uses: actions/upload-artifact@v4
with: { name: build, path: dist }
# in the next job
- uses: actions/download-artifact@v4
with: { name: build }
Artefakte werden pro Workflow-Lauf gespeichert, mit einer Aufbewahrungsdauer, die Sie festlegen können.
Automatisierte Konvertierung: GitHub Actions Importer
GitHub stellt den Importer als gh-Erweiterung bereit, die CircleCI, Jenkins, GitLab CI, Azure DevOps, Bamboo, Bitbucket Pipelines und Travis CI unterstützt (laut GitHub-Dokumentation, Stand Oktober 2026). Er benötigt Docker und die GitHub CLI.
gh extension install github/gh-actions-importer
gh actions-importer configure # sets up tokens for GitHub and CircleCI
gh actions-importer audit circle-ci --output-dir audit
gh actions-importer dry-run circle-ci --output-dir out ...
Die dokumentierten Befehle sind audit (Pipelines analysieren), forecast (Actions-Nutzung aus vergangenen Läufen schätzen), dry-run (konvertierte Workflows lokal schreiben) und migrate (einen Pull Request öffnen). Führen Sie zuerst audit aus: Es zeigt, welche Konstrukte sich konvertieren lassen und welche manuelle Arbeit erfordern, was eine realistische Projektplanung ermöglicht. Behandeln Sie die Ausgabe als ersten Entwurf. Orbs und eigene Befehle müssen oft von Hand umgeschrieben werden, und die konvertierte YAML ist ausführlich. Prüfen Sie die aktuelle Importer-Dokumentation auf die genauen Flags Ihrer Version.
Umstellungsplan
- Auditieren Sie mit dem Importer und erfassen Sie Orbs, Contexts und zeitgesteuerte Pipelines.
- Portieren Sie einen Workflow (meist den Haupt-Testjob) und führen Sie ihn auf einem Branch aus.
- Betreiben Sie beide parallel für ein bis zwei Wochen. Vergleichen Sie Laufzeit und Erfolgsquote und beheben Sie instabile Abweichungen.
- Verschieben Sie Secrets und Environments, danach die Deployment-Jobs. Testen Sie Deployments zuerst gegen eine Staging-Umgebung.
- Aktualisieren Sie den Branch-Schutz, sodass die GitHub-Checks statt der CircleCI-Checks erforderlich sind.
- Deaktivieren Sie CircleCI-Trigger, behalten Sie die Konfiguration in der Git-Historie und entfernen Sie sie nach einem Release-Zyklus.
Nach der Umstellung: Kosten und Geschwindigkeit
Die standardmäßigen GitHub-gehosteten Runner haben 2 vCPU. Wenn Ihre CircleCI-Jobs large- oder xlarge-Ressourcenklassen nutzten, werden die Standard-Runner von GitHub wahrscheinlich langsamer wirken. Vergleichen Sie die größeren Runner von GitHub mit Alternativen unter GitHub Actions Preise. compiler.dev führt denselben Workflow auf Maschinen mit 8 vCPU / 16 GB für $0.008 pro Minute aus, indem Sie runs-on auf [self-hosted, Linux, compiler-ci] ändern. Bei Fehlern fällt das System automatisch auf Ihre ursprünglichen Runner zurück; siehe Preise.
FAQ
Wie lange dauert eine Migration von CircleCI zu GitHub Actions?
Eine einzelne Pipeline mit gängigen Orbs: Stunden. Ein Dutzend Pipelines mit eigenen Orbs, Contexts und Deployment-Logik: Wochen, vor allem für Validierung und Secrets.
Was ersetzt CircleCI-Orbs?
Marketplace-Actions für gängige Tools, zusammengesetzte Actions für wiederverwendbare Schrittfolgen und wiederverwendbare Workflows für ganze Jobs.
Kann ich das Test-Splitting von CircleCI nach Laufzeiten beibehalten?
Nicht nativ. Jest und Playwright sharden nach Datei oder Testanzahl; für eine laufzeitbasierte Verteilung verwenden Sie ein Splitting-Skript oder ein dafür entwickeltes Tool.
Verliere ich das SSH-Debugging von CircleCI?
Es gibt kein eingebautes Pendant. Community-Actions öffnen eine temporäre SSH- oder tmate-Sitzung; prüfen Sie deren Sicherheit, bevor Sie sie einsetzen.
Kann ich beide eine Zeit lang betreiben?
Ja, und das sollten Sie auch. Betreiben Sie beide, bis die Ergebnisse übereinstimmen, und stellen Sie dann die erforderlichen Checks um.
Verwandt
- GitLab CI zu GitHub Actions migrieren: Schritt für SchrittGitLab CI zu GitHub Actions migrieren: mit .gitlab-ci.yml-Zuordnungstabelle, Gegenüberstellung, Variablen, Cache, Services, Importer und Umstellung.
- Von Jenkins zu GitHub Actions migrieren: Schritt für SchrittJenkins zu GitHub Actions migrieren: Jenkinsfile-Zuordnungstabelle, Übersetzung nebeneinander, Credentials, Caching, Agents, Importer und Umstellungsplan.
- CircleCI vs. GitHub Actions mit compiler.dev-RunnernCircleCI vs. GitHub Actions auf compiler.dev-Runnern: Preismodell, Konfigurationsunterschiede, Vorteile von CircleCI und Migrationsskizze mit echtem YAML.
- Die besten CircleCI-Alternativen 2026Die besten CircleCI-Alternativen: GitHub Actions, GitLab CI, Buildkite, Semaphore, Jenkins und compiler.dev im Vergleich nach Preismodell, Aufwand und Eignung.