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

A avaliação em lote permite-lhe analisar um portefólio de aplicações Java, .NET e JavaScript/TypeScript numa única execução. Obtém uma visão abrangente do panorama da modernização em todas as suas aplicações. Este artigo orienta-o através do processo de avaliação eficiente de múltiplos repositórios. O processo suporta tanto repositórios de língua única como mono-repos que contêm uma mistura de projetos Java, .NET e JavaScript/TypeScript.

Cada aplicação é analisada ao longo de dois percursos complementares. A análise de problemas encontra problemas que precisa de resolver. Os insights da base de código documentam como a aplicação é construída para que possas planear em torno dela.

Verificação de problemas

A análise de problemas deteta problemas de modernização e segurança em três domínios. A cobertura linguística difere consoante o domínio:

• Atualização — análise das versões do ambiente de execução e do framework. Abrange Java e .NET.
• Preparação para a cloud — adequação da plataforma de destino do Azure e problemas de migração. Abrange Java e .NET.
• Segurança — análise de CVE em dependências diretas e transitivas, além de problemas de segurança CWE orientados pela ISO 5055. Java apenas neste momento; O suporte a .NET e JavaScript/TypeScript está no roteiro.

Informações sobre a base de código

Os insights da base de código documentam como cada aplicação é construída. São produzidos para projetos Java, .NET e JavaScript/TypeScript. Elas aparecem quando seleciona análise completa na definição de Cobertura de Análise.

• Arquitetura — diagrama de arquitetura de alto nível com camadas, limites de módulos, topologia de execução e pontos de entrada.
• Contratos de API — interfaces REST, gRPC, filas de mensagens e webhooks que a aplicação expõe ou consome. Determina o impacto da integração antes da migração.
• Configuração — ficheiros de configuração, variáveis de ambiente, flags de funcionalidades, strings de ligação e segredos. Promove a migração de segredos e configurações para o Azure Key Vault e o Azure App Configuration.
• Fluxos de Trabalho Empresariais — fluxos funcionais de ponta a ponta reconstruídos a partir de código (por exemplo, encomenda → reserva → pagar → cumprir). Define o âmbito da regressão e a comunicação com as partes interessadas.
• Dependências — bibliotecas diretas e transitivas, SDKs e drivers com versões fixadas. Fornece dados para o mapeamento dos serviços do Azure e assinala versões EOL ou beta.
• Modelo de Dados — bases de dados, esquemas, entidades-chave e relações provenientes de mapeamentos ORM e DDL. Orienta o planeamento da migração da camada de dados.

Relatórios

A avaliação por lotes é especialmente valiosa para o planeamento da migração, pois permite avaliar de forma eficiente a prontidão e os requisitos de várias aplicações em simultâneo. Ao utilizar a avaliação em lote, pode avaliar diferentes repositórios ao mesmo tempo e obter relatórios detalhados de avaliação para cada aplicação. Produz dois tipos de relatórios para apoiar o seu planeamento migratorial:

• Por relatório de repositório: Fornece informações detalhadas sobre os dois aspetos identificados ao nível de cada repositório.
• Relatório agregado: Apresenta uma perspetiva geral de todas as aplicações avaliadas, oferecendo insights resumidos, recomendações sobre serviços de Azure, plataformas-alvo, caminhos de atualização, estratégias de migração e ondas de migração. Além disso, o relatório agregado inclui atalhos para fácil acesso a cada relatório de repositório.

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

• Visibilidade entre aplicações:

  • Relatórios agregados: Obtenha uma visão abrangente das aplicações.
  • Análise entre repositórios: Identificar padrões e dependências comuns entre aplicações.
  • Informações sobre priorização: Compreenda quais aplicações precisam de atenção imediata.

• Escala e eficiência:

  • Processamento paralelo: Use agentes na cloud para processar múltiplos repositórios simultaneamente.
  • Fluxos de trabalho automatizados: Integração com pipelines de CI/CD para realização de avaliações programadas.
  • Poupança de tempo: Reduza o tempo total de avaliação de semanas para horas.

Pré-requisitos

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

