Generieren und Verwenden von Regelbüchern mit der Modernize CLI

Rulebooks halten die Modernisierungsrichtlinien Ihrer Organisation in Markdown-Dateien fest, die der GitHub Copilot Modernisierungsagent bei der Bewertung, Planung und Ausführung verwendet. Verwenden Sie ein Regelbuch, um Leitplanken, verbotene Muster, erforderliche Anwendungsfunktionen, die Durchsetzung benutzerdefinierter Skills sowie Ziel-Frameworks und Azure-Dienste anwendungsübergreifend zu definieren.

In diesem Artikel verwenden Sie die Modernize CLI, um ein Regelbuch aus einer Richtlinienquelldatei zu generieren, sie in einem zentralen GitHub Repository zu speichern und auf den Modernisierungsplan einer Anwendung anzuwenden.

Prerequisites

  • Ein GitHub Copilot-Abonnement: Free, Pro, Pro+, Business oder Enterprise.
  • GitHub CLI (gh) Version 2.45.0 oder höher. Anweisungen zur Installation finden Sie unter GitHub CLI.
  • Die Modernize CLI. Installationsanweisungen finden Sie unter Installieren und Verwenden des Modernisierungs-Agents.
  • Ein zentrales GitHub-Repository für generierte Regelbücher. Sie benötigen die Berechtigung, in dieses Repository zu pushen und es zu lesen, wenn Sie Modernisierungspläne erstellen.
  • Ein lokales Auschecken eines Ziel-.NET oder Java Anwendungs-Repositorys mit Lese- und Schreibberechtigungen.
  • Eine Markdown-Datei, die die Modernisierungsrichtlinien Ihrer Organisation beschreibt.

Authentifizieren sie sich mit GitHub, bevor Sie fortfahren:

gh auth login

Allgemeine Plattformanforderungen finden Sie unter Installieren und Verwenden des Modernisierungs-Agents.

Regelbücher konfigurieren

Erstellen Sie ein privates Repository, um das generierte Regelbuch zu speichern, oder verwenden Sie ein vorhandenes Repository. Ersetzen Sie <org> in diesem Artikel durch Ihre GitHub Organisation:

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

Verweisen Sie die CLI auf dieses Repository. Wählen Sie entweder eine Konfigurationsdatei oder eine Umgebungsvariable aus.

Verwenden einer Konfigurationsdatei

Fügen Sie für eine Einstellung, die über Terminalsitzungen hinweg erhalten bleibt, Ihrer Konfigurationsdatei auf Benutzerebene die folgende Eigenschaft hinzu. Wenn die Datei bereits vorhanden ist, führen Sie diese Property mit den vorhandenen Einstellungen zusammen, anstatt sie zu ersetzen.

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

Die Konfigurationsdateispeicherorte sind:

Geltungsbereich Location
Benutzer, Windows %USERPROFILE%\.modernize\config.json
Benutzer, Linux oder macOS ~/.modernize/config.json
Repository .github/modernize/config.json

Umgebungsvariablen haben Vorrang vor der Konfiguration auf Benutzerebene, die Vorrang vor der Konfiguration auf Repositoryebene hat.

Eine Umgebungsvariable verwenden

Um das Regelbuch-Repository für die aktuelle Terminalsitzung zu konfigurieren, setzen Sie MODERNIZE_PORTFOLIO_URL in der Shell, in der Sie die Modernize CLI ausführen.

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

Richtlinienquelldatei vorbereiten

Erstellen Sie eine Markdown-Datei namens agent-rulebook.md , die die Standards beschreibt, die der Agent während der Planung und Ausführung anwenden sollte. Schließen Sie Ihre erforderlichen Zielframeworks, verbotenen Muster und Anforderungen für Identität, Observability, Health-Endpunkte, Geheimnisverwaltung und Datenbankzugriff ein, sofern zutreffend.

Im folgenden Beispiel wird der Richtlinieninhalt veranschaulicht. Passen Sie es an die Anforderungen Ihrer Organisation an; es ist kein erforderliches Dateischema.

# 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.

Generieren und veröffentlichen Sie ein Regelbuch

Führen Sie den folgenden Befehl in dem Verzeichnis aus, das die Quelldatei Ihrer Richtlinie enthält. Verwenden Sie dieselbe Repository-URL, die Sie für portfolio_url oder MODERNIZE_PORTFOLIO_URL konfiguriert haben:

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

Der Befehl verarbeitet Ihre Quellrichtlinien in agentoptimierte Markdown-Dateien und überträgt sie in das zentrale Repository:

Datei Purpose
charter.md Definiert die allgemeine Modernisierungscharta.
targets.md Definiert Zielframeworks und Plattformen.
policies.md Definiert Richtlinien für die Modernisierung.

Überprüfen Sie die generierten Dateien im zentralen Repository, bevor Sie sie verwenden, um als Grundlage für Anwendungsänderungen zu dienen. Überprüfen Sie, ob sie die Anforderungen in Ihrer Quelldatei widerspiegeln.

Erstellen eines Plans, der das Regelbuch verwendet

Wechseln Sie in derselben konfigurierten Terminalsitzung zum Zielanwendungs-Repository, und erstellen Sie einen Plan:

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

Wenn Sie die zentrale Repository-URL konfigurieren, ruft die CLI automatisch charter.md, targets.md und policies.md ab und verwendet sie als Kontext für die Planung. Sie benötigen keine zusätzliche Regelbuchoption für den Planbefehl.

Mit dem Standardplannamen umfasst die generierte Ausgabe Folgendes:

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

Überprüfen plan.md Und rulebook-compliance.md bevor Sie den Plan ausführen. Der Compliancebericht bietet eine Abdeckung nach einzelnen Regeln, damit Sie überprüfen können, wie der Plan Ihre Richtlinien behandelt.

Führen Sie den Plan aus und überprüfen Sie ihn

Führen Sie nach der Überprüfung des Plans und des Complianceberichts Folgendes aus:

modernize plan execute

Der Agent verwendet Ihre Regelbuchrichtlinien während der Ausführung. Es führt die geplanten Aufgaben aus, nimmt Codeänderungen vor, überprüft Builds, sucht nach Common Vulnerabilities and Exposures (CVEs) und committet Änderungen.

Überprüfen Sie die resultierenden Codeänderungen und Validierungsergebnisse anhand der Richtlinien Ihrer Organisation. Der Regelbuchkontext und ein generierter Compliancebericht ersetzen ihre Überprüfung der Anwendung nicht.

Fehlerbehebung bei der Regelbuchkonfiguration

Wenn die CLI Ihr Rulebook nicht anwendet, überprüfen Sie die folgenden Elemente:

  • Vergewissern Sie sich, dass portfolio_url oder MODERNIZE_PORTFOLIO_URL auf das Repository verweist, in dem Sie das generierte Regelbuch veröffentlicht haben.
  • Suchen Sie nach Umgebungsvariablen, die Ihre Konfigurationsdatei außer Kraft setzen.
  • Wenn Sie Umgebungsvariablen verwendet haben, führen Sie die Planerstellung aus der Terminalsitzung aus, in der Sie sie festlegen.
  • Vergewissern Sie sich, dass Ihr authentifizierter GitHub Konto das Regelbuch-Repository lesen kann und schreibzugriff hat, wenn Sie ein Regelbuch generieren und veröffentlichen.
  • Überprüfen Sie die generierten Regelbuchdateien und den Compliance-Bericht des Plans, um zu prüfen, welche Richtlinien enthalten sind.