Avaliação em lote com o agente de modernização do GitHub Copilot

A avaliação em lote permite que você analise um portfólio de aplicativos Java, .NET e JavaScript/TypeScript em uma única execução. Você obtém uma visão abrangente do cenário de modernização em seus aplicativos. Este artigo orienta você pelo processo de avaliação eficiente de vários repositórios. O processo dá suporte a repositórios de linguagem única e mono-repos que contêm uma combinação de projetos Java, .NET e JavaScript/TypeScript.

Cada aplicativo é analisado ao longo de duas faixas complementares. A verificação de problemas encontra problemas que você precisa corrigir. Os insights do Codebase documentam como o aplicativo é criado para que você possa planejar em torno dele.

Problema de verificação

A varredura de problemas detecta problemas de modernização e segurança em três domínios. A cobertura da linguagem difere por domínio:

• Atualização – análise de versão do runtime e da estrutura. Abrange Java e .NET.
• Prontidão para a Nuvem — adequação à plataforma de destino do Azure e problemas de migração. Abrange Java e .NET.
• Segurança — varredura de CVEs em dependências diretas e transitivas, além de problemas de segurança de CWE orientados pela ISO 5055. Apenas Java neste momento; o suporte a .NET e JavaScript/TypeScript está previsto no roadmap.

Insights da base de código

Os insights do Codebase documentam como cada aplicativo é criado. Eles são produzidos para projetos Java, .NET e JavaScript/TypeScript. Elas são exibidas quando você seleciona a análise completa na configuração de Cobertura de Análise.

• Arquitetura – diagrama de arquitetura de alto nível com camadas, limites de módulo, topologia de runtime e pontos de entrada.
• Contratos de API — REST, gRPC, message-queue e webhook são superfícies que o aplicativo expõe ou consome. Dimensiona o raio de impacto da integração antes da migração.
• Configuração – arquivos de configuração, variáveis de ambiente, sinalizadores de recursos, cadeias de conexão e segredos. Lidera a migração de segredos e configurações para o Azure Key Vault e o Configuração de Aplicativos do Azure.
• Fluxos de trabalho empresariais — fluxos funcionais de ponta a ponta reconstruídos do código (por exemplo, pedido → reserva → pagamento → atender). Serve de base para o escopo de regressão e a comunicação com as partes interessadas.
• Dependências – bibliotecas diretas e transitivas, SDKs e drivers com versões fixas. Alimenta o mapeamento de serviços do Azure e exibe indicadores de EOL ou beta.
• Modelo de dados – bancos de dados, esquemas, entidades-chave e relações de mapeamentos ORM e DDL. Conduz o planejamento de migração da camada de dados.

Relatórios

A avaliação em lote é especialmente valiosa para o planejamento de migração, pois permite avaliar com eficiência a preparação e os requisitos de vários aplicativos ao mesmo tempo. Usando a avaliação em lote, você pode avaliar repositórios diferentes ao mesmo tempo e obter relatórios detalhados de avaliação para cada aplicativo. Ele produz dois tipos de relatórios para dar suporte ao seu planejamento de migração:

• Por relatório de repositório: fornece insights detalhados sobre os dois aspectos identificados no nível do repositório individual.
• Aggregated report: apresenta uma perspectiva geral de todos os aplicativos avaliados, oferecendo insights resumidos, recomendações sobre serviços Azure, plataformas de destino, caminhos de atualização, estratégias de migração e ondas de migração. Além disso, o relatório agregado inclui atalhos para facilitar o acesso a cada relatório de repositório.

A avaliação em lote fornece os seguintes benefícios:

• Visibilidade entre aplicativos:

  • Relatórios agregados: obtenha uma exibição abrangente entre aplicativos.
  • Análise entre repositórios: identifique padrões e dependências comuns entre aplicativos.
  • Insights de priorização: Entenda quais aplicações precisam de atenção imediata.

• Escala e eficiência:

  • Processamento paralelo: use agentes de nuvem para processar vários repositórios simultaneamente.
  • Fluxos de trabalho automatizados: integre-se aos pipelines de CI/CD para avaliação agendada.
  • Economia de tempo: reduza o tempo total de avaliação de semanas para horas.

