GitHub Actions Importer, CI Migration, Compatibility, and Modernization: Diagnostics, Failure Modes, and Production Practices

1. Evidence-first migration diagnostics

When the target workflow fails or behaves differently, preserve both sides before editing. Record the source run, target run/attempt, exact revision, generated workflow revision, runner/tool versions, artifact metadata and any external target state. Then classify the failure: trigger/configuration, runner/tooling, credential, cache/artifact, deployment/provider or migration-transformer layer.

2. The diagnostic sequence

Use the same incident discipline established earlier in the course: preserve first failure → confirm source and target revision identity → compare trigger/event semantics → compare job graph and conditions → compare runner capabilities → compare token/secret availability → compare artifact/cache semantics → compare deployment gate and external target → make the smallest correction → rerun the smallest equivalent scope.

3. Failure: committing generated workflows without semantic review

# BROKEN migration shortcut — illustrative only
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - run: ./legacy-deploy.sh
# TODO from importer was deleted without mapping the old approval gate.

The syntax may run, but the old approval state disappeared. Repair by restoring the missing gate as an explicit requirement, pinning runner/tool assumptions, and comparing deployment authorization evidence before enabling writes.

4. Failure: copying secrets literally

Literal secrets in YAML, transformer files or migration reports are a credential incident. Stop publishing the generated material, preserve evidence according to incident policy without spreading the value, revoke or rotate the exposed credential, then remap the secret through GitHub Secrets, environments, OIDC or another least-privilege mechanism. Redaction in logs does not undo repository-history exposure.

5. Failure: ignoring agent-specific tools or network

A generated workflow can fail because the source agent had an undeclared package, mounted certificate, proxy, private DNS route or service account. Do not “fix” this by installing everything globally on a new self-hosted runner. Identify the exact dependency and decide whether it belongs in repository setup, a container, service container, restricted runner image, or external integration.

6. Failure: treating cache and artifact semantics as identical

A legacy pipeline may restore a cache produced by a previous branch and then deploy its contents. Recreating that with Actions cache preserves a correctness bug. Migration is an opportunity to separate immutable build evidence from best-effort acceleration: use artifacts for handoff/evidence and cache only recomputable dependency/build state.

7. Failure: cutover without dual-run evidence

A single green Actions run is weak evidence. Run source and target on a representative sample of identical revisions, including at least one controlled failure and one change that exercises trigger or condition logic. Compare required checks, artifact digests, test counts and deployment eligibility.

8. Failure: legacy CI can still deploy after cutover

This is a governance failure even if no collision has occurred. Disable or revoke the legacy deployment path, preserve the change record, and verify denial from the legacy side. A cutover is complete only when the old system is no longer an untracked writer to the target.

9. Intentionally broken parity example

SOURCE run 4812  sha=abc123  artifact=sha256:111...  deploy=blocked-for-approval
TARGET run 99201 sha=def456  artifact=sha256:222...  deploy=success
Engineer conclusion: "migration works"

The conclusion is invalid three times: revisions differ, artifacts differ, and deployment authorization differs. The least-destructive repair is to rerun both systems against the same immutable source revision with deployment writes disabled, compare artifact contents, then separately validate the target approval path. Preserve the original mismatched comparison as evidence of the diagnostic mistake.

10. Lesson summary

Most migration failures are not parser errors; they are semantic drift hidden behind green jobs. Preserve source/target evidence, classify the layer, repair the smallest boundary and keep the first mismatch. The checkpoint now applies the complete process to an intentionally unsupported feature.

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.