用途
glab-dependency-firewall 是 GitLab CLI（glab）中用于对接 GitLab Dependency Firewall 的命令组，主要做三件事：检查单个包是否符合策略、让受支持的包管理器通过防火墙运行、查看本地记录下来的防火墙活动。使用场景是需要在依赖安装或上传环节执行 GitLab Dependency Firewall 策略时。该命令组被标注为实验性（experimental），官方提示在将其用于持久化自动化之前应先确认可用性。
主要能力
单包检查
当需要对某一个带版本的包坐标获取策略决定、而不运行包管理器时，使用 package 子命令。示例：
glab dependency-firewall package pkg:npm/left-pad@1.3.0 glab dependency-firewall package pkg:pypi/requests@2.31.0 glab dependency-firewall package pkg:maven/org.slf4j/slf4j-api@2.0.13 glab dependency-firewall package pkg:gem/rails@7.1.3
支持的 PURL 类型为 npm、pypi、maven、gem，且 PURL 必须包含版本。退出码含义：0 表示允许或警告，1 表示配置错误或传输失败，3 表示被阻止。警告虽然退出码为 0，也应作为需要人工审查的输入；退出码 3 属于策略结果，不应围绕它重试。该命令不写入 .gitlab/df/ci-log.json，因此其结果不会出现在 ci-summary 中。
受支持的包装器
每个包装器会先解析当前仓库对应的 GitLab 项目并创建 GitLab API 客户端，然后获取该项目的 Dependency Firewall 策略，把剩余参数转发给指定的包管理器二进制文件，对包流量执行策略，并汇总本次运行。项目解析总是在包管理器启动之前执行。包装器使用包管理器已有的 registry、索引或源配置，不会重写这些配置。
当前 glab 对识别出的、内容长度已知的成功包产物采用流式处理，而不是把整个产物缓冲在内存中，覆盖 wheels、crates、tarballs、ZIPs、gems、JARs、WARs、AARs 和 NuGet 包（按扩展名或受支持的二进制内容类型识别）。长度未知、经传输解压、元数据以及非成功响应仍走缓冲路径，以便安全修复 HTTP 帧与头部。应保留包管理器自身的校验和/完整性验证，并把任何部分下载错误视为安装失败。
| glab 命令 | 可执行文件 | 示例 |
|---|---|---|
| bundle | bundle | glab dependency-firewall bundle install |
| gem | gem | glab dependency-firewall gem install rake |
| gradle | gradle | glab dependency-firewall gradle build |
| maven | mvn | glab dependency-firewall maven verify |
| npm | npm | glab dependency-firewall npm ci --ignore-scripts |
| pip | pip | glab dependency-firewall pip install requests |
| pipenv | pipenv | glab dependency-firewall pipenv install requests |
| pnpm | pnpm | glab dependency-firewall pnpm install left-pad |
| poetry | poetry | glab dependency-firewall poetry add requests |
| twine | twine | glab dependency-firewall twine upload dist/* |
| uv | uv | glab dependency-firewall uv pip install requests |
| yarn | yarn | glab dependency-firewall yarn add left-pad |
应在 Git 仓库内运行包装器，且该仓库的 GitLab remote 要能标识出目标项目，并先验证 glab 认证。策略阻止结果应视为权威结果，不要为了绕过该结果而在包装器之外重试。
包装器帮助
包装器名称之后的所有内容都会原样转发给包管理器。包装器命令使用 DisableFlagParsing，因此 glab 标志（如 -h、-R、--repo、--hostname）不会在这里被解析。项目解析和 GitLab API 客户端创建仍会先执行；在非 GitLab remote 仓库或没有有效认证上下文时，glab dependency-firewall <wrapper> --help 会在包管理器能显示帮助之前就失败。
父命令与受支持的包装器
glab dependency-firewall --help glab help dependency-firewall package
不调用包管理器的 glab 包装器帮助
glab help dependency-firewall npm glab help dependency-firewall maven glab help dependency-firewall uv glab help dependency-firewall yarn
在生成文档或自动化时，对每个包装器都应使用 glab help dependency-firewall <wrapper>。不要依赖 glab dependency-firewall <wrapper> --help 来发现包装器。
汇总 CI 活动
ci-summary 读取相对于当前工作目录的 .gitlab/df/ci-log.json。应在产生该日志的包管理器/Dependency Firewall 操作所在的同一目录下运行它。
if glab dependency-firewall ci-summary; then echo "No blocked dependency entries" else rc=$? case "$rc" in 1) echo "Dependency Firewall log could not be read" >&2 ;; 3) echo "Dependency Firewall blocked one or more packages" >&2 ;; *) echo "Unexpected Dependency Firewall failure: $rc" >&2 ;; esac exit "$rc" fi
退出码：
0：没有被阻止的条目；仅允许、仅警告或没有记录到的活动。
1：日志无法读取或解析。
3：一个或多个条目被阻止。
应把退出码 3 当作策略结果，而不是瞬时命令失败。应呈现被阻止的包、版本和原因；不要绕过策略或改写日志。警告虽不会导致命令失败，也应作为审查输入对待。
当前的人类可读汇总在终端支持时使用彩色 Unicode 方框。不要解析该展示格式；自动化应使用退出码和底层日志。
使用方式
- 在 Git 仓库中工作，且该仓库的 GitLab remote 能标识目标项目。
- 先完成 glab 认证。
- 单包检查使用 glab dependency-firewall package <purl>；包管理器场景使用 glab dependency-firewall <wrapper> <参数...>。
- 需要汇总时，在产生 .gitlab/df/ci-log.json 的同一工作目录运行 glab dependency-firewall ci-summary，并依据退出码判断结果。
适用场景
- 在 CI 或本地，对单个包坐标快速获取 Dependency Firewall 策略决定。
- 让 npm、pip、maven、gem 等生态的包管理器安装或上传流量经过 Dependency Firewall 策略执行。
- 读取并汇总 .gitlab/df/ci-log.json 中记录的防火墙活动，判断是否存在被阻止的依赖。
限制与注意事项
- 该命令组为实验性；用于持久化自动化前需确认可用性。
- package 命令不写 ci-log.json，其结果不进入 ci-summary。
- PURL 必须包含版本，仅支持 npm、pypi、maven、gem。
- 包装器在包管理器启动前总会先解析 GitLab 项目并创建客户端，因此对认证和远程仓库有要求。
- 包装器不重写包管理器配置，若使用了错误的 registry/索引/源，应通过包管理器自身的文档化流程修正。
- 包装器命令不解析 glab 标志，包装器名称之后的参数会原样传给包管理器。
- 包装器发现应使用 glab help dependency-firewall <wrapper>，而非 <wrapper> --help。
- ci-summary 依赖相对当前工作目录的 .gitlab/df/ci-log.json；仓库根目录的日志不适用于在嵌套工作区运行的包管理器场景。
- 不要把人类可读的彩色方框汇总当作可解析格式，自动化应使用退出码与底层日志。
- 不要从内部支持代码或相似生态推断出未列出的包装器；应查阅当前父命令帮助与官方文档。
- 策略阻止应视为权威结果，不应在包装器之外重试以绕过；部分下载错误应视为安装失败。
- 参考 references/commands.md 可查看经校验和验证的父命令、包检查、包装器与汇总帮助。