在 CI/CD 流水线中使用 Regal 对 Rego 策略进行代码检查-平芜编程栈

后端
认证鉴权
云原生

【免费下载链接】opa

Open Policy Agent (OPA) is an open source, general-purpose policy engine.

项目地址：https://gitcode.com/gh_mirrors/op/opa

Regal 是 Open Policy Agent 生态中专门用于 Rego 策略代码的 linter 与语言服务器，其核心价值之一就是可以被无缝嵌入 GitHub Actions、GitLab CI/CD 等主流构建流水线，让策略质量检查与普通代码检查一样自动、可重复、可审计。本文以 docs/projects/regal/cicd.md 为骨架，完整覆盖 GitHub Actions 与 GitLab CI/CD 两种落地方式，并结合 CLI 文档、配置文档、自动修复文档与架构文档补充输出格式、退出码、severity 级别等关键细节，帮助你从零搭建一套可运行的策略 lint 流水线。

为什么要把 Regal 放进构建流水线

策略代码（Rego）与普通代码一样存在 bug、风格问题和反模式。Regal 通过将每个 Rego 文件解析为抽象语法树（AST），再把 AST 转成 JSON 作为input提供给用 Rego 编写的 lint 规则进行求值——即"用 Rego 来 lint Rego"（详见 architecture.md）。这意味着：

检查逻辑完全规则化、可解释，每条违规都有对应的规则文档说明原因与修法；
结果可输出为多种机器可读格式（JSON、SARIF、JUnit、GitHub workflow command），天然适配不同 CI 平台；
退出码可控（--fail-level），可以在"警告不阻断"与"任何违规即失败"之间灵活选择。

在 CI/CD 中运行 Regal，可以让团队在每次提交或合并请求时自动获得策略代码的质量反馈，并强制规则一致性。

在 GitHub Actions 中运行 Regal

官方提供了open-policy-agent/setup-regal这个 Action 用于在 GitHub Actions 环境中安装指定版本的 Regal。官方推荐的做法是：先用actions/checkout检出代码，再用setup-regal安装 Regal，最后执行regal lint。

以下是一个可直接使用的.github/workflows/lint.yml示例（假设policy目录下存放 Rego 文件），它在每次 pull request 时运行：

name: Regal Lint on: pull_request: jobs: lint-rego: runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 - uses: open-policy-agent/setup-regal@v2 with: # 生产环境建议固定到具体版本，如 v0.22.0 version: latest - name: Lint run: regal lint --format=github ./policy

关键点解读：

固定版本：setup-regal的version参数默认可写latest，但为了构建可复现、避免上游更新带来意外违规，生产流水线应固定到具体版本（例如v0.22.0）。
--format=github：这是 GitHub Actions 的推荐输出格式。它输出 GitHub 的 workflow command，可以直接在 PR 上标注违规位置，并生成 job summary 汇总 lint 报告（见 CLI 文档）。
指定目标目录：regal lint ./policy只检查策略目录，避免误扫仓库内其他文件。

setup-regal还支持更多安装选项（如指定安装路径、架构等），具体可查看其仓库文档；在 GitHub Actions 之外，它也常被用于其他基于虚拟机的 CI 平台。

在 GitLab CI/CD 中运行 Regal

GitLab 上最常见的做法是直接使用官方 Docker 镜像ghcr.io/open-policy-agent/regal:latest，配合junit输出格式把 lint 结果嵌入合并请求（MR）的测试报告中。

以下.gitlab-ci.yml中的 stage 示例会在合并请求被创建或更新时，对policy目录运行 Regal：

regal_lint_policies: stage: regal-lint image: # 生产环境建议固定到具体版本，如 v0.22.0 name: ghcr.io/open-policy-agent/regal:latest entrypoint: ['/bin/sh', '-c'] script: - regal lint ./policy --format junit > regal-results.xml artifacts: reports: junit: regal-results.xml when: always rules: - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

要点说明：

镜像与 entrypoint：entrypoint: ['/bin/sh', '-c']覆盖镜像默认入口，保证script中的 shell 命令可以正常执行。
--format junit：将 lint 报告导出为 JUnit XML（见 CLI 文档的输出格式列表），GitLab 会把 JUnit 报告渲染为 MR 中的测试报告，直接展示违规内容。
artifacts.reports.junit+when: always：即使 lint 失败也保留报告，方便开发者在 MR 页面查看全部违规，而不是只看到流水线红了。
rules：仅当流水线来源是merge_request_event时才运行，避免在普通分支推送或定时流水线上重复执行。

输出格式与 CI 平台匹配

regal lint通过--format指定输出格式，选择与 CI 平台匹配的格式能获得最佳体验。完整格式列表见 CLI 文档：

格式	适用场景
`pretty`（默认）	人读的表格式输出，每条违规附详细解释，适合本地开发
`compact`	每条违规单行输出的人读格式
`json`	结构化输出，适合程序化消费（如后续脚本处理、上报平台）
`github`	GitHub workflow command 输出，可在 PR 上标注并生成 job summary，专用于 GitHub Actions
`sarif`	SARIF JSON 格式，供代码分析类工具（如 GitHub Code Scanning 等）消费
`junit`	JUnit XML 输出，适合 GitLab 等在 MR 中展示测试报告的 CI 平台

