Evaluación por lotes con el agente de modernización de GitHub Copilot

La evaluación por lotes permite analizar una cartera de aplicaciones Java, .NET y JavaScript/TypeScript en una sola ejecución. Obtiene una visión completa del panorama de modernización en las aplicaciones. Este artículo le guía por el proceso de evaluación de varios repositorios de forma eficaz. El proceso admite repositorios de un solo lenguaje y mono-repos que contienen una combinación de proyectos de Java, .NET y JavaScript/TypeScript.

Cada aplicación se analiza a lo largo de dos pistas complementarias. Análisis de problemas encuentra problemas que debes corregir. Información sobre la base de código documenta cómo está construida la aplicación para que puedas planificar en consecuencia.

Análisis de problemas

El examen de problemas detecta problemas de modernización y seguridad en tres dominios. La cobertura de idioma difiere según el dominio:

• Actualización : análisis de versiones del entorno de ejecución y del marco. Cubre Java y .NET.
• Preparación para la nube — adecuación a la plataforma de destino de Azure y problemas de migración. Cubre Java y .NET.
• Seguridad — análisis de CVE en dependencias directas y transitivas, así como problemas de seguridad de CWE conformes a ISO 5055. Solo Java por ahora; la compatibilidad con .NET y JavaScript/TypeScript está en la hoja de ruta.

Información de Codebase

Codebase Insights documenta cómo se compila cada aplicación. Se generan para Java, .NET y JavaScript/TypeScript. Se muestran al seleccionar Análisis completo en la configuración Cobertura de análisis.

• Arquitectura : diagrama de arquitectura de alto nivel con capas, límites de módulo, topología en tiempo de ejecución y puntos de entrada.
• Contratos de API — interfaces REST, gRPC, colas de mensajes y webhooks que la aplicación expone o consume. Calcula el alcance de la integración antes de la migración.
• Configuración : archivos de configuración, variables de entorno, marcas de características, cadenas de conexión y secretos. Impulsa la migración de secretos y configuración a Azure Key Vault y Azure App Configuration.
• Flujos de trabajo empresariales: flujos funcionales de un extremo a otro reconstruidos a partir del código (por ejemplo, pedir → reservar → pagar → completar). Sirve de base para definir el alcance de la regresión y la comunicación con las partes interesadas.
• Dependencias : bibliotecas directas y transitivas, SDK y controladores con versiones ancladas. Alimenta el mapeo de servicios de Azure y señala versiones fijadas EOL o beta.
• Modelo de datos : bases de datos, esquemas, entidades clave y relaciones de asignaciones ORM y DDL. Impulsa la planificación de la migración del nivel de datos.

Informes

La evaluación por lotes es especialmente valiosa para el planeamiento de la migración, ya que permite evaluar de forma eficaz la preparación y los requisitos de varias aplicaciones a la vez. Mediante la evaluación por lotes, puede evaluar repositorios diferentes al mismo tiempo y obtener informes de evaluación detallados para cada aplicación. Genera dos tipos de informes para apoyar la planificación de la migración:

• Informe por repositorio: proporciona información detallada sobre los dos aspectos identificados en el nivel de repositorio individual.
• Informe agregado: presenta una perspectiva general de todas las aplicaciones evaluadas, ofreciendo información resumida, recomendaciones sobre servicios de Azure, plataformas de destino, rutas de actualización, estrategias de migración y fases de migración. Además, el informe agregado incluye accesos directos para facilitar el acceso a cada informe por repositorio.

La evaluación por lotes proporciona las siguientes ventajas:

• Visibilidad entre aplicaciones:

  • Informes agregados: obtenga una vista completa de las aplicaciones.
  • Análisis entre repositorios: identifique patrones y dependencias comunes entre aplicaciones.
  • Información de priorización: comprenda qué aplicaciones necesitan atención inmediata.

• Escala y eficiencia:

  • Procesamiento paralelo: use agentes en la nube para procesar varios repositorios simultáneamente.
  • Flujos de trabajo automatizados: se integran con canalizaciones de CI/CD para evaluaciones programadas.
  • Ahorro de tiempo: reduzca el tiempo total de evaluación de semanas a horas.

Prerrequisitos

• Modernización de la CLI.
• Acceso a todos los repositorios que desea evaluar.
• GitHub autenticación está configurada (gh auth login).

Configuración de repositorios

El agente de modernización admite varias maneras de especificar los repositorios que desea evaluar:

• Carpeta actual: evalúe el proyecto en el directorio de trabajo actual.
• Entrada manual: escriba directamente rutas de acceso de directorio local o direcciones URL de Git remotas.
• Archivo de configuración del repositorio: use un archivo de configuración JSON que muestre todos los repositorios.

