Skip to content

operations.md

Latest commit

 

History

History
195 lines (138 loc) · 5.68 KB

operations.md

File metadata and controls

195 lines (138 loc) · 5.68 KB
Raw

Operations Guide

How to use migration agents to convert CI/CD pipelines to GitHub Actions.

Quick Reference

Method Use For How
Manual Individual repos, testing Invoke agent via github.com/copilot/agents
Batch Multiple repos, scale Run Submit Repositories workflow in .github-private

Manual Migration

1. Prepare Repository

Create a feature branch:

git checkout -b migrate/to-actions
git push -u origin migrate/to-actions

2. Invoke Agent

  1. Go to 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

  4. Provide clear instructions:

Example:

Migrate our Jenkins pipeline to GitHub Actions.

Files:
- Jenkinsfile (main build)
- deploy/Jenkinsfile (deployment)
- vars/buildDocker.groovy (shared library)

We use Docker, Kubernetes, and AWS plugins.

3. Review Output

Check generated files:

  • Workflows: .github/workflows/*.yml
  • Archive: .github/ci-archive/ (original files preserved)
  • Report: Pull Request body and .github/ci-archive/MIGRATION-README.md (fallback if PR creation/update isn’t possible; includes validation, secrets, next steps)

4. Configure Secrets

Add secrets to repository settings:

  1. Go to Settings → Secrets and variables → Actions
  2. Add secrets listed in migration report

5. Test and Merge

git add .github/
git commit -m "Migrate to GitHub Actions"
git push

Monitor workflow runs, create PR, and merge when validated.

Batch Migration

Automate migrations across multiple repositories using custom properties.

How It Works

  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

Supported Migration Types

Set GH_MIGRATION_TYPE to: Jenkins, Azure DevOps, CircleCI, GitLab, Travis CI, Bamboo, Bitbucket, or DroneCI

Set Custom Properties

Using GitHub CLI:

# 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

# Multiple repositories
for repo in repo1 repo2 repo3; do
  gh api --method PUT \
    -H "Accept: application/vnd.github+json" \
    /repos/YOUR-ORG/$repo/properties/values \
    -f properties[GH_MIGRATION_TYPE]=Jenkins
done

Run Migration 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"

Monitor Progress

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

Review migration results in each repository's pull requests.

Configuration

Edit .github/settings/config.yaml in .github-private:

gh_migration_type:
  default_value: 'Jenkins'
  other_values:
    - 'Jenkins'
    - 'Azure DevOps'
    - 'CircleCI'
    - 'GitLab'
    - 'Travis CI'
    - 'Bamboo'
    - 'Bitbucket'
    - 'DroneCI'

organizations:
  - 'your-org-name'

batch_size: 100

Troubleshooting

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

Best Practices

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

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

  • Migration Reports: Review the Pull Request created at migration completion
  • Knowledgebase: Review knowledge/ in .github-private
  • Discussions: github.com/copilot/agents discussions
  • Issues: Report problems or request improvements

Related Docs