Générer et utiliser des règles avec l’interface CLI Moderniser

Les règles capturent les stratégies de modernisation de votre organisation dans les fichiers Markdown utilisés par l'agent de modernisation GitHub Copilot lors de l'évaluation, de la planification et de l'exécution. Utilisez un rulebook pour définir des garde-fous, des modèles interdits, des fonctionnalités d’application requises, une mise en œuvre des compétences personnalisées et des frameworks cibles et des services Azure entre les applications.

Dans cet article, vous utilisez l'interface CLI Moderniser pour générer un livre de règles à partir d'un fichier source de stratégie, le stocker dans un référentiel de GitHub central et l'appliquer au plan de modernisation d'une application.

Prerequisites

  • Un abonnement GitHub Copilot : Gratuit, Pro, Pro+, Entreprise ou Entreprise.
  • GitHub CLI (gh) version 2.45.0 ou ultérieure. Pour obtenir des instructions d’installation, consultez les instructions d’installation de GitHub CLI.
  • Le CLI Modernize. Pour obtenir des instructions d’installation, consultez Installer et utiliser l’agent de modernisation.
  • Référentiel GitHub central pour les recueils de règles générés. Vous devez être autorisé à envoyer (push) à ce référentiel et à le lire lorsque vous créez des plans de modernisation.
  • Copie locale d’un dépôt d’application .NET ou Java cible, avec des autorisations de lecture et d’écriture.
  • Fichier Markdown décrivant les stratégies de modernisation de votre organisation.

Authentifiez-vous avec GitHub avant de continuer :

gh auth login

Pour connaître les exigences générales de la plateforme, consultez Installation et utilisation de l’agent de modernisation.

Configurer des recueils de règles

Créez un dépôt privé pour stocker le rulebook généré ou utilisez un dépôt existant. Remplacez <org> par votre organisation GitHub tout au long de cet article :

gh repo create <org>/modernize-rulebooks --private

Pointez l’interface CLI vers ce référentiel. Choisissez un fichier de configuration ou une variable d’environnement.

Utiliser un fichier de configuration

Pour un paramètre qui persiste entre les sessions de terminal, ajoutez la propriété suivante à votre fichier de configuration au niveau de l’utilisateur. Si le fichier existe déjà, fusionnez cette propriété avec ses paramètres existants plutôt que de la remplacer.

{
  "portfolio_url": "https://github.com/<org>/modernize-rulebooks"
}

Les emplacements des fichiers de configuration sont les suivants :

Scope Location
Utilisateur, Windows %USERPROFILE%\.modernize\config.json
Utilisateur, Linux ou macOS ~/.modernize/config.json
Référentiel .github/modernize/config.json

Les variables d’environnement sont prioritaires sur la configuration au niveau de l’utilisateur, qui est prioritaire sur la configuration au niveau du dépôt.

Utiliser une variable d’environnement

Pour configurer le référentiel de rulebooks pour la session de terminal actuelle, définissez MODERNIZE_PORTFOLIO_URL dans l’interpréteur de commandes où vous exécutez la CLI Modernize.

$env:MODERNIZE_PORTFOLIO_URL = "https://github.com/<org>/modernize-rulebooks"

Préparer un fichier source de stratégie

Créez un fichier Markdown nommé agent-rulebook.md qui décrit les normes que l’agent doit appliquer pendant la planification et l’exécution. Incluez vos frameworks cibles requis, les modèles interdits et les exigences pour l’identité, l’observabilité, les points de terminaison de santé, la gestion des secrets et l’accès aux bases de données, le cas échéant.

L’exemple suivant illustre le contenu de la stratégie. Adaptez-la aux exigences de votre organisation ; ce n’est pas un schéma de fichier requis.

# Modernization policies

## Target platform

- Migrate the application to Azure Container Apps.

## Identity and secrets

- Use managed identities for Azure service access where supported.
- Don't commit credentials or connection secrets to source control.

## Application operations

- Provide health endpoints for the application.
- Include application telemetry without logging secrets or personal data.

## Validation

- Build the application and run its tests after code changes.

Générer et publier un recueil de règles

Dans le répertoire contenant votre fichier source de stratégie, exécutez la commande suivante. Utilisez la même URL de référentiel que celle que vous avez configurée pour portfolio_url ou MODERNIZE_PORTFOLIO_URL:

modernize rulebook create --file-path ./agent-rulebook.md --push-git-url https://github.com/<org>/modernize-rulebooks

La commande traite vos stratégies sources en fichiers Markdown optimisés par l’agent et les envoie (push) au référentiel central :

Fichier Purpose
charter.md Définit la charte de modernisation de haut niveau.
targets.md Définit des frameworks et des plateformes cibles.
policies.md Définit des règles de politique pour la modernisation.

Passez en revue les fichiers générés dans le référentiel central avant de les utiliser pour guider les modifications de l’application. Vérifiez qu’ils reflètent les exigences dans votre fichier source.

Créer un plan qui utilise le rulebook

Dans la même session de terminal configurée, accédez à votre référentiel d’applications cible et créez un plan :

cd /path/to/your-app
modernize plan create "migrate to Azure Container Apps"

Lorsque vous configurez l’URL du référentiel central, l’interface CLI récupère charter.mdautomatiquement, targets.mdet policies.md les utilise comme contexte pour la planification. Vous n’avez pas besoin d’une option rulebook supplémentaire sur la commande de plan.

Avec le nom du plan par défaut, la sortie générée inclut :

.github/modernize/modernization-plan/
    plan.md
    rulebook-compliance.md
    .metadata/
        tasks.json
        rulebook-metadata.json

Passez en revue plan.md et rulebook-compliance.md avant d’exécuter le plan. Le rapport de conformité fournit une couverture de règle par règle pour vous permettre de vérifier la façon dont le plan traite vos politiques.

Exécuter et valider le plan

Après avoir examiné le rapport de planification et de conformité, exécutez :

modernize plan execute

L’agent applique les règles de votre référentiel pendant l’exécution. Il exécute les tâches planifiées, apporte des modifications de code, valide les builds, analyse les Common Vulnerabilities and Exposures (CVE) et commit les modifications.

Passez en revue les modifications de code obtenues et les résultats de validation par rapport aux politiques de votre organisation. Le contexte du livre de règles et un rapport de conformité généré ne remplacent pas votre révision de l’application.

Dépannage de la configuration du rulebook

Si l’interface CLI n’applique pas votre rulebook, vérifiez les éléments suivants :

  • Confirmez que portfolio_url ou MODERNIZE_PORTFOLIO_URL pointe vers le référentiel où vous avez publié le livre de règles généré.
  • Recherchez les variables d’environnement qui prennent le pas sur votre fichier de configuration.
  • Si vous avez utilisé des variables d’environnement, exécutez la création d’un plan à partir de la session de terminal où vous les avez définies.
  • Vérifiez que votre compte GitHub authentifié peut lire le référentiel de règles et dispose d’un accès en écriture lorsque vous générez et publiez un rulebook.
  • Passez en revue les fichiers du rulebook générés et le rapport de conformité du plan pour vérifier quelles politiques sont représentées.