GitHub Actions Importer, CI Migration, Compatibility, and Modernization: Core Concepts and Mental Model

1. The migration problem is semantic, not syntactic

Moving a pipeline from Jenkins, GitLab CI, Azure DevOps, CircleCI or another system is not complete when a YAML file appears under .github/workflows. A pipeline is a behavioral contract: triggers select revisions, jobs form a graph, agents provide tools and network access, variables and secrets carry authority, caches and artifacts preserve different kinds of state, and deployment gates decide whether external systems may change.

GitHub Actions Importer can accelerate translation, inventory and forecasting, but current GitHub guidance explicitly requires converted workflows to be reviewed before production use. GitHub describes an approximate 80% conversion target, not semantic equivalence. The remaining work is the engineering work that matters most: proving that the migrated pipeline preserves intended invariants and intentionally modernizes unsafe or obsolete ones.

2. Mental model: inventory → conversion → semantic review → dual-run proof → cutover

Begin with the source CI as evidence. Record platform/version, pipeline source, trigger behavior, job graph, variables and secret names, agent capabilities, cache/artifact rules and deployment controls. Importer then produces audit/forecast output or generated workflow YAML. Treat that output as a candidate implementation, not as the truth.

flowchart TD
  A[Source CI inventory + execution history] --> B[Importer audit / forecast / dry-run]
  B --> C[Generated Actions workflow + TODOs]
  C --> D[Manual semantic review]
  D --> E[Runner / secret / artifact / gate mapping]
  E --> F[Parallel validation on same source revision]
  F --> G{Parity and approved deltas?}
  G -- No --> D
  G -- Yes --> H[Guarded cutover]
  H --> I[Legacy deployment disabled]
  I --> J[Retirement evidence + rollback window]

Each arrow is causal: conversion changes configuration text; semantic review changes confidence; dual-run validation creates evidence; cutover changes which system may publish or deploy; and retirement removes the old deployment authority.

3. State ledger for a reproducible migration

4. Read-only inspection before changing anything

Before running a converter, export or copy source configuration and sample run metadata. Do not begin by editing secrets or disabling jobs. A safe first pass asks which triggers actually fire, which stages are required, which agent capabilities are accidental, which outputs are consumed downstream, and which steps mutate external systems.

git rev-parse HEAD
git status --short
find . -maxdepth 3 -type f | sort
sha256sum source-ci.yml > evidence/source-ci.sha256

5. What Actions Importer currently does—and does not prove

Current GitHub Actions Importer is distributed through the gh actions-importer CLI extension and a containerized backend. Its primary planning and conversion commands are audit, forecast, dry-run, and migrate. Automated migration documentation covers Azure DevOps, Bamboo, Bitbucket Pipelines, CircleCI, GitLab, Jenkins and Travis CI.

A successful dry-run proves only that a candidate workflow was produced. It does not prove equivalent trigger semantics, runner capabilities, secret availability, cache behavior, artifact identity or deployment authorization. Unsupported constructs and TODOs are evidence that human review is required, not text to delete.

6. Secrets and runner mappings are trust-boundary migrations

Never copy a secret value into generated YAML. Map source secret names to GitHub secrets, environments, OIDC or another authorized credential mechanism, then verify scope and timing. Likewise, do not map a proprietary build agent directly to self-hosted because its scripts happened to work there. Enumerate the exact tools, filesystem assumptions, network routes and credentials the old agent supplied.

7. Cache and artifact names are not semantics

A source CI “cache” may be immutable enough to have been misused as a build handoff, while a GitHub Actions cache is a best-effort performance optimization. A source “artifact” may be a deployment bundle, test report or temporary output. During migration, classify each item by purpose, producer, consumer, retention and integrity requirement before selecting GitHub cache, job output or artifact mechanisms.

8. Cutover is a deployment-governance event

Dual-running CI is useful; dual-running deployers is dangerous. During validation, keep both systems read-only with respect to production or select exactly one authorized publisher/deployer. At cutover, document the authority transition: disable legacy deployment credentials or triggers before or atomically with enabling the Actions deployment path, then verify the old system can no longer mutate the target.

A rollback plan should restore a known, previously validated control path rather than simply turn both deployers back on.

9. Current assumptions recorded for this chapter

• GitHub documentation checked on 2026-09-10.
• Importer commands used conceptually: audit, forecast, dry-run and migrate.
• Current automated migration docs cover Azure DevOps, Bamboo, Bitbucket Pipelines, CircleCI, GitLab, Jenkins and Travis CI.
• Importer output requires manual correctness review; generated YAML is not proof of behavioral parity.
• Mandatory labs require only local files, Python and Git; live source-CI credentials and GitHub write access are optional.

10. Lesson summary

A safe CI migration preserves observable behavior and trust boundaries across a fixed source revision. Importer accelerates inventory and translation, but parity is established only when source and target executions are compared and every intentional delta is documented. Lesson 2 builds that evidence with a disposable fixture.

Knowledge check

Official references and version notes

• Automating migration with GitHub Actions Importer — Current Importer commands, prerequisites, supported platforms and review warning.
• GitHub Actions Importer reference — Supplemental settings and migration-reference material.
• Custom transformers — Current custom transformer model for unsupported tasks, runners and variables.
• Migrating to GitHub Actions — Automated and manual migration guidance.
• Secure use reference — Trust-boundary and least-privilege guidance applicable during cutover.