GitHub AI Scan API Guide: Automate Pull Request Security Settings

GitHub introduced REST API controls for AI Scan on pull requests on September 10, 2026. The public preview gives security teams a programmatic way to read and change AI Scan settings at the organization and repository levels instead of configuring every repository manually.

The API makes a controlled rollout easier, but it does not turn AI findings into a merge gate. GitHub describes the findings as advisory, says they may include false positives, and currently limits them to pull requests. This guide explains what the feature scans, what must be enabled first, how the settings hierarchy works, and how to automate a rollout without granting unnecessarily broad access.

What is the GitHub AI Scan API?

The GitHub AI Scan API is a set of REST endpoints for reading and updating AI-powered pull request scanning at the organization and repository levels. It is a public preview for GitHub Advanced Security customers on GitHub.com. The scan complements CodeQL, produces advisory findings on pull requests, and cannot currently block merges through rulesets.

GitHub's AI-powered security detections are intended to extend coverage into languages and frameworks that CodeQL does not currently support. GitHub lists examples including PHP, Shell/Bash, Terraform configuration, Dockerfiles, JSP for Java, and Blazor for C#.

The engine examines changed code and can use code search for additional repository context. It runs when a pull request is created and after new commits, provided the repository uses CodeQL default setup and the required AI settings are enabled. Findings appear on the pull request's Conversation and Files changed tabs with an AI label.

Who can use it, and what does it cost?

During the public preview, GitHub documents several prerequisites:

• The repository must be hosted on GitHub.com; GitHub Enterprise Server is not supported for this release.
• The organization needs a GitHub Advanced Security license.
• AI-powered detections also require a GitHub Copilot license.
• CodeQL default setup must be enabled on participating repositories.
• The enterprise policy must allow AI findings before an organization can enable them.

Usage consumes AI credits. That means a large rollout should include a budget and measurement plan, not just an enablement script. Track how many eligible pull requests are scanned, how many findings developers accept, the false-positive rate, time to remediation, and credit consumption. A feature that generates many ignored findings can increase both cost and review fatigue.

How the settings hierarchy works

The setting has three practical layers:

1. Enterprise policy: AI findings are not allowed at the enterprise level by default. An enterprise administrator must permit the feature.
2. Organization setting: An organization owner or security manager can enable or disable AI Scan for the organization.
3. Repository setting: Repository administrators can opt individual repositories out or enable eligible repositories when the parent policies allow it.

A repository cannot override an organization-level disabled state. Likewise, an organization cannot enable the feature when the enterprise policy disallows it. Automation should therefore read the organization setting before attempting repository changes and treat a policy rejection as a configuration outcome, not as a transient error to retry repeatedly.

The four REST operations

GitHub's new endpoints use one organization path and one repository path, each supporting GET and PATCH:

• GET /orgs/{org}/code-scanning/ai-scan reads the organization setting.
• PATCH /orgs/{org}/code-scanning/ai-scan updates the organization setting.
• GET /repos/{owner}/{repo}/code-scanning/ai-scan reads the repository setting.
• PATCH /repos/{owner}/{repo}/code-scanning/ai-scan updates the repository setting.

The response and request body use pr_scan with either enabled or disabled. GitHub recommends the application/vnd.github+json media type and currently documents 2026-03-10 as the REST API version for these examples.

Example: read and update a repository setting

Use a dedicated token supplied through your secret manager. The placeholders below deliberately contain no real credential:

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  https://api.github.com/repos/OWNER/REPO/code-scanning/ai-scan

After confirming the parent policy and current value, enable the repository with a PATCH request:

curl -L \
  -X PATCH \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  https://api.github.com/repos/OWNER/REPO/code-scanning/ai-scan \
  -d '{"pr_scan":"enabled"}'

A successful request returns HTTP 200 and the stored setting. GitHub documents 403 responses when GitHub Advanced Security is unavailable or, for repository updates, when the repository is archived. A 404 can indicate a missing resource or inaccessible endpoint, while 422 can indicate invalid input. Validate JSON before sending it; ToolNexa's JSON formatting and validation guide covers the common syntax mistakes that cause avoidable API failures.

A safe rollout workflow

1. Inventory eligible repositories

Start with active repositories on GitHub.com that already use CodeQL default setup. Record the owning organization, language mix, pull request volume, risk level, current code-scanning configuration, and whether GitHub Advanced Security and Copilot licenses are assigned.

2. Confirm policy from the top down

