GitHub Actions Migration Agents

Enterprise-grade GitHub Copilot agents that automatically migrate CI/CD pipelines from virtually any platform to GitHub Actions—powered by a comprehensive knowledgebase of migration patterns and best practices.

Why This Project?

Organizations migrating to GitHub Actions face:

• Inconsistent migrations across teams
• Loss of domain knowledge during manual conversions
• Security oversights with credentials
• Time-consuming manual work
• Lack of validation leading to broken workflows

This project delivers:

• ⚡ Faster than manual migration
• 🎯 Consistent quality using documented best practices
• ✅ Built-in validation with actionlint
• 📊 Complete documentation of every decision
• 🔄 Reusable patterns for future migrations

Available Migration Agents

The Reusable Workflow Builder scans multiple GitHub organizations, detects common CI/CD patterns (Node.js builds, AWS deployments, Docker workflows), and generates standardized reusable workflows—reducing duplication and capturing organizational best practices.

Choose Your Surface

This project ships the same agents for two GitHub Copilot surfaces. Pick the one that matches how your team works.

Both surfaces produce the same deliverables:

1. .github/workflows/*.yml — production-ready, validated workflows
2. .github/ci-archive/ — original files and MIGRATION-README.md preserved for reference
3. Pull Request — migration report in the PR body with validation results, required secrets, next steps, and knowledgebase references

🌐 Using the Copilot Cloud Agent

Agents live in agents/ and reference the knowledgebase in knowledge/ at runtime. They are deployed to your enterprise's .github-private repository so they're available to all internal repos.

Getting started

1. Deploy — Follow the Deployment Guide to set up the agents in your enterprise's .github-private repo.
2. Migrate — Run migrations using the Operations Guide.

Two ways to migrate

💻 Using the Copilot CLI

The same nine agents are packaged as a Copilot CLI plugin under plugin/, with the knowledgebase pre-split into composable skills. See plugin/README.md for the composition model and full skill catalog.

Option A — Install from the marketplace (use as-is)

Fastest path. Use this when you want the agents with the default knowledgebase.

copilot plugin marketplace add github/actions-migrations-via-copilot
copilot plugin install actions-migrator

The marketplace is defined in .github/plugin/marketplace.json.

Option B — Install locally (customize skills)

Use this when you want to tailor patterns, action mappings, security guardrails, or report templates to your organization.

git clone https://github.com/github/actions-migrations-via-copilot.git
cd actions-migrations-via-copilot
# edit files under plugin/skills/ to match your org's standards
copilot plugin install ./plugin

How Migration Works

Whichever surface you choose, each agent follows the same five-phase process:

1. Reads source CI/CD configuration files
2. References the knowledgebase for conversion patterns
3. Generates GitHub Actions workflows
4. Validates with actionlint
5. Documents all changes in a migration report

Documentation

Project Structure

.
├── agents/                    # Agent definitions (9 migration agents) — cloud agent / .github-private deployment
├── docs/                      # Deployment, operations, and extending guides
├── knowledge/                 # Migration knowledgebase (source of truth for cloud agent)
│   ├── actions-mapping/       # CI/CD → Actions mappings
│   ├── patterns/              # Platform-specific conversion patterns
│   └── report-template/       # Migration report templates
├── plugin/                    # Copilot CLI plugin (agents + composable skills, derived from knowledge/)
│   ├── plugin.json
│   ├── agents/                # 9 thin agent composers
│   └── skills/                # 11 skills (3 core + 8 platform)
└── .github/
    └── plugin/
        └── marketplace.json   # Copilot CLI plugin marketplace manifest

Detailed structure: See Extending Guide for complete file organization.

Contributing

We welcome contributions! See our guides:

• CONTRIBUTING.md — General contribution guidelines
• Extending Guide — Add new CI/CD platforms or improve agents

Ways to contribute:

• Add support for new CI/CD platforms
• Improve action mappings and patterns
• Enhance agent accuracy
• Report issues or suggest improvements

Support

• Documentation — Deployment | Operations | Extending | Plugin
• Discussions — Ask questions and share experiences
• Issues — Report bugs or request features
• GitHub Actions Docs — Official documentation

Acknowledgments

Built by GitHub Professional Services for enterprise CI/CD migration programs. Contributions from GitHub's field engineering, solutions architecture, and customer success teams.