Pré-requisitos

• Modernizar a CLI.
• Acesso a todos os repositórios que você deseja avaliar.
• GitHub autenticação está configurada (gh auth login).

Configurar repositórios

O agente de modernização dá suporte a várias maneiras de especificar os repositórios que você deseja avaliar:

• Pasta atual: avalie o projeto em seu diretório de trabalho atual.
• Entrada manual: insira caminhos de diretório local ou URLs remotas do Git diretamente.
• Arquivo de configuração do repositório: use um arquivo de configuração JSON que lista todos os repositórios.

Arquivo de configuração do repositório

Para operações em lotes em vários repositórios, crie um arquivo de configuração JSON para listar todos os repositórios. Por exemplo, crie-o em .github/modernize/repos.json seu diretório de trabalho ou forneça um caminho personalizado.

Certifique-se de que você tenha as permissões corretas para os repositórios ou faça um fork deles.

Formato simples (matriz de repositórios):

[
  {
    "name": "PhotoAlbum-Java",
    "url": "https://github.com/Azure-Samples/PhotoAlbum-Java.git"
  },
  {
    "name": "PhotoAlbum",
    "url": "https://github.com/Azure-Samples/PhotoAlbum.git"
  },
  {
    "name": "eShopOnWeb",
    "url": "https://github.com/dotnet-architecture/eShopOnWeb.git"
  }
]

Formato completo (com ramificação e caminhos locais):

{
  "repos": [
    {
      "name": "PhotoAlbum-Java",
      "url": "https://github.com/Azure-Samples/PhotoAlbum-Java.git",
      "branch": "main"
    },
    {
      "name": "local-project",
      "path": "/absolute/path/to/project"
    }
  ]
}

Cada entrada de repositório dá suporte aos seguintes campos:

Formato completo com agrupamento de aplicativos (opcional, para relatórios organizados):

Você pode adicionar uma apps[] seção para agrupar repositórios em aplicativos lógicos. Quando os aplicativos são definidos, o relatório agregado organiza os resultados por aplicativo e dá suporte à distribuição de relatórios para destinos externos.

{
  "repos": [
    {
      "name": "PhotoAlbum-Java",
      "url": "https://github.com/Azure-Samples/PhotoAlbum-Java.git",
      "branch": "main"
    },
    {
      "name": "PhotoAlbum",
      "url": "https://github.com/Azure-Samples/PhotoAlbum.git"
    }
  ],
  "apps": [
    {
      "identifier": "photo-app",
      "description": "Photo management application",
      "repos": ["PhotoAlbum-Java"],
      "output": {
        "type": "local",
        "path": "/path/to/reports/photo-app"
      }
    }
  ]
}

Cada entrada de aplicativo dá suporte a:

O output campo dá suporte aos seguintes tipos de distribuição:

O agente de modernização detecta automaticamente o arquivo repos.json em .github/modernize/repos.json quando você seleciona De um arquivo de configuração no modo interativo. Você também pode fornecer um caminho personalizado.

Executar avaliação em lote

Dois modos de execução estão disponíveis:

• Execução local: o agente de modernização processa repositórios um após o outro em seu computador local. Esse modo funciona melhor para um conjunto menor de aplicativos ou para testes iniciais. Dá suporte a repositórios de URL do Git e de caminho local.
• Delegação de agentes na nuvem: o agente de modernização envia tarefas aos agentes de nuvem do GitHub Copilot para processamento paralelo na nuvem. Esse modo é mais rápido para cenários de vários repositórios.

Modo interativo (avaliar localmente)

1. Execute o agente de modernização:

   modernize
   

2. Selecione Avaliar no menu principal.

   

3. Escolha como especificar seus repositórios de destino. Selecione De um arquivo de configuração para usar um repos.json arquivo.

   

   Dica

   Você também pode selecionar entrada manual para inserir caminhos locais ou URLs remotas do Git diretamente ou pasta atual para avaliar o projeto em seu diretório atual.

4. Se o repos.json arquivo for detectado no local padrão, o agente o preencherá automaticamente. Caso contrário, insira o caminho para o arquivo de configuração e pressione Enter.

