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.
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
| Agent | Migrates From | Handles |
|---|---|---|
| Jenkins Migrator | Jenkinsfile | Pipelines, shared libraries, Groovy scripts |
| Azure DevOps Migrator | azure-pipelines.yml | YAML pipelines, templates, variable groups |
| CircleCI Migrator | .circleci/config.yml | Workflows, jobs, Orbs |
| GitLab Migrator | .gitlab-ci.yml | Pipelines, includes, Pages |
| Travis CI Migrator | .travis.yml | Build matrix, deploy providers |
| Bamboo Migrator | bamboo-specs.yml | Build plans, deployment projects |
| Bitbucket Migrator | bitbucket-pipelines.yml | Pipelines, Pipes |
| Drone CI Migrator | .drone.yml | Pipelines, plugins |
| Reusable Workflow Builder | GitHub Actions across orgs | Pattern analysis, reusable workflows |
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.
This project ships the same agents for two GitHub Copilot surfaces. Pick the one that matches how your team works.
| Surface | Best For | How agents are delivered |
|---|---|---|
| 🌐 Copilot cloud agent | Org-wide rollout, batch migrations across many repos, central governance | Deployed to your enterprise's .github-private repository. Agents fetch the knowledgebase from knowledge/ at runtime via the GitHub MCP server. → Jump to setup |
| 💻 Copilot CLI | Local/interactive use, individual developers, customizing skills for your org | Installed as a Copilot CLI plugin. The knowledgebase ships pre-split into composable skills under plugin/—no runtime fetch required. → Jump to setup |
Both surfaces produce the same deliverables:
.github/workflows/*.yml— production-ready, validated workflows.github/ci-archive/— original files andMIGRATION-README.mdpreserved for reference- Pull Request — migration report in the PR body with validation results, required secrets, next steps, and knowledgebase references
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.
- Deploy — Follow the Deployment Guide to set up the agents in your enterprise's
.github-privaterepo. - Migrate — Run migrations using the Operations Guide.
| Method | Best For | Guide |
|---|---|---|
| Manual | Individual repos, testing | Operations Guide |
| Batch | Multiple repos, scale | Operations Guide |
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.
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@actions-migrations-via-copilotThe marketplace is defined in .github/plugin/marketplace.json.
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 ./pluginUse this when you need reproducible installs with lockfile-pinned versions, content-integrity scanning, SBOM export, or offline agent runtime — typical for regulated industries. Install itself still requires network access to fetch the CLI and the pinned package, but once apm install resolves the dependency, all primitives land on disk in your repo — so the agent's runtime never fetches from a marketplace or plugin cache.
Install the APM CLI once:
# macOS / Linux
curl -sSL https://aka.ms/apm-unix | sh# Windows
irm https://aka.ms/apm-windows | iexAdd the dependency to your project's apm.yml:
dependencies:
apm:
- github/actions-migrations-via-copilot/plugin#v1.3.0The /plugin suffix is a virtual path — it points APM at the plugin/ subdirectory where plugin.json lives, so APM treats this repo as a Plugin collection package type (APM docs) and dissects plugin.json to install the agents and skills.
Then run:
apm installAPM deploys the agents and skills into your repo, pins the resolved sources and content hashes in apm.lock.yaml, and content-scans every primitive before it reaches disk.
The #v1.3.0 above selects that exact Git tag, not the version declared in the
current plugin manifest. Cloning the default branch gets the current merged code.
For a newer pinned install, choose an existing tag from
Releases.
Maintainers should update this example only after the new tag is published and
the documented install has been verified in a clean project. Do not move an
existing release tag to deliver newer code.
This package deliberately keeps dependencies.mcp: []. Its agents use the
shipped action catalog first and authenticated gh commands when needed.
Adding an MCP tool allowlist would not restrict the shell access these agents
already have, and a remote MCP server does not solve offline access.
Teams that want a GitHub MCP server should configure it explicitly in their consumer project using the APM MCP guide. Choose only the read tools required for the task and verify they are exposed by the installed server and permitted by the chosen agent. Merely installing a server does not give this package's agents new tools.
Check the APM version and target before installing. Earlier testing with APM
0.26.0 wrote Copilot MCP configuration globally to ~/.copilot/mcp-config.json.
Current APM documentation describes project-scoped .github/mcp.json for
Copilot CLI and .vscode/mcp.json for VS Code; global installs use user-level
configuration. Review the actual file changes and credential handling before
sharing them. Do not commit tokens or overwrite unrelated MCP settings.
Whichever surface you choose, each agent follows the same five-phase process:
- Reads source CI/CD configuration files
- References the knowledgebase for conversion patterns
- Generates GitHub Actions workflows
- Validates with actionlint
- Documents all changes in a migration report
| Guide | Purpose |
|---|---|
| Deployment Guide | Set up agents in your enterprise (cloud agent) |
| Operations Guide | Use agents to migrate repositories |
| Extending Guide | Add new CI/CD platforms |
| Plugin README | Copilot CLI plugin details |
| Contributing Guide | Contribute improvements |
.
├── 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.
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
- Documentation — Deployment | Operations | Extending | Plugin
- Discussions — Ask questions and share experiences
- Issues — Report bugs or request features
- GitHub Actions Docs — Official documentation
Built by GitHub Professional Services for enterprise CI/CD migration programs. Contributions from GitHub's field engineering, solutions architecture, and customer success teams.