Edit

Add code insights by using GitHub Copilot modernization (preview)

This article describes how to add code insights by using GitHub Copilot modernization when you're migrating applications to Azure services. Adding code insights helps you better assess migration readiness and get recommendations for migration strategies based on the code changes identified during the scan.

Code insights for web apps provide changes required to modernize them to Azure Kubernetes Service (AKS) and Azure App Service. Code changes for an application are an aggregate of code changes for its child web apps.

In this article, you learn how to:

  • Generate a GitHub Copilot code assessment report for web apps.
  • Add code insights for web apps from an application inventory and assessment pages.
  • Add code insights for web apps from a web app inventory and assessment pages.
  • View code insights.

You can add code insights by using any of the following methods:

  • Use the GitHub Copilot Modernize CLI. Use this method to run an at-scale assessment for multiple web apps simultaneously, with automated report upload to Azure Migrate. This approach allows cloud administrators and application developers to collaborate while adhering to their organization's code security guidelines.
  • Upload by using a ZIP file. Use this method when you already have a code scan report or permissions to generate one. It requires manual mapping of reports to each web app.
  • Request a report through a GitHub issue. Use this method when you can't generate a code insights report yourself or you don't have access to the code repository.

Note

Code insights aren't currently supported through private endpoints.

Run at-scale code assessments by using the GitHub Copilot Modernize CLI

Using the GitHub Copilot Modernize CLI enables at-scale code assessment for multiple applications and web apps, with source code spread across multiple repositories.

First, you download a configuration file from Azure Migrate that contains details of all the web apps. You then update the mapping of web apps to repositories and run the assessment by using the GitHub Copilot Modernize CLI. Code changes are automatically mapped back to Azure Migrate for the corresponding applications and web apps.

Prerequisites for Azure Migrate users

  • An Azure Migrate project with successful discovery of applications and web apps.
  • ASP.NET or Java web apps. These types of web apps are supported.
  • Azure App Service or Azure Kubernetes Service. Code insights are supported for these Azure targets.

Prerequisites for GitHub Copilot Modernize CLI users

  • A GitHub Copilot Free, Pro, Pro+, Business, or Enterprise license.
  • Installation of the Azure CLI and GitHub Copilot Modernize CLI. Sign in to Azure and GitHub Copilot.
  • The Decide and Plan Expert role or higher privileges to the Azure Migrate project.

For detailed installation steps, see the Modernize CLI instructions.

Download the configuration file from Azure Migrate

  1. Generate the configuration file by using any of these methods:

    • On the Azure Migrate Overview page, under Explore Applications, select Applications.
    • On the Azure Migrate Overview page, under Explore inventory, select Web apps.
    • On the Azure Migrate Overview page, under Decide and Plan, select Assessments. Choose the relevant application assessment or web app assessment.

  2. Select the applications or web apps for which you want to add code insights. Then select Add code insights > GitHub Copilot modernization.

    Screenshot that shows the selection of the GitHub Copilot modernization option.

  3. By default, At scale code assessment with automated report upload is selected to add code changes by using the GitHub Copilot Modernize CLI.

  4. Review the list of web apps. You can remove the web apps for which you don't need code insights.

  5. Select Download to generate a JSON file that contains details of all the web apps to be assessed and placeholders to add repository information. The download might take a few seconds to finish.

    Screenshot that shows the download configuration option.

Run the configuration file in the Modernize CLI

  1. Before you run the configuration file in the Modernize CLI, you must update the file with the code repository name and path for each web app. The file has two sections: apps and repos.

    Screenshot that shows how to update the file with the code repository name and path for each web app.

  2. In the apps section, review the web app name, hosting server, parent application, and framework version.

  3. In the apps section, in the repos property, replace <sample-git-repo> and <sample-local-repo> with the name of the repository that's associated with the web app. You can mention names of multiple GitHub repositories and local paths.

  4. In the repos section, update the same repository names as described in the previous step. Then replace <https://github.com/<sample-org>/<sample-repo>.git> with the path to the GitHub repository. The branch field is optional. If the repository is stored locally, replace </absolute/path/to/project> with path details.

  5. Repeat the preceding steps for all web apps in the configuration file.

  6. Open the GitHub Copilot Modernize CLI. Authenticate to GitHub Copilot and Azure by using gh auth login and az login. Ensure that the user running the Modernize CLI has the Decide and Plan Expert role assigned for the Azure Migrate project.

  7. Run modernize assess --source <local path to configuration file>. The code assessment might take a few minutes to finish.

  8. After a successful code assessment, reports are automatically pushed to Azure Migrate. You receive the message Distribution complete: m/n app(s) distributed.

  9. Code changes are automatically updated for the selected applications and web apps in Azure Migrate.

