The code scanning API lets you retrieve and update code scanning alerts from a repository. You can use the endpoints to create automated reports for the code scanning alerts in an organization or upload analysis results generated using offline code scanning tools. For more information, see "Finding security vulnerabilities and errors in your code."
List code scanning alerts for a repository
Lists all open code scanning alerts for the default branch (usually main
or master
). You must use an access token with the security_events
scope to use this endpoint. GitHub Apps must have the security_events
read permission to use this endpoint.
get /repos/{owner}/{repo}/code-scanning/alerts
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
state |
string | query | Set to |
ref |
string | query | Set a full Git reference to list alerts for a specific branch. The |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://api.github.com/repos/octocat/hello-world/code-scanning/alerts
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/code-scanning/alerts', {
owner: 'octocat',
repo: 'hello-world'
})
Default response
Status: 200 OK
[
{
"number": 4,
"created_at": "2020-02-13T12:29:18Z",
"url": "https://api.github.com/repos/github/hello-world/code-scanning/alerts/4",
"html_url": "https://github.com/github/hello-world/code-scanning/4",
"state": "open",
"dismissed_by": null,
"dismissed_at": null,
"dismissed_reason": null,
"rule": {
"id": "js/zipslip",
"severity": "error",
"description": "Arbitrary file write during zip extraction"
},
"tool": {
"name": "CodeQL command-line toolchain",
"version": null
}
},
{
"number": 3,
"created_at": "2020-02-13T12:29:18Z",
"url": "https://api.github.com/repos/github/hello-world/code-scanning/alerts/3",
"html_url": "https://github.com/github/hello-world/code-scanning/3",
"state": "dismissed",
"dismissed_by": {
"login": "octocat",
"id": 1,
"node_id": "MDQ6VXNlcjE=",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"gravatar_id": "",
"url": "https://api.github.com/users/octocat",
"html_url": "https://github.com/octocat",
"followers_url": "https://api.github.com/users/octocat/followers",
"following_url": "https://api.github.com/users/octocat/following{/other_user}",
"gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
"starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
"subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
"organizations_url": "https://api.github.com/users/octocat/orgs",
"repos_url": "https://api.github.com/users/octocat/repos",
"events_url": "https://api.github.com/users/octocat/events{/privacy}",
"received_events_url": "https://api.github.com/users/octocat/received_events",
"type": "User",
"site_admin": false
},
"dismissed_at": "2020-02-14T12:29:18Z",
"dismissed_reason": "false positive",
"rule": {
"id": "js/zipslip",
"severity": "error",
"description": "Arbitrary file write during zip extraction"
},
"tool": {
"name": "CodeQL command-line toolchain",
"version": null
}
}
]
Response if github advanced security is not enabled for this repository
Status: 403 Forbidden
Response if the ref does not match an existing ref
Status: 404 Not Found
Service unavailable
Status: 503 Service Unavailable
Notes
Get a code scanning alert
Gets a single code scanning alert. You must use an access token with the security_events
scope to use this endpoint. GitHub Apps must have the security_events
read permission to use this endpoint.
The security alert_number
is found at the end of the security alert's URL. For example, the security alert ID for https://github.com/Octo-org/octo-repo/security/code-scanning/88
is 88
.
get /repos/{owner}/{repo}/code-scanning/alerts/{alert_number}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
alert_number |
integer | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://api.github.com/repos/octocat/hello-world/code-scanning/alerts/42
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/code-scanning/alerts/{alert_number}', {
owner: 'octocat',
repo: 'hello-world',
alert_number: 42
})
Default response
Status: 200 OK
{
"number": 42,
"created_at": "2020-06-19T11:21:34Z",
"url": "https://api.github.com/repos/github/hello-world/code-scanning/alerts/42",
"html_url": "https://github.com/github/hello-world/code-scanning/42",
"instances": [
{
"ref": "refs/heads/main",
"analysis_key": ".github/workflows/codeql-analysis.yml:CodeQL-Build",
"environment": "",
"state": "fixed"
},
{
"ref": "refs/pull/3740/head",
"analysis_key": ".github/workflows/codeql-analysis.yml:CodeQL-Build",
"environment": "",
"state": "dismissed"
}
],
"state": "dismissed",
"dismissed_by": {
"login": "octocat",
"id": 1,
"node_id": "MDQ6VXNlcjE=",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"gravatar_id": "",
"url": "https://api.github.com/users/octocat",
"html_url": "https://github.com/octocat",
"followers_url": "https://api.github.com/users/octocat/followers",
"following_url": "https://api.github.com/users/octocat/following{/other_user}",
"gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
"starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
"subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
"organizations_url": "https://api.github.com/users/octocat/orgs",
"repos_url": "https://api.github.com/users/octocat/repos",
"events_url": "https://api.github.com/users/octocat/events{/privacy}",
"received_events_url": "https://api.github.com/users/octocat/received_events",
"type": "User",
"site_admin": false
},
"dismissed_at": "2020-02-14T12:29:18Z",
"dismissed_reason": "false positive",
"rule": {
"id": "js/polynomial-redos",
"severity": "warning",
"description": "Polynomial regular expression used on uncontrolled data"
},
"tool": {
"name": "CodeQL command-line toolchain",
"version": null
}
}
Response if github advanced security is not enabled for this repository
Status: 403 Forbidden
Resource not found
Status: 404 Not Found
Service unavailable
Status: 503 Service Unavailable
Notes
Update a code scanning alert
Updates the status of a single code scanning alert. You must use an access token with the security_events
scope to use this endpoint. GitHub Apps must have the security_events
write permission to use this endpoint.
patch /repos/{owner}/{repo}/code-scanning/alerts/{alert_number}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
alert_number |
integer | path | The security alert number, found at the end of the security alert's URL. |
state |
string | body |
Required. Sets the state of the code scanning alert. Can be one of |
dismissed_reason |
string or null | body |
Required when the state is dismissed. The reason for dismissing or closing the alert. Can be one of: |
Code samples
Shell
curl \
-X PATCH \
-H "Accept: application/vnd.github.v3+json" \
https://api.github.com/repos/octocat/hello-world/code-scanning/alerts/42 \
-d '{"state":"state"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /repos/{owner}/{repo}/code-scanning/alerts/{alert_number}', {
owner: 'octocat',
repo: 'hello-world',
alert_number: 42,
state: 'state'
})
Default response
Status: 200 OK
{
"number": 42,
"created_at": "2020-08-25T21:28:36Z",
"url": "https://api.github.com/repos/github/hello-world/code-scanning/alerts/42",
"html_url": "https://github.com/github/hello-world/code-scanning/42",
"instances": [
{
"ref": "refs/heads/codeql-analysis-yml",
"analysis_key": ".github/workflows/codeql-analysis.yml:CodeQL-Build",
"environment": "",
"state": "dismissed"
},
{
"ref": "refs/pull/3740/head",
"analysis_key": ".github/workflows/codeql-analysis.yml:CodeQL-Build",
"environment": "",
"state": "dismissed"
}
],
"state": "dismissed",
"dismissed_by": {
"login": "octocat",
"id": 1,
"node_id": "MDQ6VXNlcjE=",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"gravatar_id": "",
"url": "https://api.github.com/users/octocat",
"html_url": "https://github.com/octocat",
"followers_url": "https://api.github.com/users/octocat/followers",
"following_url": "https://api.github.com/users/octocat/following{/other_user}",
"gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
"starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
"subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
"organizations_url": "https://api.github.com/users/octocat/orgs",
"repos_url": "https://api.github.com/users/octocat/repos",
"events_url": "https://api.github.com/users/octocat/events{/privacy}",
"received_events_url": "https://api.github.com/users/octocat/received_events",
"type": "User",
"site_admin": false
},
"dismissed_at": "2020-09-02T22:34:56Z",
"dismissed_reason": "false positive",
"rule": {
"id": "js/polynomial-redos",
"severity": "warning",
"description": "Polynomial regular expression used on uncontrolled data"
},
"tool": {
"name": "CodeQL command-line toolchain",
"version": null
}
}
Response if the repository is archived or if github advanced security is not enabled for this repository
Status: 403 Forbidden
Response when code scanning is not available and you should try again at a later time
Status: 503 Service Unavailable
Notes
List recent code scanning analyses for a repository
List the details of recent code scanning analyses for a repository. You must use an access token with the security_events
scope to use this endpoint. GitHub Apps must have the security_events
read permission to use this endpoint.
get /repos/{owner}/{repo}/code-scanning/analyses
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
ref |
string | query | Set a full Git reference to list alerts for a specific branch. The |
tool_name |
string | query | Set a single code scanning tool name to filter alerts by tool. |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://api.github.com/repos/octocat/hello-world/code-scanning/analyses
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/code-scanning/analyses', {
owner: 'octocat',
repo: 'hello-world'
})
Default response
Status: 200 OK
[
{
"ref": "refs/heads/master",
"commit_sha": "d99612c3e1f2970085cfbaeadf8f010ef69bad83",
"analysis_key": ".github/workflows/codeql-analysis.yml:analyze",
"tool_name": "CodeQL command-line toolchain",
"environment": "{}",
"error": "",
"created_at": "2020-08-27T15:05:21Z"
},
{
"ref": "refs/heads/my-branch",
"commit_sha": "c8cff6510d4d084fb1b4aa13b64b97ca12b07321",
"analysis_key": ".github/workflows/shiftleft.yml:build",
"tool_name": "Python Security Analysis",
"environment": "{}",
"error": "",
"created_at": "2020-08-31T22:46:44Z"
}
]
Response if github advanced security is not enabled for this repository
Status: 403 Forbidden
Notes
Upload a SARIF file
Upload a SARIF file containing the results of a code scanning analysis to make the results available in a repository. You must use an access token with the security_events
scope to use this endpoint. GitHub Apps must have the security_events
write permission to use this endpoint.
post /repos/{owner}/{repo}/code-scanning/sarifs
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
commit_sha |
string | body |
Required. The commit SHA of the code scanning analysis file. |
ref |
string | body |
Required. The full Git reference of the code scanning analysis file, formatted as |
sarif |
string | body |
Required. A Base64 string representing the SARIF file to upload. You must first compress your SARIF file using |
checkout_uri |
string | body |
The base directory used in the analysis, as it appears in the SARIF file. This property is used to convert file paths from absolute to relative, so that alerts can be mapped to their correct location in the repository. |
started_at |
string | body |
The time that the analysis run began. This is a timestamp in ISO 8601 format: |
tool_name |
string | body |
Required. The name of the tool used to generate the code scanning analysis alert. |
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
https://api.github.com/repos/octocat/hello-world/code-scanning/sarifs \
-d '{"commit_sha":"commit_sha","ref":"ref","sarif":"sarif","tool_name":"tool_name"}'
JavaScript (@octokit/core.js)
await octokit.request('POST /repos/{owner}/{repo}/code-scanning/sarifs', {
owner: 'octocat',
repo: 'hello-world',
commit_sha: 'commit_sha',
ref: 'ref',
sarif: 'sarif',
tool_name: 'tool_name'
})
Response
Status: 202 Accepted
Response if the sarif field is invalid
Status: 400 Bad Request
Response if the repository is archived or if github advanced security is not enabled for this repository
Status: 403 Forbidden
Response if commit sha or ref cannot be found
Status: 404 Not Found
Response if the sarif field is too large
Status: 413 Payload Too Large