Comandos CLI do agente de modernização do GitHub Copilot

O agente de modernização GitHub Copilot fornece modos interativos e não interativos para a modernização de aplicações.

Modos de comando

Modo interativo

Lance a Interface de Utilizador de Texto interativa (TUI) para modernização guiada:

modernize

O modo interativo oferece:

  • Navegação guiada por menus através do fluxo de trabalho de modernização.
  • Seleção flexível de fonte: pasta atual, introdução manual (caminhos locais ou URLs Git) ou ficheiros de configuração de repositório.
  • Plano visual e indicadores de progresso.
  • Prompts guiados para opções de configuração, incluindo domínios de avaliação e parâmetros.
  • Interface de seleção multi-repositório.

Modo não interativo

Executar comandos específicos diretamente para automação e scripting:

modernize <command> [options]

Use o modo não interativo quando:

  • Integração com pipelines CI/CD.
  • Automatizar operações em lote.
  • Workflows de modernização de scripts.
  • Correr em ambientes sem cabeça.

Opções globais

Todos os comandos suportam estas opções globais:

Option Descrição
--help, -h Apresenta informação de ajuda.
--no-tty Desativa os prompts interativos (modo headless).

Comandos

avaliar

Realiza uma avaliação e gera um relatório de análise abrangente.

Sintaxe

modernize assess [options]

Opções

Option Descrição Predefinição
--source <source> Fonte a avaliar (repetível). Aceita caminhos locais, URLs Git ou um caminho de ficheiro de configuração JSON. Use múltiplas --source flags para especificar vários repositórios. . (diretório atual)
--output-path <path> Um caminho de saída personalizado para os resultados da avaliação. .github/modernize/assessment/
--issue-url <url> Um URL de edição do GitHub para atualizar com o resumo da avaliação. Nenhum
--format <format> Formato de saída para relatórios de avaliação: html ou markdown. html
--assess-config <path> Caminho para um ficheiro YAML de configuração de avaliação que sobrepõe parâmetros de avaliação predefinidos, como runtime de alvo, serviços de computação e cobertura de análise. Descoberta automática ou incumprimentos
--model <model> O modelo de LLM a usar. claude-sonnet-4.6
--delegate <delegate> O modo de execução: local (esta máquina) ou cloud (Agente de Codificação na Nuvem). local
--wait Espera que as tarefas delegadas sejam concluídas e gerem resultados (válidos apenas com --delegate cloud). Disabled
--force Força o reinício da delegação, ignorando tarefas em curso (válidas apenas com --delegate cloud). Disabled

Exemplos

Avaliação básica do diretório atual:

modernize assess

Avalie com a localização personalizada da saída:

modernize assess --output-path ./reports/assessment

Avaliar e atualizar o problema do GitHub com os resultados:

modernize assess --issue-url https://github.com/org/repo/issues/123

Avalie o diretório específico de projetos:

modernize assess --source /path/to/project

Avalie múltiplos repositórios usando um ficheiro de configuração:

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 e produza relatórios em formato de marcação:

modernize assess --format markdown

Output

A avaliação gera:

  • Ficheiros de relatório: Análise detalhada em formatos JSON, MD e HTML.
  • Resumo: Principais conclusões e recomendações.
  • Atualizações de edição (se fornecer --issue-url): GitHub comentário de edição com resumo.

Criar o plano

Cria um plano de modernização baseado num enunciado em linguagem natural que descreve os seus objetivos de modernização.

Sintaxe

modernize plan create <prompt> [options]

Argumentos

Argumento Descrição
<prompt> Uma descrição em linguagem natural dos objetivos de modernização (obrigatória).

Opções

Option Descrição Predefinição
--source <path> O caminho para o código-fonte da aplicação. Diretório atual
--plan-name <name> O nome do plano de modernização. modernization-plan
--language <lang> A linguagem de programação (java, dotnet, ou python). Detetação automática
--overwrite Sobrescreve um plano existente com o mesmo nome. Disabled
--model <model> O modelo de LLM a usar. claude-sonnet-4.6

Exemplos

Gerar um plano de migração:

modernize plan create "migrate from oracle to azure postgresql"

Gere um plano de atualização com um nome personalizado:

modernize plan create "upgrade to spring boot 3" --plan-name spring-boot-upgrade

Gerar um plano de implementação:

modernize plan create "deploy the app to azure container apps" --plan-name deploy-to-aca

