连接你的管道

扫描器在你的代理或运行器上运行。任务或 Action 收集它们的 SARIF，将其发送到你的工作区，并读取关卡结果。

1. 生成接入令牌

所有者或管理员打开 Pipeline 页面，输入令牌名称，然后选择“生成接入令牌”。令牌只显示一次。请将其存为 Azure Pipelines 中的机密变量 GUARDRAIL_TOKEN，或 GitHub 上的仓库机密 GUARDRAIL_INGEST_TOKEN。

2. 安装四个扫描器

Trivy、Gitleaks、Checkov 和 Opengrep 必须位于代理或运行器的 PATH 中。任务不会安装它们。

3a. Azure DevOps

在 Pipeline 页面，输入你的 Azure DevOps 组织名称（即 dev.azure.com/<organisation> 中的名称），然后选择“与此组织共享扩展”。
打开此处出现的 Marketplace 链接，选择“免费获取”并选择组织。安装需要在该组织中管理扩展的权限。在扩展共享之前，不会显示该链接。
将该步骤添加到 azure-pipelines.yml，并在拉取请求上运行管道。

- task: GuardrailLedgerScan@0
  inputs:
    guardrailUrl: 'https://<workspace>.guardrail-ledger.com'
    ingestToken: '$(GUARDRAIL_TOKEN)'
  env:
    SYSTEM_ACCESSTOKEN: $(System.AccessToken)

env 这一行使任务可以在拉取请求上评论关卡结果。项目的构建服务身份还需要在该仓库上拥有“参与拉取请求”（Contribute to pull requests）权限。

3b. GitHub Actions

在 Pipeline 页面，下载 action.yml 和 index.js。将它们分别提交为 .github/actions/guardrail-ledger/action.yml 和 .github/actions/guardrail-ledger/dist/index.js。
添加 Pipeline 页面显示的工作流。它会安装扫描器，然后用你的工作区地址和机密 GUARDRAIL_INGEST_TOKEN 运行该 Action。
对来自仓库内分支的拉取请求运行扫描。对于来自 fork 的拉取请求，GitHub 不会给作业提供任何机密。

作业需要以下权限，Action 才能读取代码并在拉取请求上评论：

permissions:
  contents: read
  pull-requests: write

其他 CI

任何能写出 SARIF 的 CI 都可以将其发送到你的工作区。请求体是包含 repo 和 sarif 的 JSON，令牌放在 Bearer 请求头中。

curl -sS -X POST 'https://<workspace>.guardrail-ledger.com/api/v1/ingest/sarif' \
  -H "Authorization: Bearer $GUARDRAIL_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"repo":"example-repo","sarif":{"version":"2.1.0","runs":[...]}}'

扫描器失败时

当扫描器缺失、崩溃、以错误退出或没有写出可用的 SARIF 时，该步骤会失败，并指明是哪个扫描器。此时不会发送任何内容。要继续运行其他扫描器，请在 Azure DevOps 任务上设置 allowMissingScanners: true，或在 Action 上设置 allow-missing-scanners: true。这次运行随后会作为不完整的运行发送，因此不会据此解决任何发现，关卡也不会因缺失的部分而通过。

发送的内容

任务发送扫描器的 SARIF 结果、仓库名称、提交、拉取请求编号、运行构建的人员的登录名，以及 AI 工具文件（例如 AGENTS.md 或 mcp.json）的路径。它在发送前会从 SARIF 中删除代码片段和上下文行。它不会上传仓库。扫描器输出写入代理的临时目录（位于源代码之外），读取后即被删除。