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.