5. Todos os repositórios são selecionados por padrão. Desmarque todos os repositórios que você deseja ignorar e pressione Enter para confirmar sua seleção.

   • Use teclas de direção para navegar e pressionar Espaço para alternar repositórios individuais.

   

6. Selecione os domínios de avaliação a serem analisados. Upgrade e Cloud Readiness executados em projetos Java e .NET no repositório. Security é desmarcado por padrão e é executado somente em projetos Java; selecione-o para verificar se há vulnerabilidades CVE e problemas de CWE guiados pelo ISO 5055.

   

7. Examine e configure as opções de avaliação. A página de configuração mostra as opções agrupadas por idioma e domínio:

   • Cobertura geral/de análise:
     • Problema somente (padrão): detecta problemas de modernização e segurança no código-fonte. Opção mais rápida.
     • Análise completa: detecta problemas e, além disso, gera insights de base de código em seis aspectos do seu aplicativo : Arquitetura, Contratos de API, Configuração, Fluxos de Trabalho De Negócios, Dependências e Modelo de Dados. Leva mais tempo para ser executado do que a análise somente de problemas.
   • Java/UPGRADE: Runtime de destino (OpenJDK 11, 17, 21 ou 25).
   • Java/CLOUD READINESS: Serviços de Computação de Destino, Sistema Operacional de Destino e Contêinerização.
   • Java/SECURITY: gravidade CVE mínima (low, medium, high, critical; padrão high). Valores de severidade mais baixos incluem mais descobertas. (O domínio de segurança é exclusivo do Java no momento.)
   • .NET/UPGRADE: Estrutura de Destino (.NET 8, 9 ou 10).
   • .NET/CLOUD READINESS: Serviços de Computação Alvo.

   Use as teclas de direção para navegar, pressione Enter para alterar um valor ou selecione Continuar para continuar com as configurações atuais.

   

   Dica

   Os padrões recomendados funcionam para a maioria dos cenários. Você só precisará alterar essas configurações se tiver requisitos específicos, como direcionar uma versão específica do JDK, um serviço de computação Azure específico ou um limite de severidade CVE diferente.

8. Escolha o modo de execução. Selecione Avaliar localmente.

   

9. Insira o caminho de saída para os resultados da avaliação ou pressione Enter para aceitar o padrão.

10. O agente automaticamente:

    • Clona repositórios remotos (repositórios de caminho local são usados diretamente).

    • Executa a avaliação em cada repositório um por um.

    • Gera relatórios de avaliação individuais.

      

    • Cria um relatório agregado.

      

11. Quando a avaliação for concluída, o agente abrirá automaticamente o relatório agregado.

    

Modo interativo (delegando para agentes de nuvem)

Primeiro, configure agentes de nuvem em cada repositório de aplicativos. Para configurar agentes de nuvem, bifurque os repositórios de exemplo.

Configuração para aplicativos .NET

Configurar para ser executado em Windows para aplicativos do .NET Framework

Por padrão, o agente de nuvem Copilot é executado em um ambiente Ubuntu Linux. Para aplicativos .NET Framework, você precisa de um ambiente Windows. Para habilitá-lo, configure .github/workflows/copilot-setup-steps.yaml no main branch do repositório de aplicativos, conforme mostrado no exemplo a seguir:

# Windows-based Copilot Setup Steps for .NET tasks
# Note: Windows runners have firewall limitations that may affect some network operations
# Use this workflow for .NET projects that require Windows-specific tooling

name: "Copilot Setup Step (Windows)"

on:
  workflow_dispatch:

jobs:
  copilot-setup-steps:
    runs-on: windows-latest
    permissions:
      contents: read
    steps:
      - name: Checkout code
        uses: actions/checkout@v5

Saiba mais em: Personalizando o ambiente de desenvolvimento do Copilot com as etapas de configuração do Copilot

Desabilitar firewall

Desabilite o firewall integrado do agente de nuvem do Copilot nas configurações do repositório, conforme mostrado na imagem a seguir:

Servidor MCP

