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 文件和计划的符合性报告,以查看包含了哪些策略。