migration-core

name	migration-core
description	5-phase migration process, security guardrails, deliverables, archival protocol, and the 10-item completion checklist for any CI/CD migration to GitHub Actions. Load at the start of every migration.

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

1. mcp_github_get_latest_release — find the current version.
2. mcp_github_get_tag — resolve the commit SHA.
3. Fallback: mcp_github_list_commits if the repo has no releases.

# actions/checkout v4.1.7
- uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332

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:

Original	Archive destination
Jenkinsfile	.github/ci-archive/Jenkinsfile
azure-pipelines.yml	.github/ci-archive/azure-pipelines.yml
.circleci/config.yml	.github/ci-archive/circleci-config.yml (delete .circleci/ dir)
.gitlab-ci.yml	.github/ci-archive/.gitlab-ci.yml
.travis.yml	.github/ci-archive/.travis.yml
.drone.yml	.github/ci-archive/.drone.yml
bitbucket-pipelines.yml	.github/ci-archive/bitbucket-pipelines.yml
bamboo-specs.yml	.github/ci-archive/bamboo-specs.yml

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/)