Configurar repositórios

O agente de modernização suporta várias formas de especificar os repositórios que pretende avaliar:

• Pasta atual: Analise o projeto no seu diretório de trabalho corrente.
• Entrada manual: Introduza diretamente caminhos de diretórios locais ou URLs Git remotos.
• Ficheiro de configuração do repositório: Use um ficheiro de configuração JSON que liste todos os repositórios.

Ficheiro de configuração do repositório

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

Certifica-te de que tens as permissões corretas para os repositórios ou cria um fork deles.

Formato simples (array 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 ramais 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 suporta os seguintes campos:

Formato completo com agrupamento de aplicações (opcional, para relatórios organizados):

Pode adicionar uma apps[] secção para agrupar repositórios em aplicações lógicas. Quando as aplicações são definidas, o relatório agregado organiza os resultados por aplicação e suporta a 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 da aplicação suporta:

O output campo suporta os seguintes tipos de distribuição:

O agente de modernização deteta automaticamente o ficheiro repos.json em .github/modernize/repos.json quando seleciona De um ficheiro de configuração em modo interativo. Também pode fornecer um caminho personalizado.

Executar avaliação em lote

Estão disponíveis dois modos de execução:

• Execução local: O agente de modernização processa repositórios um após outro na sua máquina local. Este modo funciona melhor para um conjunto mais pequeno de aplicações ou para testes iniciais. Suporta tanto URL Git como repositórios de caminhos locais.
• Delegação de agentes na cloud: O agente de modernização envia tarefas para os agentes cloud do GitHub Copilot para processamento paralelo na cloud. Este modo é mais rápido para cenários de múltiplos repositórios.

Modo interativo (avaliar localmente)

1. Execute o agente de modernização:

   modernize
   

2. Selecione Avaliar no menu principal.

   

3. Escolha como especificar os seus repositórios-alvo. Selecione De um ficheiro de configuração para usar um repos.json ficheiro.

   

   Sugestão

   Também pode selecionar entrada manual para introduzir caminhos locais ou URLs Git remotos diretamente, ou a pasta Current para avaliar o projeto no seu diretório atual.

4. Se o repos.json ficheiro for detetado na localização predefinida, o agente preenche-o automaticamente. Caso contrário, introduza o caminho para o seu ficheiro de configuração e pressione Enter.

5. Todos os repositórios são selecionados por padrão. Desmarque quaisquer repositórios que queira saltar e depois pressione Enter para confirmar a sua seleção.

   • Use as setas para navegar e pressione Espaço para alternar repositórios individuais.

   

6. Selecione os domínios de avaliação a analisar. Upgrade e Cloud Readiness executam em projetos Java e .NET no repositório. Security está desmarcada por predefinição e funciona apenas em projetos Java; selecione-a para detetar vulnerabilidades CVE e problemas de CWE orientados pela ISO 5055.

   

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

   • Cobertura Geral / Análise:
     • Apenas problemas (padrão): Deteta problemas de modernização e segurança no seu código-fonte. A opção mais rápida.
     • Análise completa: Detetaria problemas e gera adicionalmente insights sobre a base de código em seis aspetos da sua aplicação — Arquitetura, Contratos de API, Configuração, Fluxos de Trabalho de Negócio, Dependências e Modelo de Dados. Demora mais a executar do que a análise só de problemas.
   • Java / UPGRADE: Tempo de execução alvo (OpenJDK 11, 17, 21 ou 25).
   • Java / CLOUD READINESS: Serviços de Computação Target, Sistema Operativo Target e Containerização.
   • Java / SEGURANÇA: Gravidade mínima do CVE (low, medium, high, critical; padrão high). Valores de gravidade mais baixos incluem mais achados. (O domínio de segurança é apenas Java atualmente.)
   • .NET / UPGRADE: framework de destino (.NET 8, 9 ou 10).
   • .NET / CLOUD READINESS: Serviços de Computação de Destino.

   Use as setas para navegar, pressione Enter para alterar um valor, ou selecione Continuar para prosseguir com as definições atuais.

   

   Sugestão

   Os padrões recomendados funcionam na maioria dos cenários. Só precisa de alterar estas definições se tiver requisitos específicos, como direcionar uma versão específica do JDK, um serviço de computação específico do Azure ou um limiar de severidade CVE diferente.

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

   

9. Introduza 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 (os repositórios de caminhos locais são usados diretamente).

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

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

      

    • Cria um relatório agregado.

      

11. Quando a avaliação termina, o agente abre automaticamente o relatório agregado.

    

Modo interativo (delegação a agentes cloud)

Primeiro, configure agentes cloud em cada repositório de aplicações. Para configurar agentes cloud, faça um fork dos repositórios de exemplo.

Configuração para aplicações .NET

Configurar para correr no Windows para aplicações do .NET Framework

Por defeito, o agente cloud do Copilot corre num ambiente Ubuntu Linux. Para aplicações .NET Framework, precisas de um ambiente Windows. Para o ativar, configure .github/workflows/copilot-setup-steps.yaml no ramo main do seu repositório de aplicações, como mostrado no seguinte exemplo:

# 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: Personalização do ambiente de desenvolvimento do Copilot com as etapas de configuração do Copilot

Desativar firewall

Desative o firewall integrado do agente cloud do Copilot nas definições do seu repositório, como mostrado na imagem seguinte:

Servidor MCP

Configure GitHub Copilot Modernization MCP Server na secção Cloud agent das definições do seu repositório, como mostrado no seguinte exemplo:

{
  "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 aplicações Java

Configure GitHub Copilot Modernization MCP Server na secção Cloud agent das definições do seu repositório, como mostrado no seguinte exemplo:

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

Passos

O fluxo interativo para delegação na cloud é idêntico ao de Avaliar localmente através dos passos de código-fonte, repositório, domínio e configuração. A única diferença é a escolha do modo de execução e o que acontece depois.

1. Execute o agente de modernização:

   modernize
   

2. Selecione Avaliar no menu principal, escolha a sua fonte (ficheiro de configuração, introdução manual ou pasta atual), selecione repositórios, escolha os domínios de avaliação e reveja a configuração. Estes passos funcionam exatamente como descrito no modo Interativo (avaliar localmente).

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

   

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

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

   

   O agente recolhe os resultados da avaliação por aplicação para local e gera o relatório agregado localmente.

   

6. Quando a avaliação termina, o agente abre automaticamente o relatório agregado.

Modo não interativo (CLI)

Também pode usar o modo não interativo especificando diretamente os argumentos de comando. Use o comando modernize assess:

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

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

Avalie múltiplos repositórios especificando diretamente as fontes:

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

Avalie delegando aos agentes cloud:

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

Para mais informações, consulte avaliar - comandos CLI.

Integração do Azure Migrate

Pode conduzir a avaliação por lote diretamente a partir do seu projeto Azure Migrate e fazer com que os relatórios resultantes fluam automaticamente para o Azure Migrate.

O fluxo de extremo a extremo:

1. Descarregue um ficheiro repos.json inicial do Azure Migrate. O Azure Migrate gera um ficheiro JSON com âmbito para as aplicações que selecionou para avaliação de modernização. O ficheiro já contém as entradas apps[] e o bloco output que aponta para o seu projeto Azure Migrate.

2. Preencha os URLs dos repositórios. Edite cada entrada repos[] no ficheiro descarregado para adicionar a URL do repositório GitHub da aplicação. Mantenha os blocos apps[] e output tal como foram gerados pelo Azure Migrate — esses blocos controlam o carregamento.

3. Faz uma avaliação em lote. Execute a avaliação localmente ou delegando aos agentes cloud seguindo os passos anteriores. Ambos os modos de execução respeitam a configuração de saída do Azure Migrate.

4. Os relatórios são carregados automaticamente. Quando a avaliação termina, o agente de modernização carrega o relatório de cada aplicação para o seu projeto Azure Migrate. Não é necessária nenhuma opção adicional da CLI — a configuração output.type no ficheiro repos.json determina o carregamento.

Compreender o relatório agregado

O relatório agregado oferece uma visão abrangente das candidaturas avaliadas da seguinte forma:

Dashboard

• Resumo da saúde do portefólio: total de aplicações, quantas precisam de atualizações e contagem agregada de bloqueadores e de problemas.
• Distribuição tecnológica: que frameworks estão em uso e quantas aplicações os partilham.
• Distribuição do esforço: se a migração global é uma tarefa pequena ou grande.

Recomendações

• Azure Services: mapeia dependências atuais para equivalentes Azure recomendados. As dependências partilhadas nas aplicações são decididas uma única vez, por isso evitas retrabalho por aplicação.
• Target Platform: orienta a escolha de alojamento, como Azure Container Apps versus AKS, e revela oportunidades de consolidação.
• Caminho de Atualização: identifica quais as aplicações que necessitam de atualizações de framework como pré-requisito, separando o trabalho de atualização do trabalho de migração.
• Estimativa de Custo: estima o custo Azure de executar cada aplicação no seu alvo recomendado, para que possa considerar o gasto na priorização.
• Estratégias de Migração: recomenda uma abordagem de migração para cada aplicação — por exemplo, Replatform para migrações de transferência e reformulação ou Rearchitect para uma refatorização mais profunda — para que cada aplicação receba uma estratégia adequada ao seu grau de preparação.
• Ondas de Migração: sequenciam as aplicações por prontidão e risco em fases (por exemplo, vitórias rápidas da Onda 1, Cloud central da Onda 2, apostas a longo prazo da Onda 3). Esta abordagem permite vitórias precoces enquanto as aplicações mais difíceis são preparadas em paralelo.

Matriz de avaliação de candidaturas

• Visão geral rápida para cada aplicação sobre aspetos do framework, plataforma alvo, recomendação de atualização, divisão de problemas (Obrigatório, Potencial, Opcional), dimensionamento do esforço e mais.
• Links para relatórios individuais de aplicações para análise detalhada quando necessário.

Resolução de problemas de avaliação por lotes

Problemas comuns

Erros de acesso ao repositório:

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

Falhas de clones:

• Verifique se os repos.json URLs dos repositórios estão corretos e acessíveis.
• Certifica-te de que tens as permissões de acesso corretas para todos os repositórios.
• Verifica a tua conectividade de rede e as definições da VPN.

Falhas na avaliação:

• Verifique se o repositório contém projetos válidos em Java, .NET ou JavaScript/TypeScript.
• Verifique se existem ficheiros de build, como pom.xml, build.gradle, *.csproj, *.sln, *.slnx, ou package.json.
• Veja as mensagens de erro na saída da consola. Avisos não fatais (por exemplo, ficheiros de compilação em falta num submódulo) são agora encaminhados diretamente para a saída da CLI – reveja-os antes de considerar o relatório como final.

Problemas com delegação de agentes na cloud:

• A delegação de agentes na nuvem aceita apenas URLs de repositório https://github.com/.... Os caminhos locais e os fornecedores que não são do GitHub (GitLab, Azure DevOps) são rejeitados imediatamente com um erro descritivo. Use execução local para esses repositórios.
• Certifica-te de que tens as permissões corretas para criar fluxos de trabalho no GitHub Actions.
• Verifique as permissões do GitHub Actions e os limites de quotas para a sua organização.
• Para aplicações do .NET Framework, certifique-se de que a configuração do Windows Runner está corretamente definida.
• Verifica a configuração do teu servidor MCP.

Passos seguintes

Após completar a avaliação em lote, poderá:

Continue o fluxo de trabalho de modernização:

• Execute atualizações em lote entre repositórios - Aplique atualizações consistentes com base nos resultados da avaliação.

Saiba mais:

• Crie competências personalizadas para padrões específicos da organização.
• Aprenda sobre comandos CLI.

Fornecer comentários

A tua opinião é importante! Se tiveres algum feedback sobre a avaliação por lote ou o agente Modernization, cria um problema no repositório github-copilot-appmod ou usa o formulário de feedback de modernização GitHub Copilot.