Exemplo completo de opções:

modernize plan create "upgrade to .NET 8" \
    --source /path/to/project \
    --plan-name dotnet8-upgrade \
    --language dotnet \
    --issue-url https://github.com/org/repo/issues/456

Exemplos enunciados

Atualizações da estrutura:

  • upgrade to spring boot 3
  • upgrade to .NET 10
  • upgrade to JDK 21
  • migrate from spring boot 2 to spring boot 3

Migrações de bases de dados:

  • migrate from oracle to azure postgresql
  • migrate from SQL Server to azure cosmos db
  • switch from MySQL to azure database for mysql

Migrações para a nuvem:

  • migrate from on-premises to azure
  • containerize and deploy to azure container apps
  • migrate from rabbitmq to azure service bus

Implantação:

  • deploy to azure app service
  • deploy to azure kubernetes service
  • set up CI/CD pipeline for azure

Output

O comando gera:

  • Ficheiro do plano (.github/modernize/{plan-name}/plan.md): Estratégia detalhada de modernização incluindo:

    • Contexto e objetivos
    • Abordagem e metodologia
    • Esclarecimentos

  • Lista de tarefas (.github/modernize/{plan-name}/tasks.json): Divisão estruturada das tarefas executáveis com:

    • Descrições de tarefas
    • Competências a usar
    • Critérios de êxito

Sugestão

Podes editar manualmente ambos plan.md e tasks.json depois da geração para personalizar a abordagem antes da execução.

Plano Execução

Executa um plano de modernização criado por modernize plan create.

Sintaxe

modernize plan execute [prompt] [options]

Argumentos

Argumento Descrição
[prompt] As instruções opcionais em linguagem natural para execução (por exemplo, "skip tests").

Opções

Option Descrição Predefinição
--source <path> O caminho para o código-fonte da aplicação. Diretório atual
--plan-name <name> O nome do plano a executar. modernization-plan
--language <lang> A linguagem de programação (java ou dotnet). Detetação automática
--model <model> O modelo de LLM a usar. claude-sonnet-4.6
--delegate <delegate> O modo de execução: local (esta máquina) ou cloud (Agente de Codificação na Nuvem). local
--force Força a execução mesmo quando um trabalho de CCA está em curso. Disabled

Exemplos

Execute o plano mais recente de forma interativa:

modernize plan execute

Execute um plano específico:

modernize plan execute --plan-name spring-boot-upgrade

Execute com instruções extra:

modernize plan execute "skip the test" --plan-name spring-boot-upgrade

Executar em modo headless para CI/CD:

modernize plan execute --plan-name spring-boot-upgrade --no-tty

Comportamento de execução

Durante a execução, o agente:

  1. Carrega o plano: Lê o plano e a lista de tarefas de .github/modernization/{plan-name}/

  2. Executa tarefas: Processa cada tarefa na lista de tarefas sequencialmente:

    • Aplica transformações de código.
    • Valida builds após alterações.
    • Exames para CVEs.
    • Alterações de commits com mensagens descritivas.

  3. Gera um resumo: Fornece um relatório de todas as alterações e resultados.

Output

  • Histórico de commits: Commits detalhados para cada tarefa executada.
  • Relatório resumo: Visão geral das mudanças, sucessos e quaisquer problemas encontrados.
  • Validação da build: Confirmação de que a aplicação é construída com sucesso.
  • Relatório CVE: Vulnerabilidades de segurança identificadas e abordadas.

actualização

Executa um fluxo de trabalho de atualização de ponta a ponta – planear e executar – num único comando.

Sintaxe

modernize upgrade [prompt] [options]

Argumentos

Argumento Descrição
[prompt] A versão alvo, como Java 17, Spring Boot 3.2, .NET 10. Por defeito é o LTS mais recente.

Opções

Option Descrição Predefinição
--source <source> Fonte a atualizar (repetível). Aceita caminhos locais, URLs Git ou um caminho de ficheiro de configuração JSON. Use múltiplas --source flags para especificar vários repositórios. . (diretório atual)
--delegate <delegate> O modo de execução: local (esta máquina) ou cloud (Agente de Codificação na Nuvem). local
--model <model> O modelo de LLM a usar. claude-sonnet-4.6

Exemplos

Execute upgrade no diretório atual:

modernize upgrade "Java 17"

modernize upgrade ".NET 10"