Archivo de configuración del repositorio

Para las operaciones por lotes en muchos repositorios, cree un archivo de configuración JSON para enumerar todos los repositorios. Por ejemplo, créelo en .github/modernize/repos.json en el directorio de trabajo o proporcione una ruta de acceso personalizada.

Asegúrese de tener los permisos adecuados para los repositorios o bifurcarlos.

Formato simple (matriz de repositorios):

[
  {
    "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 (con rutas de acceso locales y de rama):

{
  "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 del repositorio admite los siguientes campos:

Formato completo con la agrupación de aplicaciones (opcional, para informes organizados):

Puede agregar una apps[] sección para agrupar repositorios en aplicaciones lógicas. Cuando se definen las aplicaciones, el informe agregado organiza los resultados por aplicación y admite la distribución de informes a 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 la aplicación admite:

El output campo admite los siguientes tipos de distribución:

El agente de modernización detecta automáticamente el archivo repos.json en .github/modernize/repos.json al seleccionar De un archivo de configuración en modo interactivo. También puede proporcionar una ruta de acceso personalizada.

Ejecución de la evaluación por lotes

Hay dos modos de ejecución disponibles:

• Ejecución local: El agente de modernización procesa los repositorios uno tras otro en el equipo local. Este modo funciona mejor para un conjunto más pequeño de aplicaciones o para pruebas iniciales. Admite la dirección URL de Git y los repositorios de rutas de acceso locales.
• Delegación en agentes de la nube: El agente de modernización envía tareas a los agentes en la nube de GitHub Copilot para su procesamiento en paralelo en la nube. Este modo es más rápido para escenarios de varios repositorios.

Modo interactivo (evaluar localmente)

1. Ejecute el agente de modernización:

   modernize
   

2. Seleccione Evaluar en el menú principal.

   

3. Elija cómo especificar los repositorios de destino. Seleccione Desde un archivo de configuración para usar un repos.json archivo.

   

   Sugerencia

   También puede seleccionar Entrada manual para escribir rutas de acceso locales o direcciones URL remotas de Git directamente o carpeta actual para evaluar el proyecto en el directorio actual.

4. Si el repos.json archivo se detecta en la ubicación predeterminada, el agente lo rellena automáticamente. De lo contrario, escriba la ruta de acceso al archivo de configuración y presione Entrar.

5. Todos los repositorios se seleccionan de forma predeterminada. Anule la selección de los repositorios que quiera omitir y presione Entrar para confirmar la selección.

   • Use las teclas de dirección para navegar y presionar Espacio para alternar repositorios individuales.

   

6. Seleccione los dominios de evaluación que se van a analizar. Upgrade y Cloud Readiness se ejecutan en proyectos de Java y .NET en el repositorio. Security está desactivada de forma predeterminada y se ejecuta solo en proyectos de Java; selecciónela para buscar vulnerabilidades de CVE y problemas de CWE guiados por ISO 5055.

   

7. Revise y configure las opciones de evaluación. En la página de configuración se muestran las opciones agrupadas por idioma y dominio:

   • Cobertura general o de análisis:
     • Solo incidencias (valor predeterminado): detecta incidencias de modernización y de seguridad en el código fuente. Opción más rápida.
     • Análisis completo: detecta problemas y genera además información de código base en seis aspectos de la aplicación: arquitectura, contratos de API, configuración, flujos de trabajo empresariales, dependencias y modelo de datos. Tarda más tiempo en ejecutarse que el análisis de solo problema.
   • Java/ UPGRADE: Tiempo de ejecución de destino (OpenJDK 11, 17, 21 o 25).
   • Java / PREPARACIÓN PARA LA NUBE: Servicios de Cómputo Objetivo, Sistema Operativo Objetivo y Contenerización.
   • Java / SECURITY: gravedad de CVE mínima (low, medium, high, critical; high predeterminado). Entre los valores de gravedad más bajos se incluyen más hallazgos. (el dominio de seguridad es solo Java hoy).
   • .NET /UPGRADE: Plataforma de destino (.NET 8, 9 o 10).
   • .NET/CLOUD READINESS: Target Compute Services.

   Use las teclas de dirección para navegar, presione Entrar para cambiar un valor o seleccione Continuar para continuar con la configuración actual.

   

   Sugerencia

   Los valores predeterminados recomendados funcionan para la mayoría de los escenarios. Solo tiene que cambiar esta configuración si tiene requisitos específicos, como tener como destino una versión de JDK determinada, un servicio de proceso de Azure específico o un umbral de gravedad de CVE diferente.

8. Elija el modo de ejecución. Seleccione Evaluar localmente.

   

9. Escriba la ruta de acceso de salida para los resultados de la evaluación o presione Entrar para aceptar el valor predeterminado.

10. El agente actúa automáticamente:

    • Clona repositorios remotos y usa directamente los de ruta de acceso local.

    • Ejecuta la evaluación en cada repositorio uno por uno.

    • Genera informes de evaluación individuales.

      

    • Crea un informe agregado.

      

11. Cuando finalice la evaluación, el agente abre automáticamente el informe agregado.

    

Modo interactivo (delegación de agentes en la nube)

En primer lugar, configure los agentes en la nube en cada repositorio de aplicaciones. Para configurar agentes en la nube, bifurque los repositorios de ejemplo.

Configuración de aplicaciones de .NET

Configuración para ejecutarse en Windows para aplicaciones de .NET Framework

De forma predeterminada, el agente en la nube de Copilot se ejecuta en un entorno de Ubuntu Linux. Para las aplicaciones .NET Framework, necesita un entorno de Windows. Para habilitarlo, configure .github/workflows/copilot-setup-steps.yaml en la main rama del repositorio de aplicaciones, como se muestra en el ejemplo siguiente:

# 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

Obtenga más información en: Personalización del entorno de desarrollo de Copilot con los pasos de configuración de Copilot

Disable firewall (Deshabilitar firewall)

Deshabilite el firewall integrado del agente en la nube de Copilot en la configuración de su repositorio, como se muestra en la siguiente imagen:

Servidor MCP

Configure el servidor MCP de modernización de GitHub Copilot en la sección Cloud agent de la configuración de su repositorio, como se muestra en el siguiente ejemplo:

{
  "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": ["*"]
    }
  }
}

Configuración de aplicaciones de Java

Configure el servidor MCP de modernización de GitHub Copilot en la sección agente de nube de la configuración de su repositorio, como se muestra en el ejemplo siguiente:

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

Pasos

El flujo interactivo para la delegación en la nube es idéntico a Evaluar localmente a través de los pasos de origen, repositorio, dominio y configuración. La única diferencia es la elección del modo de ejecución y lo que sucede después.

1. Ejecute el agente de modernización:

   modernize
   

2. Seleccione Evaluar en el menú principal, elija el origen (archivo de configuración, entrada manual o carpeta actual), seleccione repositorios, elija los dominios de evaluación y revise la configuración. Estos pasos funcionan exactamente como se describe en modo interactivo (evaluar localmente).

3. Elija el modo de ejecución. Seleccione Delegar en Agentes de la Nube.

   

4. Escriba la ruta de acceso de salida para los resultados de la evaluación o presione Entrar para aceptar el valor predeterminado.

5. El agente delega automáticamente las tareas de evaluación de cada repositorio en agentes en la nube y las ejecuta en la nube en paralelo.

   

   El agente vuelve a extraer los resultados de la evaluación por aplicación en local y genera el informe agregado localmente.

   

6. Cuando finalice la evaluación, el agente abre automáticamente el informe agregado.

Modo no interactivo (CLI)

También puede usar el modo no interactivo especificando los argumentos de comando directamente. Use el comando modernize assess:

Evaluar localmente mediante un archivo de configuración del repositorio:

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

Evalúe varios repositorios especificando orígenes directamente:

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

Evalúe mediante la delegación a agentes en la nube:

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

Para más información, consulte evaluación: comandos de la CLI.

Integración de Azure Migrate

Puede impulsar la evaluación por lotes directamente desde el proyecto de Azure Migrate y hacer que los informes resultantes vuelvan a Azure Migrate automáticamente.

Flujo de un extremo a otro:

1. Descargue un repos.json de inicio desde Azure Migrate. Azure Migrate genera un archivo JSON limitado a las aplicaciones que ha seleccionado para la evaluación de modernización. El archivo ya contiene las entradas apps[] y el bloque output, que remite de nuevo a su proyecto de Azure Migrate.

2. Rellene las direcciones URL del repositorio. Edite cada entrada repos[] en el archivo descargado para agregar la dirección URL del repositorio de GitHub para la aplicación. Mantenga los bloques apps[] y output a medida que Azure Migrate los generó: esos bloques impulsan la carga.

3. Ejecute la evaluación por lotes. Ejecute la evaluación localmente o mediante la delegación en agentes en la nube siguiendo los pasos anteriores. Ambos modos de ejecución respetan la configuración de salida de Azure Migrate.

4. Los informes se cargan automáticamente. Una vez completada la evaluación, el agente de modernización vuelve a cargar el informe de cada aplicación en el proyecto de Azure Migrate. No se requiere ninguna opción adicional de la CLI; la opción output.type del archivo repos.json controla la carga.

Descripción del informe agregado

El informe agregado proporciona una vista completa de las aplicaciones evaluadas de la siguiente manera:

Panel de control

• Instantánea del estado de la cartera: total de aplicaciones, cuántas necesitan actualizaciones y recuentos agregados de bloqueadores y problemas.
• Distribución de tecnología: qué marcos de trabajo están en uso y cuántas aplicaciones las comparten.
• Distribución del esfuerzo: si la migración general es una tarea pequeña o grande.

Recomendaciones

• Azure Services: asigna las dependencias actuales a equivalentes de Azure recomendados. Las dependencias compartidas entre aplicaciones se deciden de manera centralizada, lo que evita la redundancia de trabajo en cada aplicación.
• Target Platform: guía la elección de hospedaje, como Azure Container Apps frente a AKS y expone oportunidades de consolidación.
• Ruta de actualización: identifica qué aplicaciones necesitan actualizaciones de marco como requisito previo, separando el trabajo de actualización del trabajo de migración.
• Cost Estimate: calcula el costo Azure de ejecutar cada aplicación en su destino recomendado, por lo que puede factorizar el gasto en priorización.
• Estrategias de migración: recomienda un enfoque de migración para cada aplicación —por ejemplo, Replatform para migraciones de tipo lift-and-reshape o Rearchitect para una refactorización profunda—, de modo que cada aplicación reciba una estrategia adaptada a su nivel de preparación.
• Oleadas de migración: organiza las aplicaciones en fases según su nivel de preparación y riesgo (por ejemplo, Oleada 1: logros rápidos, Oleada 2: nube principal, Oleada 3: apuestas a largo plazo). Este enfoque permite ganar temprano mientras las aplicaciones más difíciles se preparan en paralelo.

Matriz de evaluación de aplicaciones

• Información general rápida para cada aplicación sobre aspectos del marco de trabajo, la plataforma de destino, la recomendación de actualización, el desglose de problemas (obligatorio, potencial, opcional), el tamaño del esfuerzo, etc.
• Vínculos a informes de aplicaciones individuales para explorar en profundidad cuando sea necesario.

Solución de problemas de evaluación por lotes

Problemas comunes

Errores de acceso al repositorio:

• Compruebe GitHub autenticación mediante gh auth status.
• Asegúrese de que tiene acceso a todos los repositorios enumerados en repos.json.

Errores de clonación:

• Compruebe que las direcciones URL del repositorio en repos.json son correctas y accesibles.
• Asegúrese de que tiene los permisos de acceso adecuados para todos los repositorios.
• Compruebe la conectividad de red y la configuración de VPN.

Errores de evaluación:

• Compruebe si el repositorio contiene proyectos válidos de Java, .NET o JavaScript/TypeScript.
• Compruebe que existen archivos de compilación, como pom.xml, build.gradle, *.csproj, *.sln, *.slnxo package.json.
• Revise los mensajes de error en la salida de la consola. Las advertencias no críticas (por ejemplo, la falta de archivos de compilación en un submódulo) ahora se muestran directamente en la salida de la CLI; revíselos antes de dar el informe por definitivo.

Problemas de delegación del agente en la nube:

• La delegación de agente en la nube solo acepta las direcciones URL del repositorio https://github.com/.... Las rutas de acceso locales y los proveedores que no son de GitHub (GitLab, Azure DevOps) se rechazan por adelantado con un error descriptivo. Use la ejecución local para esos repositorios.
• Asegúrese de que tiene los permisos adecuados para crear flujos de trabajo de Acciones de GitHub.
• Compruebe Acciones de GitHub permisos y límites de cuota para su organización.
• Para aplicaciones de .NET Framework, asegúrese de que la configuración del ejecutor de Windows esté correctamente establecida.
• Compruebe la configuración del servidor MCP.

Pasos siguientes

Después de completar la evaluación por lotes, puede hacer lo siguiente:

Continúe con el flujo de trabajo de modernización:

• Ejecución de la actualización por lotes entre repositorios : aplique actualizaciones coherentes en función de los resultados de la evaluación.

Más información:

• Cree aptitudes personalizadas para patrones específicos de la organización.
• Obtenga información sobre los comandos de la CLI.

Enviar comentarios

¡Tu opinión es importante! Si tiene algún comentario sobre la evaluación por lotes o el agente de modernización, cree un problema en el repositorio github-copilot-appmod o use el formulario de comentarios de modernización GitHub Copilot.