Edit

Share via

Quickstart: Install and use the GitHub Copilot modernization agent

This quickstart guides you through installing the GitHub Copilot modernization agent and using it to modernize a sample application.

Prerequisites

  • A GitHub Copilot subscription: Free, Pro, Pro+, Business, or Enterprise plan. See Copilot plans.
  • GitHub CLI: Install the GitHub CLI (gh) for authentication, version v2.45.0 or later. See Installing gh.

Platform requirements

  • Windows: x64 or ARM64.
  • Linux: x64 or ARM64 with glibc 2.27 or later (Ubuntu 18.04 or later, Debian 10 or later, Fedora 29 or later, Azure Linux 2.0 or later).
  • macOS: Apple Silicon or Intel.

Install the modernization agent

Use the following commands to install the modernization agent or update to the latest version.

Use one of the following options:

Option 1 - Winget (recommended):

winget install GitHub.Copilot.modernization.agent

For silent installation with no prompts:

winget install GitHub.Copilot.modernization.agent --silent

Option 2 - PowerShell one-liner:

iex (irm 'https://raw.githubusercontent.com/microsoft/modernize-cli/main/scripts/install.ps1')

Option 3 - MSI installer:

Download and run the latest MSI from the GitHub releases page.

Note

After installation, open a new terminal for the modernize command to be available on your PATH. These commands work for both initial installation and updating to the latest version. A dedicated version update command will be available in a future release.

Verify the installation:

modernize --version

Get a sample application

For this quickstart, use a sample application. Choose either Java or .NET:

git clone https://github.com/Azure-Samples/PhotoAlbum-Java.git
cd PhotoAlbum-Java
git checkout -b modernize

Use the interactive mode

The easiest way to get started is by using the interactive mode. First, authenticate by using the GitHub CLI:

gh auth login

Then, run the modernization agent:

modernize

The main menu appears:

○ What would you like to do?

  > Assess        Analyze your source application and generate an assessment report
    Plan          Create a modernization plan based on assessment findings
    Execute       Run tasks defined in your modernization plan
  ──────────────
    Upgrade       Upgrade your runtime and frameworks to the latest versions

Step 1: Assess the application

  1. Select Assess from the main menu.
  2. Choose how to specify your target repositories. You can select Current folder to use your current directory, Manual input to enter local paths or remote Git URLs, or From a config file to load repositories from a JSON config file. For this quickstart, select Current folder.
  3. Choose the execution mode. Select Assess locally to run the assessment on your machine, or Delegate to Cloud Agents to let cloud agents run the assessment in parallel. For this quickstart, select Assess locally.
  4. Select assessment domains, such as Java upgrade and Cloud Readiness, and press Enter.
  5. Review the assessment configuration options, such as Analysis Coverage and Target Runtime. Press Enter on Continue to accept the recommended defaults, or adjust individual settings as needed.
  6. Accept the default output path or enter a custom one, and then press Enter to start the assessment.
  7. Wait for the assessment to complete.

The assessment results are saved to .github\modernize\assessment\ in your project directory. The agent analyzes your code, dependencies, and configuration to identify:

  • Outdated framework versions
  • Deprecated APIs
  • Cloud compatibility issues
  • Migration opportunities

Step 2: Create a modernization plan

After the assessment finishes, the agent prompts you to create a modernization plan based on the identified problems:

○ How would you like to continue?

  > 1. Create modernization plan
       Generate a plan.md file according to the identified issues
    2. Return to main menu
  1. Select 1. Create modernization plan.
  2. Enter a plan name or press Enter to use the default name.
  3. Enter your modernization goal as a prompt. By default, the prompt is References the assessment summary and creates plan to create a plan based on the assessment findings. You can replace it with any other migration request, for example:
    • migrate the database to Azure PostgreSQL
    • upgrade to Spring Boot 3
    • deploy to Azure Container Apps
  4. Press Enter to generate the plan.

The agent analyzes your codebase and generates:

  • Plan file (.github/modernize/{plan-name}/plan.md): Detailed strategy and approach.
  • Task list (.github/modernize/{plan-name}/tasks.json): Breakdown of executable steps.

Tip

You can manually edit plan.md to add clarifications or adjust details. You can also update tasks.json to modify, reorder, add, or remove tasks before executing the plan.

Step 3: Execute the modernization plan

After you verify the plan, confirm that you want to execute the plan.

○ How would you like to continue?

  > 1. Execute modernization plan
       Run the tasks defined in the modernization plan
    2. Return to main menu
  1. Select 1. Execute modernization plan.
  2. Press Enter to execute the plan.
  3. Monitor progress as the agent applies changes.

The agent executes each task in order:

  • Makes code changes according to the plan.
  • Validates builds after each change.
  • Scans for and addresses CVEs.
  • Commits changes.

Step 4: Review the results

After execution finishes, you can review all changes that the agent made before merging them:

  1. Review changes: Check the modifications on the current branch.

    git status
git diff main

  2. Create a pull request: If you're satisfied with the changes, create a PR for team review.

    gh pr create \
    --title "Modernization: migrate the app to azure" \
    --body "Automated modernization by GitHub Copilot agent"

Next steps

Provide feedback

Your input is important! If you have any feedback about the Modernization agent, create an issue at the github-copilot-appmod repository or use the GitHub Copilot modernization feedback form.

  • Last updated on