analysis

Creates, updates, deletes, gets or lists an analysis resource.

Overview

Name	analysis
Type	Resource
Id	github.code_scanning.analysis

Fields

The following fields are returned by SELECT queries:

get_analysis

Response

Name	Datatype	Description
id	integer	Unique identifier for this analysis.
sarif_id	string	An identifier for the upload. (example: 6c81cd8e-b078-4ac3-a3be-1dad7dbd0b53)
analysis_key	string	Identifies the configuration under which the analysis was executed. For example, in GitHub Actions this includes the workflow filename and job name.
category	string	Identifies the configuration under which the analysis was executed. Used to distinguish between multiple analyses for the same tool and commit, but performed on different languages or different parts of the code.
commit_sha	string	The SHA of the commit to which the analysis you are uploading relates. (pattern: ^[0-9a-fA-F]+$)
created_at	string (date-time)	The time that the analysis was created in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.
deletable	boolean
environment	string	Identifies the variable values associated with the environment in which this analysis was performed.
error	string	(example: error reading field xyz)
ref	string	The Git reference, formatted as refs/pull/<number>/merge, refs/pull/<number>/head, refs/heads/<branch name> or simply <branch name>.
results_count	integer	The total number of results in the analysis.
rules_count	integer	The total number of rules used in the analysis.
tool	object
url	string (uri)	The REST API URL of the analysis resource.
warning	string	Warning generated when processing the analysis (example: 123 results were ignored)

list_recent_analyses

Response

