通过 Modernize CLI 生成和使用规则手册

Rulebook 在 Markdown 文件中记录组织的现代化策略,GitHub Copilot 现代化代理在评估、规划和执行期间使用该策略。 使用规则手册可跨应用程序定义护栏、禁止模式、所需的应用程序功能、自定义技能实施以及目标框架和Azure服务。

在本文中,你将使用新式 CLI 从策略源文件生成规则手册,将其存储在中央GitHub存储库中,并将其应用于应用程序的现代化计划。

Prerequisites

  • GitHub Copilot订阅:免费版、专业版、专业增强版、商业版或企业版。
  • GitHub CLI(gh)版本 2.45.0 或更高版本。 有关安装说明,请参阅 GitHub CLI。
  • Modernize CLI。 有关安装说明,请参阅 安装和使用现代化代理。
  • 生成的规则手册的中心GitHub存储库。 你需要有权向此存储库推送,并在创建现代化计划时读取它。
  • 目标 .NET 或 Java 应用程序存储库的本地检出副本,并具有读取和写入权限。
  • 描述组织现代化策略的 Markdown 文件。

在继续之前,先使用GitHub进行身份验证:

gh auth login

有关常规平台要求,请参阅 安装和使用现代化代理。

配置规则手册

创建私有存储库来存储生成的规则手册,或使用现有存储库。 将本文中的 <org> 全部替换为你的 GitHub 组织:

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

环境变量优先于用户级配置,该配置优先于存储库级配置。

使用环境变量

若要为当前终端会话配置 rulebook 存储库,请在运行 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 文件中,并将其推送到中央存储库:

文件 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

代理在执行期间使用 rulebook 策略。 它运行计划的任务,进行代码更改,验证生成,扫描常见漏洞和暴露(CVE),并提交更改。

依据贵组织的政策审查生成的代码更改和验证结果。 Rulebook 上下文和生成的符合性报告不会替换对应用程序的评审。

Rulebook 配置疑难解答

如果 CLI 未应用规则手册,请检查以下项:

  • 确认 portfolio_url 或 MODERNIZE_PORTFOLIO_URL 指向你发布所生成 rulebook 的存储库。
  • 检查会覆盖配置文件设置的环境变量。
  • 如果使用了环境变量,请在设置这些变量的终端会话中运行计划创建。
  • 确认经过身份验证的GitHub帐户可以读取 rulebook 存储库,并在生成和发布规则手册时具有写入访问权限。
  • 查看生成的 rulebook 文件和计划的符合性报告,以查看包含了哪些策略。