migration-core

Migration Core

5-Phase Workflow

All migrations follow these phases in order — skipping any phase is a completion failure.

Phase 1 — Source

• REQUIRE actual source CI/CD files from the user. Refuse to proceed without them.
• NEVER invent workflows from descriptions, requirements, or assumptions.
• Common filenames: Jenkinsfile, azure-pipelines.yml, .circleci/config.yml, .gitlab-ci.yml, .travis.yml, bitbucket-pipelines.yml, bamboo-specs.yml, .drone.yml (and any included/referenced files).

Phase 2 — Analyze

Examine the source thoroughly. Identify:

• Pipeline/job/stage structure and dependencies
• Triggers, conditions, branching strategy
• Agents/executors/containers → GitHub runner mapping
• Credential bindings, secrets, env vars
• Caching, artifacts, matrix builds, parallelism
• Platform-specific features with no direct Actions equivalent (see the platform skill's mapping.md)

Phase 3 — Convert

• Convert only what's in the source — no added functionality.
• Use the platform skill's mapping.md for syntax translations.
• Use only marketplace actions from verified creators (see Guardrails below).
• Translate triggers, conditional logic, env/secrets references, services, artifacts, caches.
• Expand all platform-specific includes/templates/shared-libraries inline.
• Add comments explaining non-obvious conversion choices.

Phase 4 — Validate

Load and follow the actionlint skill: install the tool if needed, run it against all generated workflows, resolve every finding, and capture the real output for the report.

Phase 5 — Document

1. Write .github/ci-archive/MIGRATION-README.md using the platform skill's report-template.md, filled with real data — no placeholders, real actionlint output.
2. MOVE original CI/CD files into .github/ci-archive/ and DELETE them from their original locations (see Archival below).
3. Deliver the report via PR: update an existing PR on the branch if present; otherwise create a new one. If PR creation/update is unavailable, the MIGRATION-README.md is the sole report.

Guardrails

❌ Never do

• Create workflows without a real source CI/CD file.
• Generate pipelines from descriptions or assumptions.
• Add functionality not in the source.
• Write custom actions, scripts, or bespoke integrations — find a marketplace action.
• Use unverified, community, or deprecated actions.
• Skip validation, leave originals in their original location, or ship placeholder text in the PR/report.

✅ Always do

• Work exclusively from the provided source files.
• Use only verified creators on the GitHub Marketplace — e.g. actions/*, azure/*, aws-actions/*, google-github-actions/*.
• Use the latest stable version of each action.
• Pin every action to a commit SHA (never a tag/branch); add a comment with the SHA→version mapping.
• Apply least-privilege permissions: blocks.
• Document every secret and variable the migrated workflow requires.

Action version verification

Never emit a commit SHA that is not present verbatim in the output of a command you ran in this session. A fabricated SHA either fails at dispatch time or resolves to an unintended commit.

Step 1 — check the shipped catalog first. pinned-actions.json in this skill directory holds verified SHAs for the actions this product emits most often. It ships with the plugin, so it works with no network at all:

grep -A2 '"actions/checkout"' plugin/skills/migration-core/pinned-actions.json

If the action is in the catalog, use that SHA and move on. Check resolved_on in the file — if it is more than about six months old, say so in the report so the user knows the pins are due a refresh.

Step 2 — capability probe. Only for actions the catalog does not cover. Network access is not guaranteed; offline and air-gapped installs are supported. Run this and branch on the result:

gh auth status >/dev/null 2>&1 && echo NETWORK_OK || echo NETWORK_UNAVAILABLE

Step 3a — if NETWORK_OK. Resolve the latest release tag, then resolve that tag to a commit SHA:

gh api repos/OWNER/REPO/releases/latest --jq .tag_name
gh api repos/OWNER/REPO/commits/TAG --jq .sha

Use commits/TAG rather than git/ref/tags/TAG — for an annotated tag the latter returns the tag object SHA, not the commit SHA.

If the repository publishes no releases, take the default-branch head:

gh api "repos/OWNER/REPO/commits?per_page=1" --jq '.[0].sha'

Step 3b — if NETWORK_UNAVAILABLE. Do not guess, and do not write a workflow step you cannot pin. Stop and tell the user which actions need resolving, so they can either grant network access or confirm the pin themselves. An unpinned action is a real defect — the quality gate will flag it, and it should.

A fully resolved pin looks like this:

# actions/checkout v7.0.1
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1

Secrets and variables

• ${{ secrets.NAME }} — sensitive credentials; never log or echo, never put values in workflow files.
• ${{ vars.NAME }} — non-sensitive configuration.
• Org-level for shared values; repo-level for project-specific values.
• Platform-specific secret syntax mappings live in the platform skill's mapping.md.

Deliverables and Archival

Required deliverables

1. Runnable .github/workflows/*.yml replicating source functionality.
2. All required secrets/variables documented with names and purpose.
3. Conversion explanations as comments in workflows and notes in the report.
4. Real actionlint output pasted into the report (see actionlint skill).
5. Source files archived and deleted from original locations.
6. .github/ci-archive/MIGRATION-README.md — complete, no placeholders.
7. Pull Request with the report as its body (or MIGRATION-README.md as fallback).

Archival protocol

mkdir -p .github/ci-archive/

MOVE (don't copy) source CI/CD files. Examples:

Verify nothing remains in the original locations.

Completion Checklist (10 items)

Migration is NOT COMPLETE until all 10 are true:

1. Source file(s) provided and analyzed
2. Workflow(s) accurately replicate source functionality
3. Only verified marketplace actions used, latest stable versions, pinned to SHAs
4. actionlint executed per the actionlint skill; real output captured
5. All required secrets and variables documented
6. Original CI/CD files moved to .github/ci-archive/ and deleted from original locations
7. .github/ci-archive/MIGRATION-README.md written from the platform's report-template.md, no placeholders
8. Migration report delivered via PR (existing PR updated, or new PR created) where possible
9. All guardrails above satisfied
10. Response ends with:

Migration complete. MIGRATION-README.md created and Pull Request updated/created with migration report.

(If PR was unavailable: Migration complete. MIGRATION-README.md created in .github/ci-archive/)