Name	Datatype	Description
id	integer	Unique identifier for this analysis.
sarif_id	string	An identifier for the upload. (example: 6c81cd8e-b078-4ac3-a3be-1dad7dbd0b53)
analysis_key	string	Identifies the configuration under which the analysis was executed. For example, in GitHub Actions this includes the workflow filename and job name.
category	string	Identifies the configuration under which the analysis was executed. Used to distinguish between multiple analyses for the same tool and commit, but performed on different languages or different parts of the code.
commit_sha	string	The SHA of the commit to which the analysis you are uploading relates. (pattern: ^[0-9a-fA-F]+$)
created_at	string (date-time)	The time that the analysis was created in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.
deletable	boolean
environment	string	Identifies the variable values associated with the environment in which this analysis was performed.
error	string	(example: error reading field xyz)
ref	string	The Git reference, formatted as refs/pull/<number>/merge, refs/pull/<number>/head, refs/heads/<branch name> or simply <branch name>.
results_count	integer	The total number of results in the analysis.
rules_count	integer	The total number of rules used in the analysis.
tool	object
url	string (uri)	The REST API URL of the analysis resource.
warning	string	Warning generated when processing the analysis (example: 123 results were ignored)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_analysis	select	owner, repo, analysis_id		Gets a specified code scanning analysis for a repository. The default JSON response contains fields that describe the analysis. This includes the Git reference and commit SHA to which the analysis relates, the datetime of the analysis, the name of the code scanning tool, and the number of alerts. The rules_count field in the default response give the number of rules that were run in the analysis. For very old analyses this data is not available, and 0 is returned in this field. This endpoint supports the following custom media types. For more information, see "Media types." - application/sarif+json: Instead of returning a summary of the analysis, this endpoint returns a subset of the analysis data that was uploaded. The data is formatted as SARIF version 2.1.0. It also returns additional data such as the github/alertNumber and github/alertUrl properties. OAuth app tokens and personal access tokens (classic) need the security_events scope to use this endpoint with private or public repositories, or the public_repo scope to use this endpoint with only public repositories.
list_recent_analyses	select	owner, repo	tool_name, tool_guid, page, per_page, pr, ref, sarif_id, direction, sort	Lists the details of all code scanning analyses for a repository, starting with the most recent. The response is paginated and you can use the page and per_page parameters to list the analyses you're interested in. By default 30 analyses are listed per page. The rules_count field in the response give the number of rules that were run in the analysis. For very old analyses this data is not available, and 0 is returned in this field. > [!WARNING] > Closing down notice: The tool_name field is closing down and will, in future, not be included in the response for this endpoint. The example response reflects this change. The tool name can now be found inside the tool field. OAuth app tokens and personal access tokens (classic) need the security_events scope to use this endpoint with private or public repositories, or the public_repo scope to use this endpoint with only public repositories.
delete_analysis	delete	owner, repo, analysis_id	confirm_delete	Deletes a specified code scanning analysis from a repository. You can delete one analysis at a time. To delete a series of analyses, start with the most recent analysis and work backwards. Conceptually, the process is similar to the undo function in a text editor. When you list the analyses for a repository, one or more will be identified as deletable in the response: <br />"deletable": true<br /> An analysis is deletable when it's the most recent in a set of analyses. Typically, a repository will have multiple sets of analyses for each enabled code scanning tool, where a set is determined by a unique combination of analysis values: * ref * tool * category If you attempt to delete an analysis that is not the most recent in a set, you'll get a 400 response with the message: <br />Analysis specified is not deletable.<br /> The response from a successful DELETE operation provides you with two alternative URLs for deleting the next analysis in the set: next_analysis_url and confirm_delete_url. Use the next_analysis_url URL if you want to avoid accidentally deleting the final analysis in a set. This is a useful option if you want to preserve at least one analysis for the specified tool in your repository. Use the confirm_delete_url URL if you are content to remove all analyses for a tool. When you delete the last analysis in a set, the value of next_analysis_url and confirm_delete_url in the 200 response is null. As an example of the deletion process, let's imagine that you added a workflow that configured a particular code scanning tool to analyze the code in a repository. This tool has added 15 analyses: 10 on the default branch, and another 5 on a topic branch. You therefore have two separate sets of analyses for this tool. You've now decided that you want to remove all of the analyses for the tool. To do this you must make 15 separate deletion requests. To start, you must find an analysis that's identified as deletable. Each set of analyses always has one that's identified as deletable. Having found the deletable analysis for one of the two sets, delete this analysis and then continue deleting the next analysis in the set until they're all deleted. Then repeat the process for the second set. The procedure therefore consists of a nested loop: Outer loop: * List the analyses for the repository, filtered by tool. * Parse this list to find a deletable analysis. If found: Inner loop: * Delete the identified analysis. * Parse the response for the value of confirm_delete_url and, if found, use this in the next iteration. The above process assumes that you want to remove all trace of the tool's analyses from the GitHub user interface, for the specified repository, and it therefore uses the confirm_delete_url value. Alternatively, you could use the next_analysis_url value, which would leave the last analysis in each set undeleted to avoid removing a tool's analysis entirely. OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint with private or public repositories, or the public_repo scope to use this endpoint with only public repositories.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
analysis_id	integer	The ID of the analysis, as returned from the GET /repos/{owner}/{repo}/code-scanning/analyses operation.
owner	string	The account owner of the repository. The name is not case sensitive.
repo	string	The name of the repository without the .git extension. The name is not case sensitive.
confirm_delete	string	Allow deletion if the specified analysis is the last in a set. If you attempt to delete the final analysis in a set without setting this parameter to true, you'll get a 400 response with the message: Analysis is last of its type and deletion may result in the loss of historical alert data. Please specify confirm_delete.
direction	string	The direction to sort the results by.
page	integer	The page number of the results to fetch. For more information, see "Using pagination in the REST API."
per_page	integer	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
pr	integer	The number of the pull request for the results you want to list.
ref	string	The Git reference for the analyses you want to list. The ref for a branch can be formatted either as refs/heads/<branch name> or simply <branch name>. To reference a pull request use refs/pull/<number>/merge.
sarif_id	string	Filter analyses belonging to the same SARIF upload.
sort	string	The property by which to sort the results.
tool_guid	string	The GUID of a code scanning tool. Only results by this tool will be listed. Note that some code scanning tools may not include a GUID in their analysis data. You can specify the tool by using either tool_guid or tool_name, but not both.
tool_name	string	The name of a code scanning tool. Only results by this tool will be listed. You can specify the tool by using either tool_name or tool_guid, but not both.

SELECT examples

get_analysis

Gets a specified code scanning analysis for a repository.

The default JSON response contains fields that describe the analysis.
This includes the Git reference and commit SHA to which the analysis relates,
the datetime of the analysis, the name of the code scanning tool,
and the number of alerts.

The rules_count field in the default response give the number of rules
that were run in the analysis.
For very old analyses this data is not available,
and 0 is returned in this field.

This endpoint supports the following custom media types. For more information, see "Media types."

- application/sarif+json: Instead of returning a summary of the analysis, this endpoint returns a subset of the analysis data that was uploaded. The data is formatted as SARIF version 2.1.0. It also returns additional data such as the github/alertNumber and github/alertUrl properties.

OAuth app tokens and personal access tokens (classic) need the security_events scope to use this endpoint with private or public repositories, or the public_repo scope to use this endpoint with only public repositories.