Executa upgrade num projeto específico:

modernize upgrade "Java 17" --source /path/to/project

Executa upgrade usando o Cloud Coding Agent:

modernize upgrade "Java 17" --delegate cloud

Atualize múltiplos repositórios usando um ficheiro de configuração:

modernize upgrade "Java 21" --source .github/modernize/repos.json

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

modernize upgrade "Java 21" --source https://github.com/org/repo1 --source https://github.com/org/repo2

help

Fornece comandos de ajuda e informação.

Sintaxe

modernize help [command]

Comandos

Comando Descrição
models Lista modelos LLM disponíveis e os seus multiplicadores.

Exemplos

Lista de modelos disponíveis:

modernize help models

Configurar a CLI

Ao usar o agente de modernização, pode personalizar o comportamento da aplicação através de ficheiros JSON e variáveis de ambiente.

Variáveis de ambiente

Defina as variáveis de ambiente para sobrepor todos os outros escopos de configuração:

Variable Descrição Predefinição
MODERNIZE_LOG_LEVEL O nível de registo (none, error, warning, info, debug, ) all info
MODERNIZE_MODEL O modelo de LLM a usar. claude-sonnet-4.6
MODERNIZE_COLLECT_TELEMETRY Ativar ou desativar a recolha de telemetria. true

Exemplo: 

export MODERNIZE_LOG_LEVEL=debug
export MODERNIZE_MODEL=claude-sonnet-4.6
modernize assess

Configuração de utilizador

Armazene as preferências específicas do utilizador ou ~/.modernize/config.json definições de repositório em .github/modernize/config.json.

{
  "model": "claude-sonnet-4.6",
  "log_level": "info",
  "trusted_folders": [
    "/path/to/trusted/project",
  ]
}

A trusted_folders propriedade especifica as pastas que são de confiança para usar LLM em modo interativo.

Observação

As variáveis de ambiente têm a maior prioridade, seguidas pela configuração do utilizador e, em seguida, pela configuração do repositório. Use variáveis de ambiente para sobrescrições CI/CD e configuração do utilizador para preferências pessoais.

Configuração multi-repositório

Pode fornecer múltiplas fontes ao CLI de várias formas:

  • Ficheiro de configuração do repositório: Crie um .github/modernize/repos.json ficheiro que liste todos os repositórios e depois passe com --source.
  • Múltiplos --source flags: Especifique caminhos locais ou URLs Git diretamente na linha de comandos.
  • Modo interativo: Selecione as fontes através da TUI (pasta atual, entrada manual ou configuração do repositório).

Ficheiro de configuração do repositório

Crie um .github/modernize/repos.json ficheiro para definir a sua lista de repositórios. A configuração suporta dois formatos:

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"
  }
]

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:

Campo Descrição Obrigatório
name Um nome amigável para o repositório. Sim
url URL clone do git (HTTPS ou SSH). Um de url ou path
path Caminho de diretório local absoluto. Um de url ou path
branch Faz um ramo para verificar depois da clonagem. No
description Descrição legível para humanos. No

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.

{
  "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:

Campo Descrição Obrigatório
identifier Nome de exibição único da aplicação. Sim
description Descrição legível para humanos. No
repos Lista de nomes de repositórios que pertencem a esta aplicação. Sim
output Onde distribuir o relatório de avaliação desta aplicação após a geração. No

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

Tipo Descrição Campos obrigatórios
local Copiar os relatórios para um diretório local. path
git Envie relatórios para um repositório Git. Formato URL: https://github.com/org/repo.git#branch:path. url

Importante

A delegação do Cloud Coding Agent (--delegate cloud) exige que os repositórios tenham URLs de repositório GitHub (github.com) . Repositórios de caminhos locais e fornecedores não-GitHub (GitLab, Azure DevOps) não são suportados para delegação na cloud e são ignorados.

Depois, use --source para passar o caminho do ficheiro de configuração:

Avalie todos os repositórios localmente:

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

Avalie todos os repositórios utilizando o Cloud Coding Agent:

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

Atualize todos os repositórios usando o Cloud Coding Agent:

modernize upgrade --source .github/modernize/repos.json --delegate cloud

Múltiplas fontes na linha de comandos

Também pode especificar várias fontes diretamente:

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

modernize upgrade "Java 21" --source ./project-a --source ./project-b

Passos seguintes

  • Last updated on