View code insights

  1. To view code insights for applications, go to Explore applications > Applications. In the Code changes column, select Available.

    Screenshot that shows how to select code change options in the Applications pane.

  2. To view code insights for web apps, go to Explore inventory > Web apps. In the Code changes column, select Available.

  3. If you already created an assessment for the applications or web apps for which you added code insights, that assessment is outdated. Recalculate the assessment to view code insights. You can find code changes under View details for each assessment.

  4. Review the code changes by selecting the relevant tab: Issues, Warnings, or Information. These tabs provide a summarized view of code changes across the web apps in the assessment.

  5. The list provides actionable remediation guidance and estimated effort for code fixes. GitHub Copilot effort is estimated at approximately 40% of the manual effort required.

    Screenshot that shows the summarized view of code changes across the web apps in an assessment.

  6. If you already created the assessment, code changes appear only for the recommended target, and the readiness and migration strategy might change. If the required code changes are significant, readiness might change from Ready to Ready with conditions.

Manually upload code scan reports by using a ZIP file

You can generate a code scan report manually and upload it as a ZIP file to Azure Migrate.

Prerequisites

  • Web apps for which you want to generate a code scan report

Generate a GitHub Copilot code assessment report

You can generate a code assessment report by using the GitHub Copilot modernization extension or the AppCAT CLI.

GitHub Copilot modernization extension

  1. Install the GitHub Copilot modernization extension in Visual Studio Code.

  2. Open the source code of your web app from the GitHub repository. You must have permissions to the code repository.

  3. On the sidebar, select GitHub Copilot modernization. In the ASSESSMENT section, select Migrate to Azure or Run Assessment.

  4. When the assessment finishes, you can download the report.json file to the location of your choice.

  5. Create a ZIP file for all the reports that you want to add.

AppCAT CLI

  1. Install AppCAT:

  2. Generate AppCAT reports for all assessed web apps:

  3. Create a ZIP file for all the reports that you want to add.

Upload the ZIP file

  1. Add a code assessment report by using any of these methods:

    • On the Azure Migrate Overview page, under Explore inventory, select Web apps.
    • On the Azure Migrate Overview page, under Explore Applications, select Applications.
    • On the Azure Migrate Overview page, under Decide and Plan, select Assessments. Choose the application assessment or web app assessment.

  2. Select the applications or web apps for which you want to add code insights. Then select Add code insights > GitHub Copilot modernization.

  3. Select Single code assessment with manual report upload.

    Screenshot that shows selecting single code assessment with manual report upload.

  4. In the Add Code Insights pane, select Upload a ZIP file.

  5. Select Browse. Select the location of the ZIP file that contains the reports to import, and then select Upload. Wait for the upload and validation to finish.

    Screenshot that shows how to upload the ZIP file that contains the reports to import.

  6. In the list of web apps, select the Code insights report dropdown list, and then view the uploaded reports under Uploaded from .ZIP file.

    Screenshot that shows how to view a code insights report.

  7. Select the appropriate report to map to the corresponding web app. Repeat these steps for all required web apps.

  8. Select Add and wait for the process to finish. Code insights reports are automatically mapped to all Azure targets.

    Screenshot that shows how code insights reports are automatically mapped to all Azure targets.

  9. After the mapping is complete, the Code changes column on pages for applications and web apps shows Available. All assessments for the selected applications or web apps are marked as outdated. Select Recalculate to start recalculation.

  10. On the page for the applications or web apps, select Available to view code insights. If code changes are included, the page displays the number of changes for the recommended Azure target.

Request a report via GitHub

Requesting a report via GitHub connects Azure Migrate to a GitHub repository by using the provided connection details and automatically creates an issue in that repository. By using the GitHub Copilot modernization extension, you can scan your code and upload reports directly to the related GitHub issue.