Configure o servidor MCP de Modernização do GitHub Copilot na seção Cloud agent nas configurações do seu repositório, conforme mostrado no exemplo a seguir:

{
  "mcpServers": {
   "AppModDotNetUpgrade": {
        "type": "local",
        "command": "dotnet",
        "args": [
          "dnx",
          "Microsoft.GitHubCopilot.Modernization.Mcp",
          "--prerelease",
          "--yes",
          "--source",
          "https://api.nuget.org/v3/index.json"
        ],
        "env": {
          "APPMOD_CALLER_TYPE": "modernize-cli"
        },
        "tools": ["*"]
    }
  }
}

Configuração para aplicativos Java

Configure o Servidor MCP de Modernização do GitHub Copilot na seção Cloud agent nas configurações do seu repositório, conforme mostrado no exemplo a seguir:

{
  "mcpServers": {
    "app-modernization": {
      "type": "local",
      "command": "npx",
      "tools": [
        "*"
      ],
      "args": [
        "-y",
        "@microsoft/github-copilot-app-modernization-mcp-server"
      ]
    }
  }
}

Steps

O fluxo interativo para delegação de nuvem é idêntico a Avaliar localmente por meio das etapas de origem, repositório, domínio e configuração. A única diferença é a opção de modo de execução e o que acontece depois.

1. Execute o agente de modernização:

   modernize
   

2. Selecione Avaliar no menu principal, escolha sua origem (arquivo de configuração, entrada manual ou pasta atual), selecione repositórios, escolha seus domínios de avaliação e examine a configuração. Essas etapas funcionam exatamente como descrito no modo interativo (avaliar localmente).

3. Escolha o modo de execução. Selecione Delegar para Agentes de Nuvem.

   

4. Insira o caminho de saída para os resultados da avaliação ou pressione Enter para aceitar o padrão.

5. O agente delega automaticamente as tarefas de avaliação para cada repositório para agentes de nuvem e as executa na nuvem em paralelo.

   

   O agente puxa os resultados da avaliação por aplicativo de volta para o local e gera o relatório agregado localmente.

   

6. Quando a avaliação for concluída, o agente abrirá automaticamente o relatório agregado.

CLI (modo não interativo)

Você também pode usar o modo não interativo especificando argumentos de comando diretamente. Use o comando modernize assess:

Avalie localmente usando um arquivo de configuração do repositório:

modernize assess --source .github/modernize/repos.json

Avalie vários repositórios especificando fontes diretamente:

modernize assess --source https://github.com/org/repo1 --source https://github.com/org/repo2

Avalie delegando aos agentes de nuvem:

modernize assess --source .github/modernize/repos.json --delegate cloud --wait

Para obter mais informações, consulte avaliar – comandos da CLI.

Integração com o Migrações para Azure

Você pode conduzir a avaliação em lote diretamente do seu projeto de Migrações para Azure e fazer com que os relatórios resultantes fluam de volta para Migrações para Azure automaticamente.

O fluxo de ponta a ponta:

1. Baixe um repos.json inicial de Migrações para Azure. Migrações para Azure gera um arquivo JSON com escopo para os aplicativos selecionados para avaliação de modernização. O arquivo já contém as entradas apps[] e o bloco output que aponta de volta para seu projeto de Migrações para Azure.

2. Informe as URLs do repositório. Edite cada entrada repos[] no arquivo baixado para adicionar a URL do repositório GitHub para o aplicativo. Mantenha os blocos apps[] e output conforme foram gerados pelo Migrações para Azure - esses blocos controlam o upload.

3. Execute a avaliação em lote. Execute a avaliação localmente ou delegando aos agentes de nuvem as etapas anteriores. Ambos os modos de execução respeitam a configuração de saída Migrações para Azure.

4. Os relatórios são carregados automaticamente. Quando a avaliação for concluída, o agente de modernização carregará o relatório de cada aplicativo de volta para seu projeto de Migrações para Azure. Nenhuma flag extra da CLI é necessária - a configuração output.type no arquivo repos.json controla o upload.

Noções básicas sobre o relatório agregado

O relatório agregado fornece uma visão abrangente nos aplicativos avaliados, como se segue:

Dashboard