因此：GitHub 用github，GitLab 用junit，需要二次处理用json或sarif。

退出码与失败策略：用 --fail-level 控制流水线

CI 中 lint 命令的退出码决定流水线是否失败。regal lint的默认行为与--fail-level选项如下（完整说明见 CLI 文档）：

默认--fail-level error时：

0：未发现 error
0：发现一个或多个 warning（不阻断）
3：发现一个或多个 error（阻断）

指定--fail-level warning时：

0：未发现 error 或 warning
2：发现一个或多个 warning（阻断）
3：发现一个或多个 error（阻断）

这意味着：如果团队暂时只希望"错误级别"阻断流水线、让 warning 仅作提示，保持默认即可；如果希望零容忍，则在 CI 命令中追加--fail-level warning。

与之配套的是配置文档中的规则 severity 设置——每个规则可在.regal/config.yaml或.regal.yaml中设为ignore（完全禁用）、warning（报告但不改变退出码）或error（报告且非零退出码，默认）。例如：

rules: style: todo-comment: level: ignore line-length: max-line-length: 100 level: warning opa-fmt: level: error

配置文件的查找规则：Regal 会在当前目录查找.regal/config.yaml或.regal.yaml，找不到则逐级向上遍历父目录，仍找不到则回退到~/.config/regal/config.yaml，最后使用默认配置。也可以在 CI 命令中显式指定：regal lint --config-file .regal/config.yaml ./policy。建议把配置文件提交到仓库，这样团队共享同一套规则，CI 中运行的也是这份配置。

结合 OPA 自身检查：opa check --strict

Regal 的 CLI 文档明确建议：在 Regal lint 之前先运行 OPA 自带的opa check --strict。它除了检查 Rego 语法错误，还会检查 OPA strict mode 违规；OPA 1.0 之后大部分 strict mode 检查已成为默认检查，--strict额外提供两个 Regal 未覆盖的重要检查。因此推荐的 CI 检查组合是：

opa check --strict ./policy regal lint --format=github ./policy

两条命令都通过后再视为策略检查通过。

轻量替代方案：pre-commit hooks

如果不想为 CI 单独写 stage，也可以在本地开发阶段用 pre-commit）。在.pre-commit-config.yaml中加入：

- repo: https://github.com/open-policy-agent/regal rev: v0.7.0 # 指向你需要的版本 ref hooks: - id: regal-lint

可用的 hook 包括：

regal-lint/regal-lint-use-path/regal-download：对暂存的.rego文件运行regal lint，失败则中止提交；三种变体分别对应"构建安装指定版本""使用$PATH中已有的 regal""直接下载最新二进制"。
regal-fix/regal-fix-use-path/regal-fix-download：对暂存文件运行regal fix，自动就地修复可自动修复的违规，适合与regal-lint搭配使用。

pre-commit 适合作为 CI 的前置防线，而 CI 流水线仍应独立运行一遍 lint，确保绕过本地 hook 的提交也能被拦截。

在 CI 中使用 regal fix 自动修复

部分规则支持自动修复（详见 fixing.md），例如opa-fmt、use-assignment-operator、directory-package-mismatch、use-rego-v1等。CI 中的典型用法是：先regal fix --dry-run预览改动，再实际执行修复并让开发者 review diff。由于部分修复会移动文件（如directory-package-mismatch会根据 package 路径调整文件目录），建议在 CI 中将修复结果作为可审查的改动提交，而不是直接覆盖主干。

regal fix --dry-run ./policy # 先预览 regal fix ./policy # 确认后执行

注意：regal fix遵循与regal lint相同的配置（被设为ignore的规则同样不会被修复），且所有路径相对于最近的project root解析；复杂多 root 项目可参考 project-roots 文档配置。

完整落地示例：一套可复制的流水线

结合以上内容，一个生产可用的 GitHub Actions 流水线可以是这样：

name: Rego Policy Checks on: pull_request: push: branches: [main] jobs: lint-and-check: runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 - uses: open-policy-agent/setup-regal@v2 with: version: v0.22.0 - name: OPA strict check run: opa check --strict ./policy - name: Regal lint run: regal lint --format=github --fail-level warning ./policy

该流水线同时覆盖了语法/strict 检查、Regal 规则检查（warning 级别即失败），并在 PR 上直接标注违规位置。对应地，GitLab 版本把--format=github换成--format junit并配合 JUnit artifacts 即可。

小结

GitHub Actions：使用open-policy-agent/setup-regal安装 Regal，--format=github输出可直接标注 PR 并生成 job summary。
GitLab CI/CD：使用官方镜像ghcr.io/open-policy-agent/regal:latest，--format junit配合 artifacts 在 MR 中展示违规报告。
失败策略：理解--fail-level error（默认，warning 不阻断）与--fail-level warning（warning 即失败）的退出码语义，再结合配置文件中的 severity 级别统一团队规则。
检查组合：先opa check --strict，再regal lint，两条命令分别覆盖 OPA strict 检查与 Regal 规则检查。
扩展手段：pre-commit hooks 做本地前置防线，regal fix --dry-run在 CI 中预览自动修复。