After you update the issue, Azure Migrate automatically attaches the code scan reports to the associated web applications. This approach allows cloud administrators and developers to collaborate while maintaining security boundaries for application code.

Prerequisites

  • Ensure that a web app assessment exists for each web app, because you can add code scan reports only to an existing assessment.
  • Provide information about the GitHub repository required for integration with Azure Migrate, to allow automatic requests and synchronization of code scan reports.
  • Provide GitHub application details with permissions to create issues and read comments in the target repository.

Create a new GitHub app

  1. In the upper-right corner of the GitHub page, select your profile picture.

  2. Go to your account settings:

    • For an app owned by a personal account, select Your organization and then select Settings to the right of the organization.
    • For an app owned by an enterprise:
      • If you use enterprise managed users, select Your enterprise to go directly to the enterprise account settings.
      • If you use personal accounts, select Your enterprises and then select Settings to the right of the enterprise.

  3. Go to the GitHub app settings:

    • For an app owned by a personal account or organization, select Developer settings on the sidebar. Then select GitHub Apps > New GitHub App.
    • For an app owned by an enterprise, go to Settings on the sidebar. Then select GitHub Apps > New GitHub App.

    Screenshot that shows how to select a new GitHub app.

  4. Provide the following details to set up your new GitHub app:

    1. Under GitHub App name, enter a name for your app.
    2. Under Homepage URL, provide the complete URL. This URL serves as a placeholder and isn't used in this process.

    Screenshot that shows details for registering a new GitHub app, including the home page URL.

  5. Ensure that Expire user authorization tokens is selected.

  6. Under Webhook, clear the Active checkbox.

    Screenshot that shows how to deselect the active webhook.

  7. Under Permissions, select Repository permissions. Then select the following permissions for the app.

    Resource Permissions
    Issues Read and write
    Metadata Read-only
    Webhook Read and write

  8. Under Where can this GitHub App be installed?, select Only on this account or Any account.

  9. Select Create GitHub App.

    Screenshot that shows available permissions and the button for creating a GitHub app.

Install the GitHub app in your repository

  1. Go to the GitHub app that you created.

  2. Select Install App.

  3. Select an account, and then select Install. Use the account that contains the repository for creating issues and uploading code scan reports.

    Screenshot that shows how to select an account for app installation.

  4. Select Only select repositories, and then select the appropriate repositories from Select repositories. You can select multiple repositories. When you finish, select Install.

    Screenshot that shows how to install a selected repository.

  5. After the installation finishes, note the browser URL that contains the installation ID. For example: https://github.com/settings/installations/<installationID>.

Get GitHub app details and the private key to create a GitHub connection

Collect the following GitHub app details and private key, and create a GitHub connection in Azure Migrate.

  1. Go to the GitHub app that you created and select Edit.

  2. Under General > About, find the App ID value and note it.

  3. Scroll down to Private keys and select Generate a private key.

    Note

    Rotate the private key every 90 days for security. If you generate a new private key, you must re-create the connection because updating the key isn't currently supported.

  4. The new private key file is downloaded to your machine automatically.

  5. To find the Installation ID value, go to Install App and select Settings next to the account where the app is installed.

  6. After the installation finishes, note the browser URL that contains the installation ID. For example: https://github.com/settings/installations/<installationID>.