• Instantâneo da integridade do portfólio: total de aplicativos, quantos precisam de upgrades e agregação de contagens de bloqueadores e problemas.
• Distribuição de tecnologia: quais estruturas estão em uso e quantos aplicativos as compartilham.
• Distribuição de esforço: se a migração geral é uma tarefa pequena ou grande.

Recomendações

• Azure Services: mapeia as dependências atuais para equivalentes Azure recomendados. As dependências compartilhadas entre os aplicativos são decididas apenas uma vez, portanto, você evita o retrabalho em cada aplicativo.
• Target Platform: orienta a opção de hospedagem, como Aplicativos de Contêiner do Azure versus AKS, e apresenta oportunidades de consolidação.
• Caminho de Atualização: identifica quais aplicativos precisam de atualizações de estrutura como um pré-requisito, separando o trabalho de atualização do trabalho de migração.
• Cost Estimate: estima o custo Azure de executar cada aplicativo em seu destino recomendado, para que você possa considerar os gastos em priorização.
• Estratégias de migração: recomenda uma abordagem de migração para cada aplicativo — por exemplo, Replatform para migrações do tipo lift-and-reshape ou Rearchitect para refatorações mais profundas — para que cada aplicativo receba uma estratégia adequada ao seu nível de prontidão.
• Ondas de Migração: organiza os aplicativos de acordo com o nível de prontidão e o risco em fases (por exemplo, ganhos rápidos da Onda 1, nuvem principal da Onda 2, apostas de longo prazo da Onda 3). Essa abordagem permite ganhos antecipados enquanto aplicativos mais difíceis são preparados em paralelo.

Matriz de avaliação de aplicativo

• Visão geral rápida de cada aplicativo sobre aspectos da estrutura, plataforma de destino, recomendação de atualização, detalhamento de problemas (Obrigatório, Potencial, Opcional), dimensionamento de esforço e muito mais.
• Links para relatórios de aplicativos individuais para análise detalhada quando necessário.

Solução de problemas de avaliação em lote

Problemas comuns

Erros de acesso ao repositório:

• Verifique GitHub autenticação usando gh auth status.
• Verifique se você tem acesso a todos os repositórios listados em repos.json.

Falhas de clonagem:

• Verifique se as URLs do repositório estão corretas repos.json e acessíveis.
• Verifique se você tem as permissões de acesso corretas para todos os repositórios.
• Verifique a conectividade de rede e as configurações de VPN.

Falhas de avaliação:

• Verifique se o repositório contém projetos válidos Java, .NET ou JavaScript/TypeScript.
• Verifique se existem arquivos de build, como pom.xml, , build.gradle, *.csproj, *.sln, *.slnxou package.json.
• Examine as mensagens de erro na saída do console. Avisos não fatais (por exemplo, arquivos de build ausentes em um submódulo) agora são exibidos diretamente na saída da CLI — revise-os antes de tratar o relatório como final.

Problemas de delegação do agente de nuvem:

• A delegação de agente de nuvem aceita apenas URLs de repositório https://github.com/.... Caminhos locais e provedores que não sejam do GitHub (GitLab, Azure DevOps) são rejeitados de imediato com uma mensagem de erro descritiva. Use a execução local para esses repositórios.
• Verifique se você tem as permissões certas para criar fluxos de trabalho GitHub Actions.
• Verifique GitHub Actions permissões e limites de cota para sua organização.
• Para aplicativos .NET Framework, verifique se Windows configuração do executor está definida corretamente.
• Verifique a configuração do servidor MCP.

Próximas Etapas 

Depois de concluir a avaliação em lote, você pode:

Continue o fluxo de trabalho de modernização:

• Executar a atualização em lote entre repositórios – Aplicar atualizações consistentes com base nos resultados da avaliação.

Saiba mais:

• Crie habilidades personalizadas para padrões específicos da organização.
• Saiba mais sobre os comandos da CLI.

Fornecer comentários

Sua entrada é importante! Se você tiver algum comentário sobre a avaliação em lote ou sobre o agente de Modernização, crie um problema no repositório github-copilot-appmod ou use o formulário de comentários de modernização do GitHub Copilot.