SELECT
id,
sarif_id,
analysis_key,
category,
commit_sha,
created_at,
deletable,
environment,
error,
ref,
results_count,
rules_count,
tool,
url,
warning
FROM github.code_scanning.analysis
WHERE owner = '{{ owner }}' -- required
AND repo = '{{ repo }}' -- required
AND analysis_id = '{{ analysis_id }}' -- required
;

list_recent_analyses

Lists the details of all code scanning analyses for a repository,
starting with the most recent.
The response is paginated and you can use the page and per_page parameters
to list the analyses you're interested in.
By default 30 analyses are listed per page.

The rules_count field in the response give the number of rules
that were run in the analysis.
For very old analyses this data is not available,
and 0 is returned in this field.

> [!WARNING]
> Closing down notice: The tool_name field is closing down and will, in future, not be included in the response for this endpoint. The example response reflects this change. The tool name can now be found inside the tool field.

OAuth app tokens and personal access tokens (classic) need the security_events scope to use this endpoint with private or public repositories, or the public_repo scope to use this endpoint with only public repositories.

SELECT
id,
sarif_id,
analysis_key,
category,
commit_sha,
created_at,
deletable,
environment,
error,
ref,
results_count,
rules_count,
tool,
url,
warning
FROM github.code_scanning.analysis
WHERE owner = '{{ owner }}' -- required
AND repo = '{{ repo }}' -- required
AND tool_name = '{{ tool_name }}'
AND tool_guid = '{{ tool_guid }}'
AND page = '{{ page }}'
AND per_page = '{{ per_page }}'
AND pr = '{{ pr }}'
AND ref = '{{ ref }}'
AND sarif_id = '{{ sarif_id }}'
AND direction = '{{ direction }}'
AND sort = '{{ sort }}'
;

DELETE examples

delete_analysis

Deletes a specified code scanning analysis from a repository.

You can delete one analysis at a time.
To delete a series of analyses, start with the most recent analysis and work backwards.
Conceptually, the process is similar to the undo function in a text editor.

When you list the analyses for a repository,
one or more will be identified as deletable in the response:

<br />"deletable": true<br />

An analysis is deletable when it's the most recent in a set of analyses.
Typically, a repository will have multiple sets of analyses
for each enabled code scanning tool,
where a set is determined by a unique combination of analysis values:

* ref
* tool
* category

If you attempt to delete an analysis that is not the most recent in a set,
you'll get a 400 response with the message:

<br />Analysis specified is not deletable.<br />

The response from a successful DELETE operation provides you with
two alternative URLs for deleting the next analysis in the set:
next_analysis_url and confirm_delete_url.
Use the next_analysis_url URL if you want to avoid accidentally deleting the final analysis
in a set. This is a useful option if you want to preserve at least one analysis
for the specified tool in your repository.
Use the confirm_delete_url URL if you are content to remove all analyses for a tool.
When you delete the last analysis in a set, the value of next_analysis_url and confirm_delete_url
in the 200 response is null.

As an example of the deletion process,
let's imagine that you added a workflow that configured a particular code scanning tool
to analyze the code in a repository. This tool has added 15 analyses:
10 on the default branch, and another 5 on a topic branch.
You therefore have two separate sets of analyses for this tool.
You've now decided that you want to remove all of the analyses for the tool.
To do this you must make 15 separate deletion requests.
To start, you must find an analysis that's identified as deletable.
Each set of analyses always has one that's identified as deletable.
Having found the deletable analysis for one of the two sets,
delete this analysis and then continue deleting the next analysis in the set until they're all deleted.
Then repeat the process for the second set.
The procedure therefore consists of a nested loop:

Outer loop:
* List the analyses for the repository, filtered by tool.
* Parse this list to find a deletable analysis. If found:

Inner loop:
* Delete the identified analysis.
* Parse the response for the value of confirm_delete_url and, if found, use this in the next iteration.

The above process assumes that you want to remove all trace of the tool's analyses from the GitHub user interface, for the specified repository, and it therefore uses the confirm_delete_url value. Alternatively, you could use the next_analysis_url value, which would leave the last analysis in each set undeleted to avoid removing a tool's analysis entirely.

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint with private or public repositories, or the public_repo scope to use this endpoint with only public repositories.

DELETE FROM github.code_scanning.analysis
WHERE owner = '{{ owner }}' --required
AND repo = '{{ repo }}' --required
AND analysis_id = '{{ analysis_id }}' --required
AND confirm_delete = '{{ confirm_delete }}'
;