Request a code scan report for a web app and an application assessment by using a GitHub issue

  1. Add a code assessment report by using any of these methods:

    • On the Azure Migrate Overview page, under Explore inventory, select Web apps.
    • On the Azure Migrate Overview page, under Explore Applications, select Applications.
    • On the Azure Migrate Overview page, under Decide and Plan, select Assessments. Choose the application assessment or web app assessment.

  2. Under Add code insights, select Using GitHub Copilot assessment.

    Screenshot that shows how to add code insights by using a GitHub copilot assessment.

  3. In the Add code insights pane, select Create GitHub connection.

  4. In the Create new GitHub connection pane, provide the following details:

    Field Details
    Connection name Provide a name for the connection. This name appears in the list when you add a report to the web app.
    GitHub repository URL Specify the GitHub repository for creating an issue to request a code scan report. Upload the code scan report to this issue by using GitHub Copilot.

    Use this repository only to create GitHub issues and read code scan reports from those issues. You don't need to include application code in this repository.
    App ID Enter the app ID of the GitHub app that you created, to allow Azure Migrate access.
    Private Key Copy all the contents of the private key file that you generated for your GitHub app.
    Installation ID Enter the installation ID of the GitHub app installed on the repository that you specified earlier.

  5. After you add the details, select Create connection.

    Screenshot that shows how to create a GitHub connection.

  6. Wait until the connection is successfully created, and then select Close.

  7. On the Add code insights pane in the web app, in the list, select Request report via GitHub.

  8. In the Add insights via GitHub pane, select the appropriate connection name, and then select Request.

    Screenshot that shows how to request a report via GitHub.

  9. Azure Migrate creates a GitHub issue in the repository that you specified in the connection details.

  10. When the code scan report is uploaded to the GitHub issue, Azure Migrate automatically maps the report to the web app and corresponding applications.

  11. After the mapping is complete, the Code changes column on pages for applications and web apps shows Available. All assessments for the selected applications or web apps are marked as outdated. Select Recalculate to start recalculation.

  12. On the page for the applications or web apps, select Available to view code insights. If code changes are included, the page displays the number of changes for the recommended Azure target.

Generate a code scan report by using the GitHub Copilot modernization extension

  1. Generate a code scan report:

  2. Upload the report to a GitHub issue by using the prompt in GitHub Copilot.

Troubleshoot

This section helps you resolve problems related to code insights in Azure Migrate.

GitHub Copilot Modernize CLI

Unable to generate a configuration file: Select at least one web app or one application with web apps to generate code insights.

Unable to generate a code assessment in the GitHub Copilot Modernize CLI: Ensure that the installation is complete, you met the prerequisites, and the user has permissions to the source code repository.

Unable to view code changes in Azure Migrate: If you successfully generated code insights by using the Modernize CLI but you can't view code changes in Azure Migrate, follow these guidelines to view code changes:

  • Ensure that code assessment is completed successfully for all web apps.
  • Ensure that the user running the Modernize CLI has Decide and Plan Expert role permissions to the Azure Migrate project.
  • Ensure that the relevant web apps are included in the downloaded configuration file.
  • Ensure that the framework of web apps in the configuration file is the same as the mapped code repository.

ZIP file

Failure to upload reports as a ZIP file

Follow these guidelines to successfully import paths and upload ZIP files without errors.

Upload a ZIP file that meets these requirements:

  • It contains only JSON files.
  • It's less than 50 MB. If it's uncompressed, it's less than 500 MB.
  • It contains fewer than 100 files.
  • It doesn't contain nested ZIP files.

Errors might appear if the uploaded ZIP file doesn't meet the required constraints. Here are some examples.

Error Reason
The uploaded blob content type %Value; isn't supported. The uploaded file isn't a ZIP file.
Zip contains too many files (%FileCount;). Limit is %MaxFileCount;. The ZIP file contains more than 100 files.
Total uncompressed size %UncompressedSize;MB of uploaded ZIP file exceeds limit of %MaxUncompressedSize;MB. The uncompressed size of the ZIP file exceeds 500 MB.
Zip entry %EntryName; is invalid (possible path traversal). A file name in the ZIP file contains path traversal characters such as ../../.*.
The uploaded ZIP file is empty and contains no valid files. The ZIP file doesn't contain any files.

If you get any of these errors, remove the invalid or extra files and re-create the ZIP file before uploading it again.

Partial files or no files accepted for report generation

Even if the ZIP file meets all guidelines and is processed, the reports might not appear for every file in it. The reason can be JSON schema incompatibility or unsupported targets in the report file.

When this problem occurs, Azure Migrate uses content from valid files to generate the report. Files that fail validation return errors like the following examples.

Error Reason
The report content is invalid or not in the expected JSON format. The JSON report schema is invalid or incompatible.
The report doesn't contain supported targets for the specified framework. The report includes targets that Azure Migrate doesn't support. AppCAT supports many targets, but Azure Migrate supports only a subset.

When you encounter these errors, regenerate the report with the correct configuration and upload it again by using a separate import flow.

Related content

  • Last updated on