Verify the enterprise AI Findings policy, then read the organization setting with the GET endpoint. Do not launch repository PATCH requests until the parent layers allow the feature. This reduces noisy failures and makes the final state easier to explain.

3. Use least-privilege automation

Create a dedicated GitHub App or narrowly scoped token for the rollout instead of reusing a developer's broad personal credential. Grant only the permissions required by GitHub's current endpoint documentation, keep the token outside source code and logs, and separate read-only inventory from configuration writes where practical. ToolNexa's credential security guide explains why unique credentials matter; API tokens should additionally be short-lived and narrowly scoped.

4. Pilot with a small, representative group

Choose repositories that cover several languages and team workflows without exposing the entire organization. Include at least one language outside CodeQL's normal coverage and one repository where CodeQL already performs well. The comparison helps determine whether AI findings add useful coverage or merely duplicate existing alerts.

5. Verify behavior on real pull requests

Create normal test pull requests or wait for routine development activity. Confirm that scans run after creation and new commits, that findings are clearly labeled AI, and that developers know the results are advisory. Do not seed intentionally vulnerable code into a production branch.

6. Measure signal quality and cost

Review accepted findings, false positives, duplicate findings, remediation time, developer feedback, and AI-credit consumption. Sample both findings that were fixed and findings that were dismissed. A thumbs-up or thumbs-down is useful feedback to GitHub, but your organization still needs its own audit trail for rollout decisions.

7. Expand in controlled batches

Apply repository settings in small batches, re-read each updated value, and store the HTTP status and final state. Use bounded retries for transient failures. Do not retry 403 policy or licensing errors as if they were outages, and do not assume a PATCH succeeded if the response was lost; GET the stable setting before another write.

What AI Scan can and cannot do

AI Scan complements CodeQL rather than replacing it. GitHub says it runs independently when CodeQL is waiting or fails, but CodeQL remains the high-precision static-analysis system for its supported languages and queries. The AI engine can broaden coverage, especially for unsupported languages and framework gaps, yet its output needs human review.

Current public-preview limitations matter:

• Scans apply to pull requests only, not full-repository or backlog scans.
• AI findings cannot be used in rulesets to require a passing result before merge.
• Findings may contain false positives.
• Supported languages and detection categories may change during the preview.
• Suggested remediation is available for many findings, but not every finding has one.

GitHub currently lists categories including injection, weak cryptography, broken access control, sensitive-data exposure, security misconfiguration, authentication failures, data-integrity failures, server-side request forgery, and supply-chain risks. Treat those categories as evolving preview coverage, not a guarantee that every vulnerability in them will be detected.

Operational checklist

• Confirm GitHub.com, Advanced Security, Copilot, and CodeQL default setup prerequisites.
• Verify enterprise policy before changing organization or repository settings.
• Read the current value before every PATCH and re-read it afterward.
• Use a dedicated least-privilege identity and keep tokens out of code and logs.
• Pilot on representative repositories before organization-wide enablement.
• Tell developers that AI findings are advisory and may be wrong.
• Track useful findings, false positives, remediation time, and AI-credit use.
• Retain CodeQL and other established security checks.
• Pin the REST API version and monitor preview documentation for changes.
• Maintain a rollback list so repositories can be disabled in controlled batches.

Frequently asked questions

Is GitHub AI Scan generally available?

No. GitHub labels AI-powered security detections and the new management endpoints as a public preview, so behavior, categories, and requirements may change.

Can AI Scan findings block a pull request merge?

No. GitHub says the findings are advisory and cannot currently be used in rulesets to enforce merge requirements.

Does AI Scan replace CodeQL?

No. It complements CodeQL and is designed to add coverage for languages and framework gaps that CodeQL does not cover. Participating repositories still need CodeQL default setup enabled.

Can a repository enable AI Scan if its organization disables it?

No. A repository setting cannot override an organization-level disabled state, and the organization must also comply with the enterprise policy.

Does GitHub AI Scan use credits?

Yes. GitHub's documentation says AI-powered security detections consume AI credits during the public preview, in addition to requiring the applicable Advanced Security and Copilot licenses.

Conclusion

GitHub's AI Scan API turns a manual repository setting into an auditable automation target. The safest approach is to confirm policy and licensing first, inventory the current state, pilot on a small group, and measure signal quality and credit use before expanding. Keep CodeQL and established review controls in place, because AI findings are broader but advisory, preview-stage signals rather than a complete security gate.

Sources

• GitHub Changelog: AI Scan for pull request APIs in public preview
• GitHub Docs: AI-powered security detections in pull requests
• GitHub Docs: REST API endpoints for code scanning