原文核对：2026-10-13 · 中文正文 · 英文提示词与演示
场景定位
将 Codex Security CLI 接入 CI，设置扫描时机和代码范围，保留发现与覆盖信息，并决定结果如何影响交付。
- 难度
- 中级
- 时间跨度
- 长时间运行
适合用于
- 为拉取或合并请求增加安全检查的团队。
- 在改动合入后扫描默认分支的维护者。
- 定期评估仓库的安全团队。
把安全扫描纳入开发流程：在拉取请求、改动进入默认分支后，或按固定周期运行 Codex Security。为不同触发条件选择合适范围，保留发现和覆盖信息，建立可重复的结果审阅方式。
选择扫描时机
先从一个适合团队流程的触发条件开始。了解扫描耗时、成本和团队如何使用结果后，再增加其他触发条件。
| 运行时机 | 建议范围 | 帮助审阅的内容 |
|---|---|---|
| 定期运行 | 整个仓库，也可使用深度扫描 | 按固定周期评估更广泛的代码库。 |
| 提交到 main 时 | 推送提交对应的整个仓库 | 改动进入默认分支后的集成代码。 |
| 拉取或合并请求时 | 合并基点到拟合入提交之间的变更 | 合并前可能引入的安全回归。 |
如果默认分支不叫 main，请使用实际名称。触发条件和扫描范围都需要配置：拉取请求差异扫描只覆盖该改动，不覆盖整个仓库；改动进入 main 后的扫描无法阻止已经合并的拉取请求。
开始之前
你需要获准评估的仓库、配置其 CI 流水线和密钥的权限，以及具有 Codex Security 访问权限的 OpenAI API 密钥。按照 CLI 快速入门检查访问与设置要求。
使用符合 CI 要求的可信运行器。扫描使用运行器的本地权限执行。不要在扫描作业中放入无关凭据，并遵守平台对来自 fork 的拉取请求及其他不可信代码的限制。
配置流水线
- 将 Codex Security 加入流水线：选择对应 CI 平台的示例，安装 CLI，并通过 CI 提供方的密钥存储注入 API 密钥。GitHub Actions 可从拉取请求工作流开始，扫描拟合入改动并保存结果；GitLab CI/CD 指南涵盖合并请求、默认分支和定期扫描，提供可下载流水线并说明应启用的选项；其他平台可改编“在 CI 中运行 Codex Security”中的扫描与导出命令，适配触发条件、密钥存储、代码检出和产物管理。
- 配置触发条件和范围：改动进入 main 时扫描推送提交的整个仓库，也可对指定分支定期扫描。每周一次可作为起点，再按仓库活跃度、耗时和成本调整。拉取或合并请求应获取基线与目标提交的历史，从合并基点扫描已提交差异。确保定期扫描和 main 提交扫描整个仓库，拉取请求扫描拟合入改动；具体配置遵循平台示例。按范围与频率设置预算。全仓扫描可能比差异扫描更慢、更贵；--max-cost 是估算成本限制，不是硬性支出上限，触及限制可能导致覆盖不完整。
- 运行并审阅：按正常审阅流程提交流水线改动，然后触发扫描。在运行记录和 scan-manifest.json 中确认目标版本与范围。检查已保存报告中的发现和证据，即使没有发现也要检查 coverage.json 中不完整或推迟的区域。提高频率或扩展仓库前先检查耗时与成本。将报告保存为 CI 产物，按其中的源代码和证据设置访问权限与保留期。也可以导出 SARIF 这种结构化安全发现格式，在平台安全界面显示结果；支持版本、权限和许可要求请参阅平台指南。
- 决定是否阻止合并：先审阅发现而不阻止合并。团队熟悉结果后，可以要求拉取请求通过安全检查，例如出现高危或严重漏洞时阻止合并。始终检查扫描是否完成及覆盖了哪些代码；即使未报告发现，失败或跳过代码的扫描也需要处理。设置细节见严重程度阈值与扫描结果说明。
- 跟进发现：按团队流程分配调查或修复任务，附上扫描提交、受影响代码和支持证据。验证修复后再关闭发现，并通过后续扫描补齐覆盖缺口。
展开英文原文对照
Add the Codex Security CLI to your CI pipeline. Choose when to scan and which code to review, preserve findings and coverage, and decide how results should affect delivery.
Make security scanning part of your development workflow. Run Codex Security on pull requests, after changes reach your default branch, or on a recurring schedule. Choose the scan scope that fits each trigger, preserve findings and coverage, and give your team a repeatable way to review the results.
Choose when to scan
Start with one trigger that fits your team’s workflow. Add others as you learn how long scans take, what they cost, and how your team uses the findings.
| When to run | Suggested scope | What it helps you review |
|---|---|---|
| On a schedule | Full repository, optionally using a deep scan | The broader codebase at a recurring interval. |
| On commits to main | Full repository at the pushed commit | The integrated code after changes reach your default branch. |
| On pull or merge requests | Changes between the merge base and proposed commit | Potential security regressions before merge. |
Use your repository’s default branch if it has a name other than main. Configure both the trigger and the scan scope: a pull-request diff scan covers that change, not the entire repository. A scan after changes reach main cannot block a pull request that has already merged.
Before you start
You’ll need a repository you’re authorized to assess, permission to configure its CI pipeline and secrets, and an OpenAI API key with Codex Security access. Use the CLI quickstart to check access and setup requirements.
Use a trusted runner that meets the CI requirements. Scans run with the runner’s local permissions. Keep unrelated credentials out of the scan job, and follow your platform’s restrictions for pull requests from forks and other untrusted code.
Set up your pipeline
- Add Codex Security to your pipeline Choose the example for your CI platform. Follow it to install the Codex Security CLI and provide an API key through your CI provider’s secret store. Choose a starting point: GitHub Actions: Use the pull-request workflow to scan proposed changes and preserve results. GitLab CI/CD: Use the pipeline guide for merge requests, default-branch scans, and scheduled scans. It includes a downloadable pipeline and explains which options to enable. Other CI platforms: Adapt the scan and export commands in Run Codex Security in CI to your provider’s triggers, secret store, checkout, and artifact handling.
- Configure the trigger and scope Scan the repository at the pushed commit when changes reach main, and on a recurring schedule for your chosen branch. Weekly scans are a good place to start; adjust the cadence based on repository activity, scan duration, and cost. For pull or merge requests, fetch the base and head history and scan the committed diff from their merge base. Configure each job to scan the intended code: the full repository for scheduled scans and commits to main, or the proposed changes for pull requests. Follow your platform’s example to set up the appropriate scan. Set a budget appropriate for the scope and frequency. Full-repository scans can take longer and cost more than diff scans. Treat --max-cost as an estimated cost limit, not a hard spending cap. Reaching it can leave coverage incomplete.
- Run the pipeline and review the results Submit the pipeline change through your normal review process, then trigger a scan. Confirm the target revision and scope in the run and scan-manifest.json. Review the findings and supporting evidence in the saved reports. Check coverage.json for incomplete or deferred areas, even if the scan reported no findings. Review runtime and cost before increasing the frequency or expanding to more repositories. Preserve reports as CI artifacts. Keep artifact access and retention appropriate for the source code and evidence they contain. Optionally export SARIF, a structured format for security findings, to display results in your platform’s security interface. Check the platform guide for supported versions, permissions, and licensing requirements.
- Choose whether findings should block merging Start by reviewing findings without blocking merges. Once your team is comfortable with the results, you can require pull requests to pass a security check—for example, blocking merges when the scan finds a high- or critical-severity vulnerability. Always check whether the scan completed and what code it covered. A scan that failed or skipped code needs attention, even if it reported no findings. For setup details, see Configure severity thresholds and interpret scan results.
- Follow up on findings Assign findings for investigation or remediation through your team’s normal process. Include the scanned commit, affected code, and supporting evidence so another developer can investigate. Verify fixes before closing findings, and address incomplete coverage in a follow-up scan.