Secret scanning 改进以提醒 API、webhooks 和委托工作流
Source: GitHub Changelog
即将推出的改进
本周我们将推出多项针对 APIs、webhooks 和 delegated workflows 的增强功能。这些更新进一步体现了我们持续致力于提升开发者在秘密扫描功能方面的使用体验。
- APIs – 精简的端点和更清晰的文档。
- Webhooks – 更可靠的投递以及扩展的事件类型。
- Delegated Workflows – 简化的配置和更好的错误处理。
由开发者构建，服务于开发者。
Source: …
有哪些更改 {#whats-changing}
Secret scanning 引入了新的 API 过滤器、更丰富的 webhook 负载，以及对委派警报工作流的改进：
新
exclude_secret_types过滤器
已在 GitHub UI 中可用的排除过滤器（-secret-type:）现在也可以通过 REST API 使用。警报位置的
html_url
警报位置对象现在在 REST API 响应和 webhook 负载中都包含指向相应 GitHub 内容的直接链接（html_url）。委派绕过邮件的改进
- 审核人收到的邮件会显示绕过请求的截止日期。
- 开发者在提交撤销请求后会收到确认邮件。
API / webhook 中的关闭请求评论
请求者的评论、审核人的评论以及审核人的用户名现在都包含在委派关闭的警报负载中。错误修复
当警报通过委派关闭批准方式关闭时，resolution_comment不再为null。
新增 exclude_secret_types API 过滤器
GitHub 经常会添加新的 secret 类型。当你依赖 基于包含 的过滤器时，必须不断更新脚本以处理这些新模式。
使用 排除过滤器，你只需指定不关心的 secret 类型，所有新添加的类型会自动被包含进来。
Secret Scanning Alerts API 现在支持 exclude_secret_types 查询参数。通过它可以在结果中省略特定的 secret 类型，而无需列出所有想保留的类型。
受影响的端点
所有三个列表端点均接受此新参数：
GET /repos/{owner}/{repo}/secret-scanning/alertsGET /orgs/{org}/secret-scanning/alertsGET /enterprises/{enterprise}/secret-scanning/alerts
使用方法
在 exclude_secret_types 查询参数中传入 逗号分隔 的 secret‑type slug 列表。
GET https://api.github.com/orgs/octo-org/secret-scanning/alerts?exclude_secret_types=aws_access_key,slack_token注意： 在同一次请求中同时使用
secret_type和exclude_secret_types会导致 422 Unprocessable Entity 错误。请二选一使用。
警报位置 html_url 字段
Secret scanning 警报位置在 REST API 和 webhook 负载中现在会在 details 对象里包含一个 html_url 字段。
之前，位置详情只返回 API URL（例如 /repos/{owner}/{repo}/issues/comments/{id}），因此如果你在处理 webhook 事件或在位置 API 上构建自动化，就必须额外调用 API 才能获得一个可以实际点击或放入通知中的链接。
现在，面向用户的 URL 已直接包含在内。 该字段是增量的——所有已有的 URL 字段仍然保留。
字段可用位置
- REST API –
GET /repos/{owner}/{repo}/secret-scanning/alerts/{number}/locations - Webhook 负载 – 包含在每个位置的
details对象中
支持的定位类型
| 定位类型 | 示例 html_url（替换占位符） |
|---|---|
commit | /{owner}/{repo}/blob/{sha}/{path}#L5-L5 |
issue_title / issue_body | /{owner}/{repo}/issues/{number} |
issue_comment | /{owner}/{repo}/issues/{number}#issuecomment-{id} |
pull_request_title / pull_request_body | /{owner}/{repo}/pull/{number} |
pull_request_comment | /{owner}/{repo}/pull/{number}#issuecomment-{id} |
pull_request_review | /{owner}/{repo}/pull/{number}#pullrequestreview-{id} |
pull_request_review_comment | /{owner}/{repo}/pull/{number}#discussion_r{id} |
注意： 用你仓库的实际值替换
{owner}、{repo}、{sha}、{path}、{number}、{id}。
html_url 字段为每个警报位置提供了一个可直接点击的链接，简化了自动化和通知工作流。
委派绕过请求的电子邮件通知
我们在委派绕过工作流期间发送的电子邮件通知中添加了两项改进。
1. 过期提醒
针对 bypass 和 dismissal 请求的电子邮件通知现在会包含请求的过期时长，审阅者可以了解在请求自动关闭前还有多少时间可以操作。
| 请求类型 | 过期时长 |
|---|---|
| Push‑protection 绕过 | 7 天 |
| 警报解除（短期） | 30 天 |
| 警报解除（长期） | 1 年 |
之前仅凭邮件无法判断截止日期。
2. 开发者确认邮件
开发者在提交警报解除请求后会收到一封确认邮件，告知该请求 正在等待审阅。
之前：只有审阅者会收到通知，提交者在请求被批准或拒绝之前没有任何反馈。
密码扫描警报负载中的新字段
当警报有委托关闭（解除）请求时，API 和 webhook 负载中会包含另外三个字段：
| Field | Description |
|---|---|
closure_request_comment | 请求者的评论，说明他们为何想关闭该警报。 |
closure_request_reviewer_comment | 审阅者的回复评论。 |
closure_request_reviewer | 审阅者的用户对象。 |
使用场景：跟踪警报被解除的原因、审计审阅者的决定，或与外部工单系统同步——现在可以直接从负载中获取，无需额外查询。
Bug 修复
一个错误导致通过委派的警报关闭批准流程关闭的警报，其 resolution_comment 为 null。请求者的评论被存储在豁免请求中，但未转发到警报。
修复：现在该评论已正确传递到警报的 resolution_comment 字段，行为与通过 REST API 直接驳回时一致。
了解更多
- Secret scanning overview – GitHub Docs
- Secret scanning REST API – GitHub REST API documentation
- Community discussion – 在 GitHub community forum 分享您的想法和反馈