使用 Modernize CLI 產生及使用規則書

規則手冊會以 Markdown 檔案記錄您組織的現代化政策,這些檔案會由 GitHub Copilot 現代化代理程式在評估、規劃與執行時使用。 使用規則手冊定義防護機制、禁止模式、所需應用程式功能、自訂技能強制執行,以及跨應用程式的目標框架與 Azure 服務。

在本文中,您將使用 Modernize CLI 從政策來源檔產生規則手冊,將其儲存在中央 GitHub 儲存庫中,並套用到應用程式的現代化計畫中。

Prerequisites

  • GitHub Copilot 訂閱方案:Free、Pro、Pro+、Business 或 Enterprise。
  • GitHub CLI (gh) 版本 2.45.0 或更新版本。 如需安裝說明,請參閱 GitHub CLI。
  • Modernize CLI 工具 如需安裝說明,請參閱安裝並使用現代化代理程式。
  • 一個用於生成規則書的中央 GitHub 儲存庫。 您需要具備推送至此儲存庫的權限,並在建立現代化計畫時讀取此儲存庫。
  • 目標 .NET 或 Java 應用程式儲存庫的本地複本,具有讀取與寫入權限。
  • 描述您組織現代化政策的 Markdown 檔案。

在繼續之前,請先使用 GitHub 進行驗證:

gh auth login

有關一般平台需求,請參閱 安裝並使用現代化代理程式。

設定規則書

建立私人儲存庫以儲存產生的規則書,或使用現有儲存庫。 在本文中,請以您的 GitHub 組織取代 <org>:

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

將 CLI 指向此儲存庫。 選擇設定檔或環境變數之一。

使用設定檔

若要讓某項設定在終端機工作階段之間持續保留,請將以下屬性新增至您的使用者層級設定檔。 如果檔案已存在,請將此屬性與其現有設定合併,而非替換它。

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

設定檔位置包括:

Scope Location
使用者,Windows %USERPROFILE%\.modernize\config.json
使用者、Linux 或 macOS ~/.modernize/config.json
存儲庫 .github/modernize/config.json

環境變數優先於使用者層級的設定,而使用者層級的設定又優先於儲存庫層級的設定。

使用環境變數

若要設定目前終端機工作階段的規則書儲存庫,請在執行 Modernize CLI 的 shell 中設定 MODERNIZE_PORTFOLIO_URL 。

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

準備政策來源檔案

建立一個名為 agent-rulebook.md 的 Markdown 檔案,說明代理程式在規劃與執行期間應遵循的標準。 包含您所需的目標框架、禁止的模式,以及身份、可觀察性、健康端點、秘密管理和資料庫存取(如適用)的需求。

以下範例說明政策內容。 將其調整以符合貴組織的需求;它不是必須的檔案結構。

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

產生並發佈規則書

從包含您政策來源檔的目錄中,執行以下指令。 使用您為 portfolio_url 或 MODERNIZE_PORTFOLIO_URL 設定的相同儲存庫 URL:

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

此指令將您的來源政策處理成代理程式優化的 Markdown 檔案,並將其推送到中央儲存庫:

File Purpose
charter.md 定義高層次現代化憲章。
targets.md 定義目標框架與平台。
policies.md 定義現代化政策規則。

在使用中央儲存庫中產生的檔案來引導應用程式變更之前,請先檢視這些檔案。 檢查它們是否符合你原始檔案中的需求。

建立使用規則手冊的計畫

在同一已設定的終端機工作階段中,前往您的目標應用程式儲存庫並建立計畫:

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

當您設定中央儲存庫 URL 時,CLI 會自動擷取 charter.md、targets.md 和 policies.md,並將它們作為規劃的上下文。 你不需要在 plan 指令上額外加上 rulebook 選項。

使用預設計畫名稱時,產生的輸出包括:

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

在執行計畫之前,先檢視 plan.md 並 rulebook-compliance.md 檢視。 合規報告會提供逐條規則的涵蓋情況,讓您可以檢查計畫如何符合您的政策。

執行並驗證計畫

在您檢視計畫與合規報告後,請執行:

modernize plan execute

代理程式在執行時會使用您的規則手冊政策。 它執行預定任務、進行程式碼變更、驗證建置、掃描常見漏洞與暴露(CVE),並提交變更。

根據貴組織的政策,檢視產生的程式碼變更和驗證結果。 規則手冊的上下文和產生的合規報告並不能取代你對應用程式的審查。

排除規則書設定問題

如果 CLI 未套用您的規則書,請檢查以下項目:

  • 確認或portfolio_urlMODERNIZE_PORTFOLIO_URL指向您發布生成規則書的資料庫。
  • 檢查是否有會覆寫您的設定檔的環境變數。
  • 如果您使用了環境變數,請從您設定的終端機工作階段執行計畫建立。
  • 確認您已驗證的 GitHub 帳戶在產生並發佈規則書時,能讀取規則書儲存庫並具備寫入權限。
  • 檢視產生的規則手冊檔案及計畫合規報告,以確認哪些政策被代表。