From 55694b89bf34b454d5a17243c205581b49aa0f98 Mon Sep 17 00:00:00 2001 From: antgrutta Date: Wed, 4 Feb 2026 14:28:27 -0500 Subject: [PATCH 1/5] Adding required files --- .github/ISSUE_TEMPLATE/bug_report.md | 27 ++++++++ .github/ISSUE_TEMPLATE/config.yml | 2 + .github/ISSUE_TEMPLATE/feature_request.md | 19 ++++++ .github/ISSUE_TEMPLATE/knowledge_updates.md | 13 ++++ CODE_OF_CONDUCT.md | 74 +++++++++++++++++++++ CONTRIBUTING.md | 59 ++++++++++++++++ LICENSE | 21 ++++++ README.md | 2 +- SECURITY.md | 31 +++++++++ SUPPORT.md | 11 +++ 10 files changed, 258 insertions(+), 1 deletion(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/ISSUE_TEMPLATE/knowledge_updates.md create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE create mode 100644 SECURITY.md create mode 100644 SUPPORT.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..89dc5a4 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,27 @@ +--- +name: Bug report +about: Create a report to help us improve +title: '[BUG]' +labels: '' +assignees: '' +--- + +**Describe the bug** +A clear and concise description of what the bug is. + +**To Reproduce** +Steps to reproduce the behavior: + +1. Go to '...' +2. Click on '....' +3. Scroll down to '....' +4. See error + +**Expected behavior** +A clear and concise description of what you expected to happen. + +**Screenshots** +If applicable, add screenshots to help explain your problem. + +**Additional context** +Add any other context about the problem here. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..4d3b612 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,2 @@ +--- +blank_issues_enabled: false \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..a60d242 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,19 @@ +--- +name: Feature request +about: Suggest an idea for this project +title: '[FEATURE]' +labels: '' +assignees: '' +--- + +**Is your feature request related to a problem? Please describe.** +A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] + +**Describe the solution you'd like** +A clear and concise description of what you want to happen. + +**Describe alternatives you've considered** +A clear and concise description of any alternative solutions or features you've considered. + +**Additional context** +Add any other context or screenshots about the feature request here. diff --git a/.github/ISSUE_TEMPLATE/knowledge_updates.md b/.github/ISSUE_TEMPLATE/knowledge_updates.md new file mode 100644 index 0000000..0583d53 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/knowledge_updates.md @@ -0,0 +1,13 @@ +--- +name: Knowledge update +about: Suggest additions or changes to the knowledgebase +title: '[KNOWLEDGE]' +labels: '' +assignees: '' +--- + +**Describe the knowledge update** +A clear and concise description of the knowledge you would like to add or change. + +**Additional context** +Add any other context or screenshots about the knowledge update here. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..6dc4b12 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,74 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or +advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at . All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..dc40f75 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,59 @@ +# Contributing + +:wave: Hi there! +We're thrilled that you'd like to contribute to this project. Your help is essential for keeping it great. + +## Submitting a pull request + +[Pull Requests][pulls] are used for adding new playbooks, roles, and documents to the repository, or editing the existing ones. + +### With write access + +1. Clone the repository (only if you do not have write access) +1. Create a new branch: `git checkout -b my-branch-name` +1. Make your change +1. Push and [submit a pull request][pr] +1. Pat yourself on the back and wait for your pull request to be reviewed and merged. + +### Without write access + +1. [Fork][fork] and clone the repository +1. Create a new branch: `git checkout -b my-branch-name` +1. Make your change +1. Push to your fork and [submit a pull request][pr] +1. Pat your self on the back and wait for your pull request to be reviewed and merged. + +Here are a few things you can do that will increase the likelihood of your pull request being accepted: + +- Keep your change as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, consider submitting them as separate pull requests. +- Write [good commit messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). + +Work in Progress pull requests are also welcome to get feedback early on, or if there is something blocking you. + +- Create a branch with a name that identifies the user and nature of the changes (similar to `user/branch-purpose`) +- Open a pull request + +## Releasing + +If you are the current maintainer of this action: + +1. Create a [Tag](https://stackoverflow.com/questions/18216991/create-a-tag-in-a-github-repository) +2. Draft [Release](https://help.github.com/en/github/administering-a-repository/managing-releases-in-a-repository) document explaining details of Release +3. Look for approval from [CODEOWNERS](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners) + +## Resources + +- [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/) +- [Using Pull Requests](https://help.github.com/articles/about-pull-requests/) +- [GitHub Help](https://help.github.com) +- [Hello World JavaScript Action](https://github.com/actions/hello-world-javascript-action) +- [action.yml documentation](https://help.github.com/en/articles/metadata-syntax-for-github-actions) +- [toolkit documentation](https://github.com/actions/toolkit/blob/master/README.md#packages) +- [publish using ncc](https://github.com/zeit/ncc) +- [versioning documentation](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md) +- [actions tab](https://github.com/actions/typescript-action/actions) for runs of this action! :rocket: +- [create a v1 tag](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md) + +[pulls]: https://github.com/actionsdesk/semver/pulls +[pr]: https://github.com/github/github-demo-stack/compare +[fork]: https://github.com/github/github-demo-stack/fork \ No newline at end of file diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..28a50fa --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright GitHub, Inc. + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index 4172d07..daefa8d 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# CI/CD Migration Custom Agents +# GitHub Actions Migration Agents Enterprise-grade GitHub Custom Agents that automatically migrate CI/CD pipelines from Jenkins, Azure DevOps, CircleCI, GitLab, and other platforms to GitHub Actionsβ€”powered by a comprehensive knowledgebase of migration patterns and best practices. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..abe011d --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,31 @@ +Thanks for helping make GitHub safe for everyone. + +# Security + +GitHub takes the security of our software products and services seriously, including all of the open source code repositories managed through our GitHub organizations, such as [GitHub](https://github.com/GitHub). + +Even though [open source repositories are outside of the scope of our bug bounty program](https://bounty.github.com/index.html#scope) and therefore not eligible for bounty rewards, we will ensure that your finding gets passed along to the appropriate maintainers for remediation. + +## Reporting Security Issues + +If you believe you have found a security vulnerability in any GitHub-owned repository, please report it to us through coordinated disclosure. + +**Please do not report security vulnerabilities through public GitHub issues, discussions, or pull requests.** + +Instead, please send an email to opensource-security[@]github.com. + +Please include as much of the information listed below as you can to help us better understand and resolve the issue: + + * The type of issue (e.g., buffer overflow, SQL injection, or cross-site scripting) + * Full paths of source file(s) related to the manifestation of the issue + * The location of the affected source code (tag/branch/commit or direct URL) + * Any special configuration required to reproduce the issue + * Step-by-step instructions to reproduce the issue + * Proof-of-concept or exploit code (if possible) + * Impact of the issue, including how an attacker might exploit the issue + +This information will help us triage your report more quickly. + +## Policy + +See [GitHub's Safe Harbor Policy](https://docs.github.com/en/site-policy/security-policies/github-bug-bounty-program-legal-safe-harbor#1-safe-harbor-terms) diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 0000000..aab64d4 --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,11 @@ +# Support + +## How to file issues and get help + +This project uses GitHub issues to track bugs and feature requests. Please search the existing issues before filing new issues to avoid duplicates. For new issues, file your bug or feature request as a new issue. + +For help or questions about using this project, please file an issue. + +## GitHub Support Policy + +Support for this project is limited to the resources listed above. \ No newline at end of file From a7a5724ed3dcf8db1f3093331e5a7a285f609027 Mon Sep 17 00:00:00 2001 From: antgrutta Date: Wed, 4 Feb 2026 14:37:51 -0500 Subject: [PATCH 2/5] Better issue templates --- .github/ISSUE_TEMPLATE/bug_report.md | 27 ------ .github/ISSUE_TEMPLATE/config.yml | 6 +- .github/ISSUE_TEMPLATE/documentation.md | 26 ++++++ .github/ISSUE_TEMPLATE/feature_request.md | 19 ---- .github/ISSUE_TEMPLATE/knowledge_updates.md | 13 --- .github/ISSUE_TEMPLATE/knowledgebase.md | 42 +++++++++ .github/ISSUE_TEMPLATE/migration_agent.md | 44 +++++++++ .../ISSUE_TEMPLATE/migration_automation.md | 39 ++++++++ CONTRIBUTING.md | 90 +++++++++++++------ 9 files changed, 219 insertions(+), 87 deletions(-) delete mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/documentation.md delete mode 100644 .github/ISSUE_TEMPLATE/feature_request.md delete mode 100644 .github/ISSUE_TEMPLATE/knowledge_updates.md create mode 100644 .github/ISSUE_TEMPLATE/knowledgebase.md create mode 100644 .github/ISSUE_TEMPLATE/migration_agent.md create mode 100644 .github/ISSUE_TEMPLATE/migration_automation.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md deleted file mode 100644 index 89dc5a4..0000000 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -name: Bug report -about: Create a report to help us improve -title: '[BUG]' -labels: '' -assignees: '' ---- - -**Describe the bug** -A clear and concise description of what the bug is. - -**To Reproduce** -Steps to reproduce the behavior: - -1. Go to '...' -2. Click on '....' -3. Scroll down to '....' -4. See error - -**Expected behavior** -A clear and concise description of what you expected to happen. - -**Screenshots** -If applicable, add screenshots to help explain your problem. - -**Additional context** -Add any other context about the problem here. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 4d3b612..89c5581 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,2 +1,6 @@ --- -blank_issues_enabled: false \ No newline at end of file +blank_issues_enabled: false +contact_links: + - name: General Questions + url: https://github.com/github/actions-migrations-via-copilot/discussions + about: Ask questions and discuss ideas in GitHub Discussions diff --git a/.github/ISSUE_TEMPLATE/documentation.md b/.github/ISSUE_TEMPLATE/documentation.md new file mode 100644 index 0000000..21e3c60 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/documentation.md @@ -0,0 +1,26 @@ +--- +name: Documentation Improvement +about: Suggest improvements to deployment, operations, or other documentation +title: '[DOCS]' +labels: 'documentation' +assignees: '' +--- + +**Which documentation area does this relate to?** +- [ ] Deployment Guide (`docs/deployment.md`) +- [ ] Operations Guide (`docs/operations.md`) +- [ ] README +- [ ] Contributing Guide +- [ ] New documentation needed + +**Describe the improvement** +A clear and concise description of what should be added, changed, or clarified. + +**Current documentation issue (if applicable)** +Describe what is missing, unclear, or incorrect in the current documentation. + +**Proposed content or changes** +Outline the content or changes you'd like to see. + +**Additional context** +Add any other context, links to related issues, or examples from other projects. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md deleted file mode 100644 index a60d242..0000000 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -name: Feature request -about: Suggest an idea for this project -title: '[FEATURE]' -labels: '' -assignees: '' ---- - -**Is your feature request related to a problem? Please describe.** -A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] - -**Describe the solution you'd like** -A clear and concise description of what you want to happen. - -**Describe alternatives you've considered** -A clear and concise description of any alternative solutions or features you've considered. - -**Additional context** -Add any other context or screenshots about the feature request here. diff --git a/.github/ISSUE_TEMPLATE/knowledge_updates.md b/.github/ISSUE_TEMPLATE/knowledge_updates.md deleted file mode 100644 index 0583d53..0000000 --- a/.github/ISSUE_TEMPLATE/knowledge_updates.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -name: Knowledge update -about: Suggest additions or changes to the knowledgebase -title: '[KNOWLEDGE]' -labels: '' -assignees: '' ---- - -**Describe the knowledge update** -A clear and concise description of the knowledge you would like to add or change. - -**Additional context** -Add any other context or screenshots about the knowledge update here. diff --git a/.github/ISSUE_TEMPLATE/knowledgebase.md b/.github/ISSUE_TEMPLATE/knowledgebase.md new file mode 100644 index 0000000..97a6389 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/knowledgebase.md @@ -0,0 +1,42 @@ +--- +name: Knowledgebase Update +about: Suggest updates to action mappings, patterns, or best practices +title: '[KNOWLEDGE]' +labels: 'knowledgebase' +assignees: '' +--- + +**Which knowledgebase area does this relate to?** +- [ ] Action Mappings (`knowledge/actions-mapping/`) +- [ ] Security Patterns (`knowledge/patterns/`) +- [ ] Report Templates (`knowledge/report-template/`) +- [ ] Migration Standards (`knowledge/migration-standards.md`) +- [ ] Migration Guardrails (`knowledge/migration-guardrails.md`) +- [ ] Migration Workflow (`knowledge/migration-workflow.md`) + +**Which CI/CD platform does this relate to? (if applicable)** +- [ ] Jenkins +- [ ] Azure DevOps +- [ ] CircleCI +- [ ] GitLab +- [ ] Travis CI +- [ ] Bamboo +- [ ] Bitbucket +- [ ] Drone CI +- [ ] General / All platforms + +**Describe the update** +A clear and concise description of what should be added or changed. + +**Source plugin/task/command** +``` +# The CI/CD plugin, task, or command that needs mapping +``` + +**Proposed GitHub Actions equivalent** +```yaml +# The GitHub Actions equivalent or pattern +``` + +**Additional context** +Add any documentation links, examples, or other context that supports this update. diff --git a/.github/ISSUE_TEMPLATE/migration_agent.md b/.github/ISSUE_TEMPLATE/migration_agent.md new file mode 100644 index 0000000..f80ebee --- /dev/null +++ b/.github/ISSUE_TEMPLATE/migration_agent.md @@ -0,0 +1,44 @@ +--- +name: Migration Agent Improvement +about: Suggest improvements or report issues with migration agents +title: '[AGENT]' +labels: 'agents' +assignees: '' +--- + +**Which migration agent does this relate to?** +- [ ] Jenkins Migrator +- [ ] Azure DevOps Migrator +- [ ] CircleCI Migrator +- [ ] GitLab Migrator +- [ ] Travis CI Migrator +- [ ] Bamboo Migrator +- [ ] Bitbucket Migrator +- [ ] Drone CI Migrator +- [ ] Reusable Workflow Builder +- [ ] New platform (please specify) + +**Is this a bug or an improvement?** +- [ ] Bug - Agent produces incorrect output +- [ ] Improvement - Agent could handle this better + +**Describe the issue or improvement** +A clear and concise description of the problem or enhancement. + +**Source CI/CD configuration (if applicable)** +```yaml +# Paste the source CI/CD configuration that the agent struggles with +``` + +**Expected GitHub Actions output** +```yaml +# Paste the expected GitHub Actions workflow output +``` + +**Actual output (if bug)** +```yaml +# Paste the actual output the agent produced +``` + +**Additional context** +Add any other context, screenshots, or migration report excerpts here. diff --git a/.github/ISSUE_TEMPLATE/migration_automation.md b/.github/ISSUE_TEMPLATE/migration_automation.md new file mode 100644 index 0000000..4c85339 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/migration_automation.md @@ -0,0 +1,39 @@ +--- +name: Migration Automation Improvement +about: Suggest improvements to bulk migration workflows and automation +title: '[AUTOMATION]' +labels: 'automation' +assignees: '' +--- + +**What type of automation improvement is this?** +- [ ] New automation capability +- [ ] Enhancement to existing workflow +- [ ] Bug fix for automation +- [ ] Performance optimization +- [ ] Scheduling/trigger improvement + +**Describe the improvement or issue** +A clear and concise description of the automation enhancement or problem. + +**Use case** +Describe the scenario where this automation improvement would be beneficial. + +**Current behavior (if applicable)** +Describe how the automation currently works. + +**Expected behavior** +Describe how the automation should work after this improvement. + +**Proposed implementation (optional)** +```yaml +# Outline the workflow changes or new automation approach +``` + +**Scale considerations** +- Approximate number of repositories this would affect: +- Expected frequency of execution: +- Any rate limiting or resource concerns: + +**Additional context** +Add any other context, error logs, or workflow run links here. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dc40f75..ae0d910 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,59 +1,95 @@ # Contributing :wave: Hi there! -We're thrilled that you'd like to contribute to this project. Your help is essential for keeping it great. +We're thrilled that you'd like to contribute to the GitHub Actions Migration Agents project. Your help is essential for keeping our migration agents, knowledgebase, and patterns up-to-date and effective. -## Submitting a pull request +## Ways to Contribute -[Pull Requests][pulls] are used for adding new playbooks, roles, and documents to the repository, or editing the existing ones. +### Migration Agents (`agents/`) -### With write access +- Improve existing migration agent prompts for better accuracy +- Add support for new CI/CD platforms +- Enhance agent instructions based on real-world migration feedback -1. Clone the repository (only if you do not have write access) +### Knowledgebase (`knowledge/`) + +- Add or update action mappings for CI/CD plugins and tasks +- Document new migration patterns and best practices +- Improve security patterns for credential handling +- Expand report templates with additional insights + +### Documentation (`docs/`) + +- Improve deployment and operations guides +- Add troubleshooting tips and FAQs +- Document edge cases and workarounds + +### Migration Automation (`.github/workflows/`) + +- Enhance bulk migration workflows +- Improve automation triggers and scheduling +- Add new automation capabilities for enterprise-scale migrations +- Optimize workflow performance and reliability + +## Submitting a Pull Request + +[Pull Requests][pulls] are used for adding new agents, patterns, mappings, and documentation, or improving existing ones. + +### With Write Access + +1. Clone the repository 1. Create a new branch: `git checkout -b my-branch-name` -1. Make your change +1. Make your changes 1. Push and [submit a pull request][pr] -1. Pat yourself on the back and wait for your pull request to be reviewed and merged. +1. Wait for your pull request to be reviewed and merged -### Without write access +### Without Write Access 1. [Fork][fork] and clone the repository 1. Create a new branch: `git checkout -b my-branch-name` -1. Make your change +1. Make your changes 1. Push to your fork and [submit a pull request][pr] -1. Pat your self on the back and wait for your pull request to be reviewed and merged. +1. Wait for your pull request to be reviewed and merged -Here are a few things you can do that will increase the likelihood of your pull request being accepted: +### Tips for a Successful PR - Keep your change as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, consider submitting them as separate pull requests. - Write [good commit messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). +- Test agent changes with real CI/CD configurations when possible. +- Follow the existing structure and formatting conventions in the knowledgebase. Work in Progress pull requests are also welcome to get feedback early on, or if there is something blocking you. - Create a branch with a name that identifies the user and nature of the changes (similar to `user/branch-purpose`) -- Open a pull request +- Open a pull request and mark it as a draft + +## Adding a New CI/CD Platform + +To add support for a new CI/CD platform: + +1. Create a new agent file in `agents/` (follow existing agent structure) +2. Add action mappings in `knowledge/actions-mapping/` +3. Add security patterns in `knowledge/patterns//` +4. Add a report template in `knowledge/report-template/` +5. Update the README.md to include the new platform ## Releasing -If you are the current maintainer of this action: +If you are a maintainer of this project: -1. Create a [Tag](https://stackoverflow.com/questions/18216991/create-a-tag-in-a-github-repository) -2. Draft [Release](https://help.github.com/en/github/administering-a-repository/managing-releases-in-a-repository) document explaining details of Release -3. Look for approval from [CODEOWNERS](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners) +1. Create a [Tag](https://stackoverflow.com/questions/18216991/create-a-tag-in-a-github-repository) following semantic versioning +2. Draft a [Release](https://help.github.com/en/github/administering-a-repository/managing-releases-in-a-repository) document explaining the changes +3. Obtain approval from [CODEOWNERS](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners) ## Resources - [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/) - [Using Pull Requests](https://help.github.com/articles/about-pull-requests/) - [GitHub Help](https://help.github.com) -- [Hello World JavaScript Action](https://github.com/actions/hello-world-javascript-action) -- [action.yml documentation](https://help.github.com/en/articles/metadata-syntax-for-github-actions) -- [toolkit documentation](https://github.com/actions/toolkit/blob/master/README.md#packages) -- [publish using ncc](https://github.com/zeit/ncc) -- [versioning documentation](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md) -- [actions tab](https://github.com/actions/typescript-action/actions) for runs of this action! :rocket: -- [create a v1 tag](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md) - -[pulls]: https://github.com/actionsdesk/semver/pulls -[pr]: https://github.com/github/github-demo-stack/compare -[fork]: https://github.com/github/github-demo-stack/fork \ No newline at end of file +- [GitHub Actions Documentation](https://docs.github.com/en/actions) +- [GitHub Copilot Custom Agents](https://docs.github.com/en/copilot) +- [Workflow Syntax for GitHub Actions](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions) + +[pulls]: https://github.com/github/actions-migrations-via-copilot/pulls +[pr]: https://github.com/github/actions-migrations-via-copilot/compare +[fork]: https://github.com/github/actions-migrations-via-copilot/fork \ No newline at end of file From 19669960ca4508ca68fbddd95e36fa04791ad8ec Mon Sep 17 00:00:00 2001 From: antgrutta Date: Wed, 4 Feb 2026 15:26:20 -0500 Subject: [PATCH 3/5] Adding dependabot and release config --- .github/dependabot.yml | 21 +++++++++++++++++++++ .github/release.yml | 28 ++++++++++++++++++++++++++++ 2 files changed, 49 insertions(+) create mode 100644 .github/dependabot.yml create mode 100644 .github/release.yml diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..f8e5b01 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,21 @@ +# Dependabot configuration for automated dependency updates +# See: https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file + +version: 2 +updates: + # Maintain dependencies for GitHub Actions + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" + day: "monday" + open-pull-requests-limit: 5 + groups: + # Group GitHub official actions + github-actions: + patterns: + - "actions/*" + labels: + - "dependencies" + - "github-actions" + - "automation" diff --git a/.github/release.yml b/.github/release.yml new file mode 100644 index 0000000..07919d0 --- /dev/null +++ b/.github/release.yml @@ -0,0 +1,28 @@ +# Configuration for GitHub's auto-generated release notes +# https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes + +changelog: + exclude: + labels: + - ignore-for-release + - duplicate + - invalid + - wontfix + authors: + - dependabot + categories: + - title: πŸ€– Migration Agent Improvements + labels: + - agents + - title: πŸ“š Knowledgebase Updates + labels: + - knowledgebase + - title: πŸ”„ Migration Automation + labels: + - automation + - title: πŸ“– Documentation + labels: + - documentation + - title: Other Changes + labels: + - "*" From c88237b882c27010fb4ebc2aa7d370a79e46fc9d Mon Sep 17 00:00:00 2001 From: antgrutta Date: Wed, 4 Feb 2026 15:29:47 -0500 Subject: [PATCH 4/5] remove extra dependabot label --- .github/dependabot.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/dependabot.yml b/.github/dependabot.yml index f8e5b01..3bb1976 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -18,4 +18,3 @@ updates: labels: - "dependencies" - "github-actions" - - "automation" From 96c030473024791a3c958bfb6f9f5067b4bba4ee Mon Sep 17 00:00:00 2001 From: antgrutta Date: Wed, 4 Feb 2026 15:56:40 -0500 Subject: [PATCH 5/5] simplify documentation --- README.md | 287 +++++++---------------- docs/deployment.md | 540 +++++++++++++++----------------------------- docs/extending.md | 159 +++++++++++++ docs/operations.md | 551 +++++++++------------------------------------ 4 files changed, 522 insertions(+), 1015 deletions(-) create mode 100644 docs/extending.md diff --git a/README.md b/README.md index daefa8d..391c394 100644 --- a/README.md +++ b/README.md @@ -1,250 +1,125 @@ # GitHub Actions Migration Agents -Enterprise-grade GitHub Custom Agents that automatically migrate CI/CD pipelines from Jenkins, Azure DevOps, CircleCI, GitLab, and other platforms to GitHub Actionsβ€”powered by a comprehensive knowledgebase of migration patterns and best practices. +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? -### The Challenge +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 -Organizations migrating to GitHub Actions face common obstacles: - -- **Inconsistent migrations** across teams and repositories -- **Loss of domain knowledge** during manual conversions -- **Security oversights** when migrating credentials and secrets -- **Time-consuming manual work** translating CI/CD syntax -- **Lack of validation** leading to broken workflows post-migration - -### The Solution - -**Agent-Powered Migration Benefits:** - -- ⚑ **10-100x faster** than manual migration +**This project delivers:** +- ⚑ **Faster** than manual migration - 🎯 **Consistent quality** using documented best practices -- πŸ”’ **Security-first** approach to credential migration -- βœ… **Built-in validation** with actionlint and dry-run testing -- πŸ“Š **Complete documentation** of every migration decision -- πŸ”„ **Reusable patterns** captured for future migrations +- βœ… **Built-in validation** with actionlint +- πŸ“Š **Complete documentation** of every decision +- πŸ”„ **Reusable patterns** for future migrations ## How It Works -### Architecture - -```mermaid -graph TB - subgraph GHE["GitHub Enterprise Cloud"] - Private[".github-private Repository"] - Agents["Migration Agents
β€’ Jenkins Migrator
β€’ Azure DevOps Migrator
β€’ CircleCI Migrator
β€’ GitLab Migrator
β€’ Travis CI Migrator
β€’ Bamboo Migrator
β€’ Bitbucket Migrator
β€’ Drone CI Migrator
β€’ Reusable Workflow Builder"] - KB["Knowledgebase
β€’ Migration Standards
β€’ Action Mappings
β€’ Security Patterns
β€’ Best Practices
β€’ Validation Rules"] - Automation["GitHub Actions Workflows
(Automated bulk migrations)"] - - Private -.-> Agents - Private -.-> KB - Private -.-> Automation - Agents -."references"..-> KB - - CopilotAgents["GitHub Copilot Agents
(Available to Enterprise Users)"] - Agents --> CopilotAgents - - Reusable["reusable-workflows Repository
(Generated reusable workflows)"] - CopilotAgents -.->|"generates workflows"| Reusable - - UserRepos["User Repositories
(CI/CD files being migrated)"] - CopilotAgents -."invoked from".-> UserRepos - Automation -->|"invokes agents
across repos"| CopilotAgents - end +Migration agents are GitHub Copilot Custom Agents deployed to your enterprise's `.github-private` repository. Each agent: - User["πŸ‘€ User"] -->|"invokes manually"| CopilotAgents - User -->|"triggers automation"| Automation -``` - -### Migration Process - -Each migration follows a standardized five-phase process: - -1. **Analysis** - - Read source files - - Parse CI/CD syntax - - Expand templates - - Resolve dependencies - -2. **Conversion** - - Reference knowledgebase - - Map to GitHub Actions - - Apply patterns - - Generate workflows +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 -3. **Validation** - - YAML syntax validation with actionlint - - Security and best practices review +**Knowledgebase-driven:** Agents fetch patterns, security guidelines, and action mappings from `knowledge/` during each migration, ensuring consistent, up-to-date conversions. -4. **Archival** - - Preserve history - - Archive original files - -5. **Documentation** - - Document changes and decisions - - Create migration report - - List next steps - - Include validation results - -### Knowledgebase-Driven Intelligence +## Available Migration Agents -The knowledgebase is the "brain" behind consistent 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 | -| Component | Purpose | Example | -| ----------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------- | -| **Migration Standards** | Define quality requirements, deliverables, and validation criteria | "All workflows must pass actionlint validation" | -| **Action Mappings** | Map CI/CD plugins/tasks to equivalent GitHub Actions | `maven-plugin` β†’ `actions/setup-java` + Maven commands | -| **Security Patterns** | Template secure credential handling | Jenkins `withCredentials` β†’ GitHub Secrets with least privilege | -| **Common Patterns** | Reusable conversion templates | Multi-stage pipeline β†’ Multiple workflow jobs | -| **Validation Rules** | Automated quality checks | Required fields, best practices, security checks | +### Reusable Workflow Builder -Agents dynamically fetch relevant knowledgebase content during migrations, ensuring every conversion benefits from accumulated organizational knowledge. +This unique agent 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. ## What You Get -### Migration Deliverables - Every migration produces: -1. **GitHub Actions Workflows** (`.github/workflows/`) - - Production-ready, validated YAML - - Optimized for performance and security - - Uses latest action versions - -2. **Archived Originals** (`.github/ci-archive/`) - - Complete preservation of source files - - Organized by CI/CD system - - Reference for future audits - -3. **Migration Report** (`.github/ci-archive/MIGRATION-README.md`) - - Detailed conversion documentation - - Validation results (actionlint) - - Next steps and recommendations - - Knowledgebase references used - -4. **Security Enhancements** - - Proper GitHub Secrets usage - - Least-privilege permissions - - Updated action versions - - Security scanning recommendations - -## Available Migration Agents - -| Agent | Migrates From | Handles | -| ----------------------------- | ---------------------------------- | ---------------------------------------------- | -| **Jenkins Migrator** | Jenkinsfile (declarative/scripted) | 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, GitLab 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 workflow generation | - -### Special Agent: Reusable Workflow Builder - -The **Reusable Workflow Builder** is uniqueβ€”it analyzes CI/CD patterns across your GitHub organization(s) and generates standardized reusable workflows. - -**How it works:** - -- **Input**: Scans multiple GitHub organizations (e.g., 3 orgs with 100+ repos total) -- **Analysis**: Detects common patterns across repositories - - Build patterns (Node.js, Python, Go, Java) - - Deployment patterns (AWS, Azure, Kubernetes) - - Common tooling (Docker, security scanning) -- **Output**: Generates reusable workflows in `.github/workflows/` with usage documentation - -This agent reduces duplication, standardizes CI/CD across your enterprise, and captures organizational best practices as reusable workflows. +1. **`.github/workflows/*.yml`** - Production-ready, validated workflows +2. **`.github/ci-archive/`** - Original files preserved for reference +3. **`.github/ci-archive/MIGRATION-README.md`** - Detailed report with: + - Validation results + - Required secrets + - Next steps + - Knowledgebase references ## Getting Started ### Quick Start -1. **Deploy to your enterprise** following the [Deployment Guide β†’](docs/deployment.md) -2. **Invoke an agent** from [github.com/copilot/agents](https://github.com/copilot/agents) -3. **Review and test** the migrated workflows -4. **Merge and deploy** your new GitHub Actions workflows +1. **Deploy** - Follow the [Deployment Guide](docs/deployment.md) to set up agents in your enterprise +2. **Migrate** - Use the [Operations Guide](docs/operations.md) to run migrations +3. **Extend** - Add new platforms using the [Extending Guide](docs/extending.md) + +### Two Ways to Migrate + +| Method | Best For | Guide | +| ---------- | ------------------------- | ------------------------------------------------------- | +| **Manual** | Individual repos, testing | [Operations Guide](docs/operations.md#manual-migration) | +| **Batch** | Multiple repos, scale | [Operations Guide](docs/operations.md#batch-migration) | -### Documentation +## Documentation -- **[Deployment Guide](docs/deployment.md)** - Complete enterprise setup instructions -- **[Operations Guide](docs/operations.md)** - Day-to-day usage playbooks for each agent -- **[Migration Knowledgebase](knowledge/)** - Standards, patterns, and mappings used by agents +| Guide | Purpose | +| ------------------------------------------ | ---------------------------------- | +| **[Deployment Guide](docs/deployment.md)** | Set up agents in your enterprise | +| **[Operations Guide](docs/operations.md)** | Use agents to migrate repositories | +| **[Extending Guide](docs/extending.md)** | Add new CI/CD platforms | +| **[Contributing Guide](CONTRIBUTING.md)** | Contribute improvements | ## Project Structure ``` . -β”œβ”€β”€ agents/ # Agent definition files -β”‚ β”œβ”€β”€ jenkins-migrator.md -β”‚ β”œβ”€β”€ azure-devops-migrator.md -β”‚ β”œβ”€β”€ circleci-migrator.md -β”‚ β”œβ”€β”€ gitlab-migrator.md -β”‚ β”œβ”€β”€ travisci-migrator.md -β”‚ β”œβ”€β”€ bamboo-migrator.md -β”‚ β”œβ”€β”€ bitbucket-migrator.md -β”‚ β”œβ”€β”€ droneci-migrator.md -β”‚ └── reusable-workflow-builder.md -β”‚ -β”œβ”€β”€ docs/ # Documentation -β”‚ β”œβ”€β”€ deployment.md # Enterprise deployment guide -β”‚ └── operations.md # Day-to-day operations playbooks -β”‚ -β”œβ”€β”€ knowledge/ # Migration knowledgebase (deploy to .github-private) -β”‚ β”œβ”€β”€ README.md # Knowledgebase overview -β”‚ β”œβ”€β”€ migration-standards.md # Quality and validation standards -β”‚ β”œβ”€β”€ migration-workflow.md # Standard 5-phase process -β”‚ β”œβ”€β”€ migration-guardrails.md # Security and safety guidelines -β”‚ β”‚ -β”‚ β”œβ”€β”€ actions-mapping/ # CI/CD tool β†’ Actions mappings -β”‚ β”‚ β”œβ”€β”€ jenkins.md -β”‚ β”‚ β”œβ”€β”€ azure-devops.md -β”‚ β”‚ β”œβ”€β”€ circleci.md -β”‚ β”‚ β”œβ”€β”€ gitlab.md -β”‚ β”‚ β”œβ”€β”€ travisci.md -β”‚ β”‚ β”œβ”€β”€ bamboo.md -β”‚ β”‚ β”œβ”€β”€ bitbucket.md -β”‚ β”‚ └── droneci.md -β”‚ β”‚ -β”‚ β”œβ”€β”€ patterns/ # System-specific patterns -β”‚ β”‚ β”œβ”€β”€ jenkins/ -β”‚ β”‚ β”‚ β”œβ”€β”€ pipeline.md # Pipeline conversions -β”‚ β”‚ β”‚ β”œβ”€β”€ groovy.md # Groovy script handling -β”‚ β”‚ β”‚ └── secrets.md # Credential migration -β”‚ β”‚ β”œβ”€β”€ azure-devops/ -β”‚ β”‚ β”‚ └── secrets.md -β”‚ β”‚ β”œβ”€β”€ circleci/ -β”‚ β”‚ β”‚ └── secrets.md -β”‚ β”‚ └── ... (other systems) -β”‚ β”‚ +β”œβ”€β”€ agents/ # Agent definitions (9 migration agents) +β”œβ”€β”€ docs/ # Deployment, operations, and extending guides +β”œβ”€β”€ knowledge/ # Migration knowledgebase +β”‚ β”œβ”€β”€ actions-mapping/ # CI/CD β†’ Actions mappings +β”‚ β”œβ”€β”€ patterns/ # Platform-specific conversion patterns β”‚ └── report-template/ # Migration report templates -β”‚ β”œβ”€β”€ jenkins.md -β”‚ β”œβ”€β”€ azure-devops.md -β”‚ └── ... (other systems) -β”‚ -└── README.md # This file (project overview) +└── .github/ # Automation workflows ``` -## Support and Resources - -- **[Deployment Guide](docs/deployment.md)** - Enterprise setup and configuration -- **[Operations Guide](docs/operations.md)** - Daily usage playbooks -- **[GitHub Actions Documentation](https://docs.github.com/actions)** - Official Actions docs -- **[GitHub Community](https://github.community)** - Community support +**Detailed structure:** See [Extending Guide](docs/extending.md#quick-reference) for complete file organization. ## Contributing -Contributions to improve agents and knowledgebase are welcome: +We welcome contributions! See our guides: + +- **[CONTRIBUTING.md](CONTRIBUTING.md)** - General contribution guidelines +- **[Extending Guide](docs/extending.md)** - 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 -1. **Enhance agents** - Improve conversion accuracy and coverage -2. **Update mappings** - Add new CI/CD tool to Actions mappings -3. **Document patterns** - Share successful migration patterns -4. **Refine standards** - Improve quality and validation criteria -5. **Report issues** - Submit bug reports or feature requests +- **Documentation** - [Deployment](docs/deployment.md) | [Operations](docs/operations.md) | [Extending](docs/extending.md) +- **Discussions** - [Ask questions and share experiences](https://github.com/github/actions-migrations-via-copilot/discussions) +- **Issues** - [Report bugs or request features](https://github.com/github/actions-migrations-via-copilot/issues) +- **GitHub Actions Docs** - [Official documentation](https://docs.github.com/actions) ## Acknowledgments -Built by GitHub Professional Services for enterprise CI/CD migration programs. Contributions from teams across GitHub's field engineering, solutions architecture, and customer success organizations. +Built by GitHub Professional Services for enterprise CI/CD migration programs. Contributions from GitHub's field engineering, solutions architecture, and customer success teams. diff --git a/docs/deployment.md b/docs/deployment.md index 4c75f68..c951c2c 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -1,424 +1,238 @@ # Deployment Guide -This guide provides step-by-step instructions for deploying CI/CD Migration Custom Agents to your GitHub Enterprise environment. +Deploy GitHub Actions Migration Agents to your GitHub Enterprise environment. + +## Quick Setup + +1. Create `.github-private` repository (Internal visibility) +2. Clone and configure this repository +3. Push to `.github-private` +4. Configure secrets and variables for automation +5. Enable agents in Enterprise settings ## Prerequisites -Before beginning deployment, ensure you have: +- GitHub Enterprise Cloud with Copilot Business/Enterprise +- Enterprise Owner permissions +- Organization Admin permissions +- Git client -- **GitHub Enterprise Cloud** with GitHub Copilot Business or Enterprise subscription -- **Enterprise Owner permissions** to configure custom agents -- **Organization Admin permissions** for the target organization -- **Git client** installed on your local machine -- **Access to create repositories** in your enterprise organization +## Step 1: Create .github-private Repository -## Deployment Steps +1. **Create repository** in your organization: + - Name: `.github-private` (exact name required) + - Visibility: **Internal** (required for agent access to knowledgebase) + - Do not initialize with README -### Step 1: Create the .github-private Repository +2. **Note the repository URL** for later steps -The `.github-private` repository serves as the central location for custom agents and the migration knowledgebase. +> **Why Internal?** Agents use GitHub MCP to access knowledgebase files. Internal visibility enables this while keeping content private to your enterprise. -1. **Navigate to your enterprise organization** on GitHub.com +## Step 2: Configure and Deploy -2. **Create a new repository**: - - Click **"New repository"** - - Repository name: **`.github-private`** (exactly as shown, including the leading dot) - - Visibility: **Internal** (REQUIRED - allows agents to access knowledgebase) - - Initialize: Do not initialize with README, .gitignore, or license +### Clone Repository -3. **Verify repository settings**: - - Confirm visibility is set to **Internal** - - Note the repository URL for the next steps +```bash +git clone https://github.com/github/actions-migrations-via-copilot.git +cd actions-migrations-via-copilot +``` -> **Why Internal visibility?** Agents use the GitHub MCP (Model Context Protocol) server to access knowledgebase files during migrations. Internal visibility ensures agents can read these files while keeping them private to your enterprise. +### Update Organization References -### Step 2: Clone and Prepare the Source Repository +Replace `{MY_ORGANIZATION}` with your organization slug: -1. **Clone this repository** to your local machine: - ```bash - git clone https://github.com/github/actions-migrations-via-copilot.git - cd actions-migrations-via-copilot - ``` +```bash +# macOS/Linux +find agents -name "*.md" -type f -exec sed -i '' 's/{MY_ORGANIZATION}/YOUR-ORG-SLUG/g' {} + -2. **Review the directory structure**: - ```bash - tree -aL 1 - ``` +# Verify +grep -r "{MY_ORGANIZATION}" agents/ +``` - You should see: - ``` - . - β”œβ”€β”€ .git/ # Git metadata - β”œβ”€β”€ .github/ # GitHub Actions workflows, settings, and supporting scripts - β”œβ”€β”€ .gitignore # Git ignore file - β”œβ”€β”€ agents/ # Agent definition files - β”œβ”€β”€ docs/ # Deployment and operations documentation - β”œβ”€β”€ knowledge/ # Migration knowledgebase - └── README.md - ``` +Should return no results. -### Step 3: Configure Organization References +### Push to .github-private -Before deploying, update all agent files to reference your organization. +```bash +git remote add enterprise https://github.com/YOUR-ORG-SLUG/.github-private.git +git push enterprise main +``` -1. **Identify your organization slug**: - - Your organization slug is visible in URLs: `github.com/{organization-slug}` - - Example: For `github.com/acme-corp`, the slug is `acme-corp` - -2. **Update agent files** with your organization slug: - ```bash - # Replace {MY_ORGANIZATION} in all agent files - find agents -name "*.md" -type f -exec sed -i '' 's/{MY_ORGANIZATION}/YOUR-ORG-SLUG/g' {} + - ``` - - Replace `YOUR-ORG-SLUG` with your actual organization slug. - -3. **Verify the changes**: - ```bash - grep -r "YOUR-ORG-SLUG" agents/ - ``` - - Ensure all references have been updated. - -### Step 4: Deploy to .github-private Repository - -1. **Add your .github-private repository as a remote**: - ```bash - git remote add enterprise https://github.com/YOUR-ORG-SLUG/.github-private.git - ``` - -2. **Push to your .github-private repository**: - ```bash - git push enterprise main - ``` - - This deploys the entire repository structure: - - `agents/` β†’ `.github-private/agents/` - - `knowledge/` β†’ `.github-private/knowledge/` - - `docs/` β†’ `.github-private/docs/` - - `.github/` β†’ `.github-private/.github/` - - `README.md` β†’ `.github-private/README.md` - -3. **Verify deployment** on GitHub: - - Navigate to `https://github.com/YOUR-ORG-SLUG/.github-private` - - Confirm directory structure. - - Check that agent files contain your organization slug (not `{MY_ORGANIZATION}`) - -### Step 5: Configure Repository Variables and Secrets - -The automation workflows require GitHub App credentials and a Personal Access Token for cross-organization operations. - -#### 5.1 Create GitHub App for Automation Workflows - -1. **Navigate to GitHub App creation**: - - Go to your organization settings: `https://github.com/organizations/YOUR-ORG-SLUG/settings/apps` - - Click **"New GitHub App"** - -2. **Configure GitHub App settings**: - - **GitHub App name**: `CI/CD Migration Automation` (or your preferred name) - - **Homepage URL**: `https://github.com/YOUR-ORG-SLUG/.github-private` - - **Webhook**: Uncheck "Active" (not needed for this app) - -3. **Set Repository permissions**: - - **Contents**: Read and write - - **Custom properties**: Read and write - - **Issues**: Read and write - - **Pull requests**: Read and write - - **Workflows**: Read and write - - **Metadata**: Read-only (automatically selected) - -4. **Set Organization permissions**: - - **Members**: Read-only (for accessing organization repositories) - - **Custom properties**: Read-only - -5. **Configure "Where can this GitHub App be installed?"**: - - Select **"This enterprise"** (allows installation by any organization in your enterprise) - -6. **Create the app**: - - Click **"Create GitHub App"** - - Note the **App ID** displayed on the app's page - -7. **Generate private key**: - - Scroll to **"Private keys"** section - - Click **"Generate a private key"** - - A `.pem` file will download automatically - save this securely - -8. **Install the app in your organizations**: - - Click **"Install App"** in the left sidebar - - For each organization that will use the migration tools: - - Click **"Install"** next to the organization name - - Select **"All repositories"** or choose specific repositories - - Click **"Install"** - - Repeat for all target organizations (including the organization hosting `.github-private`) - -9. **Authorize the app** (if using multiple organizations): - - Navigate to each organization's settings - - Go to **"GitHub Apps"** β†’ **"Installed GitHub Apps"** - - Confirm the app appears with appropriate permissions - -#### 5.2 Create Personal Access Token - -1. **Generate a Classic Personal Access Token**: - - Navigate to **Settings** β†’ **Developer settings** β†’ **Personal access tokens** β†’ **Tokens (classic)** - - Click **"Generate new token (classic)"** - - Token name: `Migration Automation - Issue Submission & MCP Access` - - Scopes required: - - `repo` (Full control of private repositories) - - `admin:org` (Full control of organization settings - required for settings.yml workflow) - - Expiration: Set according to your organization's policy - - Click **"Generate token"** and copy the token value - -2. **Configure SSO authorization** (if applicable): - - Click **"Configure SSO"** next to the token - - Authorize for all organizations the tool will interact with - - Click **"Authorize"** for each organization - -#### 5.3 Add Secrets to .github-private Repository - -1. **Navigate to repository secrets**: - - Go to `https://github.com/YOUR-ORG-SLUG/.github-private/settings/secrets/actions` - - Click **"New repository secret"** - -2. **Add GitHub App private key**: - - Name: `GH_APP_PEM` - - Value: Paste the entire contents of the `.pem` file you downloaded (including `-----BEGIN RSA PRIVATE KEY-----` and `-----END RSA PRIVATE KEY-----` lines) - - Click **"Add secret"** - -3. **Add Personal Access Token**: - - Click **"New repository secret"** - - Name: `ISSUE_SUBMIT_TOKEN` - - Value: Paste the PAT you generated - - Click **"Add secret"** - -#### 5.4 Update Configuration File - -1. **Edit the configuration file** in your local clone: - ```bash - cd actions-migrations-via-copilot - nano .github/settings/config.yaml # or use your preferred editor - ``` - -2. **Update the following values**: - ```yaml - # GitHub App Configuration - gh_app_id: '123456' # Replace with your GitHub App ID from step 5.1.6 - - # Custom Properties Configuration - gh_migration_type: - default_value: 'Jenkins' # Set your default migration type - description: 'The type of migration for this repository. This is used to track the migration status.' - other_values: - - 'Jenkins' - - 'Azure DevOps' - - 'CircleCI' - - 'GitLab' - - 'Travis CI' - - 'Bamboo' - - 'Bitbucket' - - 'DroneCI' - - # Migration Type Prompts - migration_type_prompts: - 'Jenkins': 'jenkins-migrator.md' - 'Azure DevOps': 'azure-devops-migrator.md' - 'CircleCI': 'circleci-migrator.md' - 'GitLab': 'gitlab-migrator.md' - 'Travis CI': 'travisci-migrator.md' - 'Bamboo': 'bamboo-migrator.md' - 'Bitbucket': 'bitbucket-migrator.md' - 'DroneCI': 'droneci-migrator.md' - - # Organizations - organizations: - - 'YOUR-ORG-SLUG' # Add all organizations the tool will interact with - - # Batch Size - batch_size: 100 # Adjust based on your needs - ``` - -3. **Save and commit changes**: - ```bash - git add .github/settings/config.yaml - git commit -m "Configure automation settings for organization" - git push enterprise main - ``` - -#### 5.5 Run Settings Workflow to Initialize Repository Variables - -The `settings.yml` workflow reads your `config.yaml` file and creates all necessary repository variables automatically. - -1. **Navigate to Actions in .github-private repository**: - - Go to `https://github.com/YOUR-ORG-SLUG/.github-private/actions` - - Click on **"Configuration Settings"** workflow in the left sidebar - -2. **Run the workflow manually**: - - Click **"Run workflow"** button (top right) - - Select branch: `main` - - Click **"Run workflow"** to confirm - -3. **Monitor workflow execution**: - - Click on the running workflow to view logs - - Verify successful completion (green checkmark) - -4. **Verify repository variables were created**: - - Navigate to `https://github.com/YOUR-ORG-SLUG/.github-private/settings/variables/actions` - - Confirm the following variables exist (populated from `config.yaml`): - - `GH_APP_ID` - - `GH_MIGRATION_TYPE_DEFAULT` - - `GH_MIGRATION_TYPE_DESCRIPTION` - - `ORGANIZATIONS` - - `BATCH_SIZE` - - Additional migration type mappings - -> **Note**: The `ISSUE_SUBMIT_TOKEN` secret must have `admin:org` scope to create repository variables. This was configured in step 5.2. - -#### 5.6 Verify Configuration - -After completing the configuration steps, verify everything is working correctly by running a test migration. Pick a few repositories from one of your configured organizations to test with. See the [**Operations Guide**](operations.md) for detailed instructions on how to initiate and test the migration tool. - -### Step 6: Configure Enterprise Copilot Settings - -Enable custom agents for your enterprise organization. - -1. **Navigate to Enterprise settings**: - - Click your profile photo β†’ **Your enterprises** - - Select your enterprise - - Click **AI controls** +Verify at `https://github.com/YOUR-ORG-SLUG/.github-private` -2. **Enable custom agents**: - - Scroll to **"Custom agents"** section - - Select the Select organization dropdown menu, then click the organization that contains your `.github-private` repository. - - Confirm your migration agents appear in the list: - - Jenkins to GitHub Actions Migration Agent - - Azure DevOps Migrator - - CircleCI Migrator - - GitLab Migrator - - Travis CI Migrator - - Bamboo Migrator - - Bitbucket Migrator - - Drone CI Migrator - - Reusable Workflow Builder +## Step 3: Configure Repository Settings -## Post-Deployment Configuration +### Create GitHub App (for automation workflows) -### Update Knowledgebase +1. **Create app** at `https://github.com/organizations/YOUR-ORG-SLUG/settings/apps`: + - Name: `CI/CD Migration Automation` + - Webhook: Inactive + - Repository permissions: Contents (R/W), Issues (R/W), Pull requests (R/W), Workflows (R/W) + - Organization permissions: Members (Read), Custom properties (Read) + - Where to install: "This enterprise" -As GitHub Actions evolves, update the knowledgebase to reflect new features: +2. **Generate private key** and save the `.pem` file -1. **Navigate to your .github-private repository** -2. **Edit knowledgebase files** in `knowledge/`: - - `actions-mapping/*.md` - Add new action equivalents - - `patterns/**/*.md` - Document new migration patterns - - `migration-standards.md` - Update quality standards +3. **Install app** in your organizations (select "All repositories") -3. **Commit and push changes**: - ```bash - git add knowledge/ - git commit -m "Update knowledgebase with new patterns" - git push - ``` +4. **Note the App ID** from the app settings page -Agents automatically reference the latest knowledgebase content on each invocation. +### Create Personal Access Token -### Maintain Agent Definitions +Generate a Classic PAT with: +- Scopes: `repo`, `admin:org` +- SSO authorization: Enable for all organizations +- Expiration: Per your organization policy -As new capabilities are needed, update agent definitions: +### Add Secrets -1. **Edit agent files** in `agents/` directory -2. **Update instructions** to reflect new features or improved patterns -3. **Test changes** by invoking the updated agent -4. **Commit and push** to `.github-private` repository +Navigate to `https://github.com/YOUR-ORG-SLUG/.github-private/settings/secrets/actions`: -Changes take effect immediately for all users. +| Secret Name | Value | +| -------------------- | ------------------------------------------------- | +| `GH_APP_PEM` | Contents of `.pem` file (include BEGIN/END lines) | +| `ISSUE_SUBMIT_TOKEN` | PAT value | -### Monitor Agent Usage +### Configure Settings -Track agent adoption across your enterprise: +Edit `.github/settings/config.yaml`: -1. **Review agent activity** in Copilot usage reports -2. **Collect feedback** from teams using migration agents -3. **Identify common issues** or enhancement requests -4. **Update knowledgebase** based on real-world migration patterns +```yaml +gh_app_id: '123456' # Your GitHub App ID -## Security Considerations +gh_migration_type: + default_value: 'Jenkins' + description: 'The type of migration for this repository' + other_values: + - 'Jenkins' + - 'Azure DevOps' + - 'CircleCI' + - 'GitLab' + - 'Travis CI' + - 'Bamboo' + - 'Bitbucket' + - 'DroneCI' -### Repository Access +organizations: + - 'YOUR-ORG-SLUG' -- **Internal visibility required**: Agents need read access to knowledgebase -- **Do not make .github-private public**: Contains enterprise-specific guidance -- **Review access logs**: Monitor who can access `.github-private` repository +batch_size: 100 +``` -### PAT Management (Reusable Workflow Builder) +Commit and push: -- **Rotate PATs regularly**: Follow your organization's token rotation policy -- **Use least-privilege scope**: Grant only `repo` scope for read access -- **Monitor PAT usage**: Review audit logs for unexpected access patterns -- **Revoke immediately if compromised**: Disable and regenerate if suspicious activity detected +```bash +git add .github/settings/config.yaml +git commit -m "Configure automation settings" +git push enterprise main +``` -### Secrets in Migrations +### Bootstrap Repository Variables -- **Review migration reports**: Check how credentials are handled in conversions -- **Validate GitHub Secrets**: Ensure sensitive values are properly stored -- **Update access controls**: Configure environment protection rules for workflows +Run the Settings workflow to create variables from config: -## Troubleshooting +1. Go to `https://github.com/YOUR-ORG-SLUG/.github-private/actions` +2. Click **"Configuration Settings"** workflow +3. Click **"Run workflow"** β†’ Select `main` β†’ **"Run workflow"** +4. Verify success (green checkmark) +5. Check variables at `https://github.com/YOUR-ORG-SLUG/.github-private/settings/variables/actions` -### Agent Not Appearing in Copilot +Expected variables: `GH_APP_ID`, `GH_MIGRATION_TYPE_DEFAULT`, `ORGANIZATIONS`, `BATCH_SIZE` -**Symptom**: Migration agents don't appear at [github.com/copilot/agents](https://github.com/copilot/agents) +## Step 4: Enable Agents in Enterprise Settings -**Solutions**: -1. Verify `.github-private` repository exists in configured organization -2. Check enterprise Copilot settings include the organization -3. Confirm agent `.md` files exist in `agents/` directory -4. Wait 5-10 minutes for agent registration to propagate +1. **Navigate to Enterprise AI controls**: + - Click profile photo β†’ Your enterprises β†’ [Your Enterprise] + - Click **AI controls** -### Agent Cannot Access Knowledgebase +2. **Enable custom agents**: + - Find **"Custom agents"** section + - Select your organization from dropdown + - Verify agents appear: + - Jenkins Migrator + - Azure DevOps Migrator + - CircleCI Migrator + - GitLab Migrator + - Travis CI Migrator + - Bamboo Migrator + - Bitbucket Migrator + - Drone CI Migrator + - Reusable Workflow Builder + +3. **Wait 5-10 minutes** for agent registration to propagate -**Symptom**: Agent responds with "Cannot access knowledgebase" or similar error +## Step 5: Test Your Deployment -**Solutions**: -1. Verify `.github-private` repository visibility is **Internal** (not Private) -2. Check organization slug in agent files matches your actual organization -3. Confirm `knowledge/` directory exists in `.github-private` repository -4. Test MCP access manually using GitHub API +1. Navigate to [github.com/copilot/agents](https://github.com/copilot/agents) +2. Verify your migration agents appear +3. Open a test repository with CI/CD configuration +4. Invoke an agent through Copilot Chat +5. Verify agent can access knowledgebase -### Reusable Workflow Builder Cannot Scan Organizations +## Maintaining Your Deployment -**Symptom**: Agent reports "Access denied" or "Cannot list repositories" +### Update Agents -**Solutions**: -1. Verify `COPILOT_MCP_GITHUB_PERSONAL_ACCESS_TOKEN` secret exists -2. Check PAT has `repo` scope enabled -3. Ensure PAT has SSO authorization for target organizations -4. Confirm PAT has not expired +When adding new agents (see [extending.md](extending.md)): -### Migration Validation Fails +1. Add agent file to `agents/` directory +2. Create knowledgebase files in `knowledge/` +3. Update organization references +4. Commit and push to `.github-private` -**Symptom**: Generated workflows contain errors or don't pass validation +```bash +# After adding new agent +git add agents/ knowledge/ +git commit -m "Add migration agent" +git push enterprise main +``` -**Solutions**: -1. Review `MIGRATION-README.md` for specific validation errors -2. Check that source CI/CD files are valid and complete -3. Update knowledgebase with missing action mappings +Changes are live immediately. -### Organization Slug Mismatch +### Update Knowledgebase -**Symptom**: Agent references `{MY_ORGANIZATION}` instead of your organization +Update mappings and patterns as Actions evolves: -**Solutions**: -1. Re-run the `sed` command from Step 3 to replace placeholders -2. Manually edit agent files in `.github-private` repository -3. Commit and push updated agent definitions -4. Verify changes by viewing files on GitHub.com +```bash +# Edit files in knowledge/ +nano knowledge/actions-mapping/jenkins.md -## Next Steps +# Commit and push +git add knowledge/ +git commit -m "Update action mappings" +git push enterprise main +``` -Once deployment is complete: +Agents automatically use latest knowledgebase content. -1. **Review the [Operations Guide](operations.md)** for instructions on using migration agents -2. **Train your teams** on invoking agents for CI/CD migrations -3. **Establish migration workflows** for systematic pipeline conversions -4. **Monitor and iterate** based on migration results and user feedback +### Monitor Usage + +- Review Copilot usage reports in Enterprise settings +- Collect feedback from migration teams +- Update knowledgebase based on real-world patterns +- Refine agents based on common issues + +## Troubleshooting + +| Issue | Solution | +| ----------------------------------------------------- | ------------------------------------------------------------------------------ | +| **Agents not appearing** | Verify `.github-private` exists, wait 10 minutes, check Enterprise AI settings | +| **Cannot access knowledgebase** | Ensure repository visibility is **Internal**, verify org slug in agent files | +| **Organization slug still shows `{MY_ORGANIZATION}`** | Re-run `sed` command or manually edit agent files | +| **Validation errors in migrations** | Review migration report, update knowledgebase mappings | + +## Security Best Practices + +- Keep `.github-private` Internal visibility (never Public) +- Review repository access regularly +- Monitor agent usage in audit logs +- Validate GitHub Secrets configuration in migrated workflows +- Use environment protection rules for sensitive workflows + +## Next Steps -For operational procedures, see [**Operations Guide β†’**](operations.md) +- **[Operations Guide](operations.md)** - Learn how to use migration agents +- **[Extending Guide](extending.md)** - Add support for new CI/CD platforms +- Train teams on agent invocation +- Establish migration workflows +- Monitor and iterate based on feedback diff --git a/docs/extending.md b/docs/extending.md new file mode 100644 index 0000000..484f084 --- /dev/null +++ b/docs/extending.md @@ -0,0 +1,159 @@ +# Extending the Project + +Add support for new CI/CD platforms by creating migration agents and knowledgebase content. + +## Quick Reference + +| Task | Files to Create | +| --------------------- | ------------------------------------------------------------- | +| **New Agent** | `agents/-migrator.md` | +| **Action Mappings** | `knowledge/actions-mapping/.md` | +| **Security Patterns** | `knowledge/patterns//secrets.md` | +| **Report Template** | `knowledge/report-template/.md` | +| **Optional Patterns** | `knowledge/patterns//{pipeline,plugins,scripts}.md` | + +## Adding a New Migration Agent + +### 1. Create Agent File + +**Location:** `agents/-migrator.md` + +**Required sections:** +- YAML frontmatter (name, description) +- Knowledge base references +- Platform expertise +- Migration process (5 phases) +- Key conversions +- Security requirements + +**Template:** Copy `agents/jenkins-migrator.md` and adapt for your platform. + +### 2. Create Knowledgebase Files + +**Required:** +- `knowledge/actions-mapping/.md` - Command/task β†’ Actions mappings +- `knowledge/patterns//secrets.md` - Credential migration patterns +- `knowledge/report-template/.md` - Migration report structure + +**Optional (create if needed):** +- `knowledge/patterns//pipeline.md` - Complex pipeline patterns +- `knowledge/patterns//plugins.md` - Plugin conversions +- `knowledge/patterns//scripts.md` - Script conversion patterns + +### 3. Update Documentation + +Add your agent to: +- `README.md` - Available Migration Agents table +- `docs/operations.md` - Usage instructions + +## Knowledgebase File Templates + +### Action Mappings (`knowledge/actions-mapping/.md`) + +Maps platform syntax to GitHub Actions equivalents. + +**Include:** +- Pipeline structure comparison +- Common command/task mappings (use tables) +- Trigger/event mappings +- Environment variable handling +- Basic secret patterns + +**Example:** `knowledge/actions-mapping/jenkins.md` + +### Security Patterns (`knowledge/patterns//secrets.md`) + +Documents credential migration. + +**Include:** +- Secret types in source platform +- GitHub Actions equivalents table +- Migration steps +- Security best practices +- Examples + +**Example:** `knowledge/patterns/jenkins/secrets.md` + +### Report Template (`knowledge/report-template/.md`) + +Defines migration report structure. + +**Include:** +- Migration summary +- Source analysis +- Conversion details +- Validation results +- Next steps + +**Example:** `knowledge/report-template/jenkins.md` + +### Optional Pattern Files + +Create when patterns are too complex for action mappings: + +| File | Purpose | When to Create | +| ------------------ | -------------------------------------------------------- | ------------------------------ | +| `pipeline.md` | Multi-stage pipelines, matrix builds, parallel execution | Complex pipeline structures | +| `plugins.md` | Plugin/extension conversions | Many platform-specific plugins | +| `scripts.md` | Inline scripts, script files | Custom scripting language | +| `notifications.md` | Slack, email, webhooks | Complex notification setup | +| `environment.md` | Environment variables, config files | Complex env configuration | + +**Keep patterns focused:** One pattern type per file. Reference Jenkins patterns for examples. + +## Testing Your Changes + +1. **Local validation** + - Verify file structure matches existing agents + - Check markdown and YAML syntax + - Confirm all knowledgebase file paths exist + +2. **Deploy to `.github-private`** + - Push changes to your organization's `.github-private` repository + - Verify repository visibility is **Internal** + +3. **Test migration** + - Create test repo with sample CI/CD config + - Invoke agent from test repo + - Verify deliverables: + - Workflows in `.github/workflows/` + - Archives in `.github/ci-archive/` + - Migration report with actionlint results + +4. **Iterate** + - Document issues + - Update knowledgebase patterns + - Refine agent instructions + - Re-test + +## Best Practices + +**Agent Design:** +- Follow the 5-phase migration workflow +- Reference knowledgebase (don't hardcode mappings) +- Include validation requirements +- Document all deliverables + +**Knowledgebase:** +- Use tables for mappings +- Show before/after examples +- Document edge cases +- Keep security patterns detailed +- Don't duplicate content (cross-reference instead) + +**Documentation:** +- Update README.md with new agent +- Add usage guide to operations.md +- Keep examples real-world and focused + +## Getting Help + +- **Questions?** [Discussions](https://github.com/github/actions-migrations-via-copilot/discussions) +- **Issues?** [Open an issue](https://github.com/github/actions-migrations-via-copilot/issues/new/choose) +- **Review?** Open a draft PR + +## Related Docs + +- [CONTRIBUTING.md](../CONTRIBUTING.md) - Contribution guidelines +- [deployment.md](deployment.md) - Deploy agents +- [operations.md](operations.md) - Use agents diff --git a/docs/operations.md b/docs/operations.md index 91fc541..32ae892 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -1,218 +1,134 @@ # Operations Guide -This guide provides instructions for using CI/CD Migration Custom Agents to migrate repositories to GitHub Actions. +How to use migration agents to convert CI/CD pipelines to GitHub Actions. -> **πŸ“– New to this project?** Start with the [README](../README.md) for an overview, then follow the [Deployment Guide](deployment.md) to set up agents in your enterprise. +## Quick Reference -## Migration Methods +| Method | Use For | How | +| ---------- | ------------------------- | ------------------------------------------------------------------------------- | +| **Manual** | Individual repos, testing | Invoke agent via [github.com/copilot/agents](https://github.com/copilot/agents) | +| **Batch** | Multiple repos, scale | Run Submit Repositories workflow in `.github-private` | -There are two ways to invoke migration agents: +## Manual Migration -1. **[Manual UI Invocation](#manual-ui-invocation)** - Migrate individual repositories through the GitHub Copilot interface -2. **[Automated Batch Migration](#automated-batch-migration)** - Migrate multiple repositories using the submit-repo workflow +### 1. Prepare Repository -## Manual UI Invocation - -Use this method to migrate individual repositories with full control over the migration process. - -### Step 1: Access the Agents Interface - -1. **Navigate to GitHub Copilot agents**: - ``` - https://github.com/copilot/agents - ``` - -2. **Select your repository context**: - - **Repository**: Choose the repository containing your CI/CD files - - **Branch**: Select the branch where migration should occur (create a feature branch first) - - **Agent**: Choose the appropriate migration agent: - - Jenkins to GitHub Actions Migration Agent - - Azure DevOps Migrator - - CircleCI Migrator - - GitLab Migrator - - Travis CI Migrator - - Bamboo Migrator - - Bitbucket Migrator - - Drone CI Migrator +Create a feature branch: +```bash +git checkout -b migrate/to-actions +git push -u origin migrate/to-actions +``` -### Step 2: Prepare Your Migration Request +### 2. Invoke Agent -Compose a clear migration request that includes: +1. Go to [github.com/copilot/agents](https://github.com/copilot/agents) +2. Select your repository and branch +3. Choose the appropriate migration agent: + - Jenkins Migrator + - Azure DevOps Migrator + - CircleCI Migrator + - GitLab Migrator + - Travis CI Migrator + - Bamboo Migrator + - Bitbucket Migrator + - Drone CI Migrator -- **What to migrate**: List all CI/CD configuration files -- **Special requirements**: Mention shared libraries, templates, or dependencies -- **Context**: Note any custom requirements (specific actions, deployment targets) +4. Provide clear instructions: -**Example for Jenkins**: +**Example:** ``` -Please migrate our Jenkins pipelines to GitHub Actions. +Migrate our Jenkins pipeline to GitHub Actions. -Files to migrate: -- Jenkinsfile (declarative pipeline for main build) -- deploy/Jenkinsfile (deployment pipeline) +Files: +- Jenkinsfile (main build) +- deploy/Jenkinsfile (deployment) - vars/buildDocker.groovy (shared library) -- vars/deployApp.groovy (shared library) -We use the following Jenkins plugins: -- Docker Pipeline -- Kubernetes -- AWS Steps +We use Docker, Kubernetes, and AWS plugins. ``` -**Example for Azure DevOps**: -``` -Please migrate our Azure DevOps pipelines to GitHub Actions. - -Files to migrate: -- azure-pipelines.yml (main build pipeline) -- pipelines/deploy-prod.yml (production deployment) -- templates/build-dotnet.yml (template) -- templates/deploy-azure.yml (template) - -We use Azure App Service and Azure Key Vault. -``` - -### Step 3: Review Migration Output - -After the agent completes, review the generated files: - -1. **Workflows**: Check `.github/workflows/` for converted workflows -2. **Archive**: Review `.github/ci-archive/` for original configuration backups -3. **Migration Report**: Read `.github/ci-archive/MIGRATION-README.md` for: - - Validation results - - Required secrets - - Known limitations - - Testing recommendations +### 3. Review Output -### Step 4: Configure Secrets +Check generated files: +- **Workflows**: `.github/workflows/*.yml` +- **Archive**: `.github/ci-archive/` (original files preserved) +- **Report**: `.github/ci-archive/MIGRATION-README.md` (validation, secrets, next steps) -Add any required secrets to your repository: +### 4. Configure Secrets -1. Navigate to **Settings** β†’ **Secrets and variables** β†’ **Actions** -2. Add secrets referenced in the migrated workflows -3. Refer to the migration report for required secret names +Add secrets to repository settings: +1. Go to **Settings** β†’ **Secrets and variables** β†’ **Actions** +2. Add secrets listed in migration report -### Step 5: Test and Validate +### 5. Test and Merge -1. **Commit the changes**: - ```bash - git add .github/ - git commit -m "Migrate CI/CD to GitHub Actions" - git push - ``` - -2. **Monitor workflow runs** in the **Actions** tab - -3. **Verify all jobs complete successfully** - -4. **Create a pull request** and request team review +```bash +git add .github/ +git commit -m "Migrate to GitHub Actions" +git push +``` -5. **Merge when validated** +Monitor workflow runs, create PR, and merge when validated. -## Automated Batch Migration +## Batch Migration -Use the `submit-repo` workflow to migrate multiple repositories across your organization automatically. +Automate migrations across multiple repositories using custom properties. ### How It Works -The batch migration system uses **custom properties** to track and control migrations. Because there is no API to send a prompt to a custom agent directly, we use issues as prompts for Copilot to process: - -1. **Custom Property**: `GH_MIGRATION_TYPE` is set on each repository to indicate the CI/CD platform type -2. **Workflow Scan**: The `submit-repo` workflow scans your organization for repositories with the custom property -3. **Issue Prompt**: For each repository, the workflow creates a new issue using the appropriate custom migration agent markdown file, based on the custom property value -4. **Copilot Assignment**: The workflow assigns the issue to Copilot for processing. Copilot uses the issue as its prompt to perform the migration -5. **Batch Processing**: Repositories are processed in batches (configurable batch size) +1. Set `GH_MIGRATION_TYPE` custom property on repositories +2. Run "Submit Repositories for Migration" workflow +3. Workflow creates issues assigned to Copilot with agent prompts +4. Copilot processes migrations using the appropriate agent -### Custom Property Values +### Supported Migration Types -The `GH_MIGRATION_TYPE` property can be set to: +Set `GH_MIGRATION_TYPE` to: `Jenkins`, `Azure DevOps`, `CircleCI`, `GitLab`, `Travis CI`, `Bamboo`, `Bitbucket`, or `DroneCI` -- `Jenkins` -- `Azure DevOps` -- `CircleCI` -- `GitLab` -- `Travis CI` -- `Bamboo` -- `Bitbucket` -- `DroneCI` +### Set Custom Properties -Each value maps to a specific migration agent (configured in `.github/settings/config.yaml`). - -### Step 1: Set Custom Properties on Repositories - -Each repository in your organization has been configured with a custom property named `GH_MIGRATION_TYPE`, with the value set to the `default_value` specified in the configuration file. For each repository that uses a different CI/CD system, you need to update the `GH_MIGRATION_TYPE` custom property to the appropriate value. - -**Using GitHub CLI**: +**Using GitHub CLI:** ```bash -# Set custom property for a single repository -gh api \ - --method PUT \ +# Single repository +gh api --method PUT \ -H "Accept: application/vnd.github+json" \ /repos/YOUR-ORG/REPO-NAME/properties/values \ -f properties[GH_MIGRATION_TYPE]=Jenkins -# Set for multiple repositories +# Multiple repositories for repo in repo1 repo2 repo3; do - gh api \ - --method PUT \ + gh api --method PUT \ -H "Accept: application/vnd.github+json" \ /repos/YOUR-ORG/$repo/properties/values \ -f properties[GH_MIGRATION_TYPE]=Jenkins done ``` -**Using GitHub UI** (if available in your organization): -1. Navigate to the repository -2. Go to **Settings** β†’ **Custom properties** -3. Set `GH_MIGRATION_TYPE` to the appropriate CI/CD platform - -### Step 2: Trigger the Submit-Repo Workflow - -1. **Navigate to your .github-private repository**: - ``` - https://github.com/YOUR-ORG/.github-private/actions - ``` - -2. **Select the "Submit Repositories for Migration" workflow** +### Run Migration Workflow -3. **Click "Run workflow"**: - - **Branch**: Select `main` - - Click **"Run workflow"** +1. Go to `https://github.com/YOUR-ORG/.github-private/actions` +2. Select **"Submit Repositories for Migration"** +3. Click **"Run workflow"** β†’ Select `main` β†’ **"Run workflow"** -### Step 3: Monitor Workflow Execution +### Monitor Progress -1. **View workflow progress** in the Actions tab - -2. **Check logs** to see which repositories are being processed: - ``` - Found 15 repositories with GH_MIGRATION_TYPE property - Processing batch 1 of 1 (15 repositories) - - Assigning jenkins-migrator to repo: frontend-app - - Assigning jenkins-migrator to repo: api-service - - Assigning circleci-migrator to repo: mobile-app - ... - ``` - -3. **Verify agent assignments** for each repository in the logs - -### Step 4: Review Migration Results - -For each repository that was processed: +Check workflow logs to see repositories being processed: +``` +Found 15 repositories with GH_MIGRATION_TYPE property +Processing batch 1 of 1 (15 repositories) +- Assigning jenkins-migrator to repo: frontend-app +- Assigning circleci-migrator to repo: mobile-app +``` -1. **Check for pull requests** created by the migration agent -2. **Review the migration report** in `.github/ci-archive/MIGRATION-README.md` -3. **Test the migrated workflows** in the pull request branch -4. **Merge successful migrations** +Review migration results in each repository's pull requests. ### Configuration -The batch migration behavior is controlled by `.github/settings/config.yaml`: +Edit `.github/settings/config.yaml` in `.github-private`: ```yaml -# Custom Properties Configuration gh_migration_type: - default_value: 'Jenkins' # Default if property not set - description: 'The type of migration for this repository' + default_value: 'Jenkins' other_values: - 'Jenkins' - 'Azure DevOps' @@ -223,305 +139,48 @@ gh_migration_type: - 'Bitbucket' - 'DroneCI' -# Migration Type Prompts -migration_type_prompts: - 'Jenkins': 'jenkins-migrator.md' - 'Azure DevOps': 'azure-devops-migrator.md' - 'CircleCI': 'circleci-migrator.md' - 'GitLab': 'gitlab-migrator.md' - 'Travis CI': 'travisci-migrator.md' - 'Bamboo': 'bamboo-migrator.md' - 'Bitbucket': 'bitbucket-migrator.md' - 'DroneCI': 'droneci-migrator.md' - -# Organizations to scan organizations: - 'your-org-name' -# Batch Size batch_size: 100 ``` ## Troubleshooting -### Custom Property Not Set - -**Symptom**: Repository not picked up by submit-repo workflow - -**Solution**: Verify the `GH_MIGRATION_TYPE` property is set: -```bash -gh api /repos/YOUR-ORG/REPO-NAME/properties/values -``` - -### Wrong Agent Assigned - -**Symptom**: Incorrect migration agent used for repository - -**Solution**: -1. Check the custom property value matches config.yaml -2. Verify `migration_type_prompts` mapping in config.yaml -3. Update the property and re-run the workflow - -### Workflow Fails After Migration - -**Symptom**: Migrated workflow fails in GitHub Actions - -**Solution**: -1. Review workflow run logs -2. Check migration report for required secrets -3. Verify all secrets are configured in repository settings -4. Test locally using `actionlint` if available - -### Agent Cannot Access Source Files - -**Symptom**: Agent reports "Cannot find file" errors - -**Solution**: -1. Verify CI/CD files exist in the repository -2. Ensure files are on the correct branch -3. Check file paths are correct (case-sensitive) - -## Getting Help - -### Resources - -- **Migration Reports**: Check `.github/ci-archive/MIGRATION-README.md` in each repository -- **Knowledgebase**: Review `.github-private/knowledge/` for migration standards -- **GitHub Actions Docs**: [docs.github.com/actions](https://docs.github.com/actions) - -### Support Channels - -1. **Internal Team**: Consult with teams who have completed migrations -2. **GitHub Support**: Contact your Enterprise support team -3. **Agent Updates**: Submit feedback to improve agent capabilities +| Issue | Solution | +| ---------------------------------------------- | -------------------------------------------------------------------------------------- | +| **Repository not picked up by batch workflow** | Verify `GH_MIGRATION_TYPE` property is set: `gh api /repos/ORG/REPO/properties/values` | +| **Wrong agent assigned** | Check property value matches config.yaml mappings | +| **Workflow fails after migration** | Review migration report for required secrets, check workflow logs | +| **Agent can't access source files** | Verify files exist on correct branch, check file paths (case-sensitive) | +| **Missing validation results** | Re-run migration with explicit validation request | -## Next Steps +## Best Practices -- **Start with pilot migrations**: Test with 2-3 repositories using manual UI invocation -- **Scale with automation**: Use batch migration for larger rollouts -- **Iterate and improve**: Refine your process based on results -- **Maintain and evolve**: Keep knowledgebase updated as Actions ecosystem grows - -For deployment and setup instructions, see [**Deployment Guide β†’**](deployment.md) +**Before migration:** +- Create feature branch +- Document current CI/CD state +- List all credentials and dependencies +**During migration:** +- Review agent output thoroughly +- Read migration report carefully +- Test in feature branch first -### Pre-Migration Checklist - -- [ ] Identify all Jenkinsfiles (declarative and scripted) -- [ ] Locate shared library files in `vars/` directory -- [ ] Document Jenkins plugins currently in use -- [ ] List credential IDs used in pipelines -- [ ] Note any custom agents or Docker images -- [ ] Create migration feature branch - -### Migration Steps - -1. **Prepare Repository**: - ```bash - git checkout -b migrate/jenkins-to-actions - git push -u origin migrate/jenkins-to-actions - ``` - -2. **Invoke Jenkins Migrator**: - - Go to [github.com/copilot/agents](https://github.com/copilot/agents) - - Select your repository and `migrate/jenkins-to-actions` branch - - Choose **"Jenkins to GitHub Actions Migration Agent"** - - Provide migration request: - ``` - Please migrate our Jenkins pipelines to GitHub Actions. - - Files to migrate: - - Jenkinsfile (declarative pipeline for main build) - - deploy/Jenkinsfile (deployment pipeline) - - vars/buildDocker.groovy (shared library) - - vars/deployApp.groovy (shared library) - - We use the following Jenkins plugins: - - Docker Pipeline - - Kubernetes - - AWS Steps - ``` - -3. **Review Agent Output**: - - Check `.github/workflows/` for generated workflows - - Review `.github/ci-archive/` for archived Jenkins files - - Read `.github/ci-archive/MIGRATION-README.md` thoroughly - -4. **Validate Workflows**: - ```bash - # Install actionlint - brew install actionlint # macOS - - # Lint workflows - actionlint .github/workflows/*.yml - ``` - -5. **Configure Secrets**: - - Navigate to repository **Settings** β†’ **Secrets and variables** β†’ **Actions** - - Add secrets referenced in migrated workflows - - Refer to `MIGRATION-README.md` for required secret names - -7. **Test in Feature Branch**: - - Commit changes: `git commit -am "Migrate Jenkins to GitHub Actions"` - - Push: `git push` - - Monitor workflow runs in **Actions** tab - - Verify all jobs complete successfully - -8. **Review and Merge**: - - Create pull request from `migrate/jenkins-to-actions` to `main` - - Request team review - - Address any issues or feedback - - Merge when approved - -## Maintenance and Monitoring - -### Updating the Knowledgebase - -As GitHub Actions evolves, keep the knowledgebase current: - -1. **Monitor GitHub Actions updates**: - - Subscribe to [GitHub Changelog](https://github.blog/changelog/) - - Watch for new actions and features - - Track deprecations and breaking changes - -2. **Update action mappings**: - ```bash - # Navigate to .github-private repository - cd .github-private - - # Edit mapping files - vim docs/actions-mapping/jenkins.md # Add new plugin mappings - - # Commit and push - git add docs/actions-mapping/ - git commit -m "Update Jenkins plugin mappings" - git push - ``` - -3. **Document new patterns**: - - Add successful migration patterns to `docs/patterns/` - - Update best practices based on real-world migrations - - Share learnings across teams - -### Monitoring Migration Success - -Track migration outcomes to improve process: - -1. **Collect metrics**: - - Migration completion rate - - Workflow execution success rate - - Build time comparisons (before/after) - - Cost comparisons (old CI vs GitHub Actions) - -2. **Gather feedback**: - - Survey teams after migrations - - Document common issues and solutions - - Identify knowledgebase gaps - -3. **Iterate on process**: - - Update operations playbooks - - Refine agent instructions - - Improve validation steps - -### Troubleshooting Common Issues - -#### Workflow Fails After Migration - -**Symptoms**: Migrated workflow fails in GitHub Actions - -**Diagnosis Steps**: -1. Review workflow run logs in GitHub Actions UI -2. Check migration report (`.github/ci-archive/MIGRATION-README.md`) -3. Compare original CI/CD file with generated workflow -4. Verify all secrets are configured - -**Common Fixes**: -- Add missing secrets to repository settings -- Update action versions to latest -- Fix YAML syntax errors flagged by actionlint -- Adjust runner labels (`runs-on`) for environment requirements - -#### Agent Cannot Access Source Files - -**Symptoms**: Agent reports "Cannot find file" or "Access denied" - -**Diagnosis Steps**: -1. Verify files exist in selected branch -2. Check file paths are correct (case-sensitive) -3. Confirm repository permissions - -**Common Fixes**: -- Push files to branch before invoking agent -- Use correct file paths in migration request -- Verify agent has repository access - -#### Migration Report Missing Validation Results - -**Symptoms**: `MIGRATION-README.md` lacks actionlint output - -**Diagnosis Steps**: -1. Check if validation tools ran successfully -2. Review agent conversation for errors -3. Verify local testing requirements - -**Common Fixes**: -- Re-run migration with explicit validation request -- Install actionlint locally and validate manually -- Update agent instructions to require validation - -## Best Practices Summary - -### Before Migration - -- βœ… **Create feature branch** for migration work -- βœ… **Document current state** of CI/CD configuration -- βœ… **List all dependencies** (credentials, services, tools) -- βœ… **Backup configurations** outside repository - -### During Migration - -- βœ… **Review agent output thoroughly** before committing -- βœ… **Read migration reports** for warnings and recommendations -- βœ… **Test in feature branch first** before merging -- βœ… **Validate with actionlint** when possible - -### After Migration - -- βœ… **Monitor workflow runs** for 1-2 weeks -- βœ… **Compare performance metrics** with old CI system -- βœ… **Update team documentation** to reflect new workflows -- βœ… **Decommission old CI** only when fully validated -- βœ… **Share learnings** with other teams +**After migration:** +- Monitor workflow runs for 1-2 weeks +- Compare performance with old CI +- Update team documentation +- Decommission old CI only when validated ## Getting Help -### Resources - -- **Migration Reports**: Always start with `.github/ci-archive/MIGRATION-README.md` -- **Knowledgebase**: Review `.github-private/docs/` for migration standards -- **GitHub Actions Docs**: [docs.github.com/actions](https://docs.github.com/actions) -- **Community Forums**: [github.community](https://github.community) - -### Support Channels - -1. **Internal Team**: Consult with teams who have completed migrations -2. **GitHub Support**: Contact your Enterprise support team -3. **Agent Updates**: Submit feedback to improve agent capabilities - -### Feedback Loop - -Help improve migration agents: - -1. **Document issues** encountered during migrations -2. **Share successful patterns** that could be added to knowledgebase -3. **Suggest agent improvements** based on experience -4. **Contribute to knowledgebase** with new mappings and patterns - -## Next Steps +- **Migration Reports**: Start with `.github/ci-archive/MIGRATION-README.md` +- **Knowledgebase**: Review `knowledge/` in `.github-private` +- **Discussions**: [github.com/copilot/agents discussions](https://github.com/github/actions-migrations-via-copilot/discussions) +- **Issues**: Report problems or request improvements -- **Start with pilot migrations**: Choose 2-3 simple pipelines to test the process -- **Iterate and improve**: Refine your migration playbook based on results -- **Scale across organization**: Apply learnings to larger migration efforts -- **Maintain and evolve**: Keep knowledgebase updated as Actions ecosystem grows +## Related Docs -For deployment and setup instructions, see [**Deployment Guide β†’**](deployment.md) +- [deployment.md](deployment.md) - Deploy agents +- [extending.md](extending.md) - Add new platforms