Skip to content
forgit api docs

Create a CodeQL variant analysis

POST
/repos/{owner}/{repo}/code-scanning/codeql/variant-analyses

Creates a new CodeQL variant analysis, which will run a CodeQL query against one or more repositories.

Get started by learning more about running CodeQL queries at scale with Multi-Repository Variant Analysis.

Use the owner and repo parameters in the URL to specify the controller repository that will be used for running GitHub Actions workflows and storing the results of the CodeQL variant analysis.

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint.

API method documentation

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
owner
required
string

The account owner of the repository. The name is not case sensitive.

repo
required
string

The name of the repository without the .git extension. The name is not case sensitive.

Request Body required

Section titled “ Request Body required ”
Media type application/json
One of:
object
language

The language targeted by the CodeQL query

string
Allowed values: actions cpp csharp go java javascript python ruby rust swift
query_pack

A Base64-encoded tarball containing a CodeQL query and all its dependencies

string
repositories
required

List of repository names (in the form owner/repo-name) to run the query against. Precisely one property from repositories, repository_lists and repository_owners is required.

Array<string>
repository_lists

List of repository lists to run the query against. Precisely one property from repositories, repository_lists and repository_owners is required.

Array<string>
<= 1 items
repository_owners

List of organization or user names whose repositories the query should be run against. Precisely one property from repositories, repository_lists and repository_owners is required.

Array<string>
<= 1 items
Examples

Using the "repositories" field. "query_pack" is abridged for brevity. 

{
  "language": "csharp",
  "query_pack": "aGVsbG8=",
  "repositories": [
    "octocat/Hello-World",
    "octocat/example"
  ]
}

Responses

Section titled “ Responses ”

201

Section titled “ 201 ”

Variant analysis submitted for processing

Media type application/json
Variant Analysis

A run of a CodeQL query against one or more repositories.

object
id
required

The ID of the variant analysis.

integer
controller_repo
required
Simple Repository

A GitHub repository.

object
id
required

A unique identifier of the repository.

integer format: int64
node_id
required

The GraphQL identifier of the repository.

string
name
required

The name of the repository.

string
full_name
required

The full, globally unique, name of the repository.

string
owner
required
Simple User

A GitHub user.

object
name
string
nullable
email
string
nullable
login
required
string
id
required
integer format: int64
node_id
required
string
avatar_url
required
string format: uri
gravatar_id
required
string
nullable
url
required
string format: uri
html_url
required
string format: uri
followers_url
required
string format: uri
following_url
required
string
gists_url
required
string
starred_url
required
string
subscriptions_url
required
string format: uri
organizations_url
required
string format: uri
repos_url
required
string format: uri
events_url
required
string
received_events_url
required
string format: uri
type
required
string
site_admin
required
boolean
starred_at
string
user_view_type
string
private
required

Whether the repository is private.

boolean
html_url
required

The URL to view the repository on GitHub.com.

string format: uri
description
required

The repository description.

string
nullable
fork
required

Whether the repository is a fork.

boolean
url
required

The URL to get more information about the repository from the GitHub API.

string format: uri
archive_url
required

A template for the API URL to download the repository as an archive.

string
assignees_url
required

A template for the API URL to list the available assignees for issues in the repository.

string
blobs_url
required

A template for the API URL to create or retrieve a raw Git blob in the repository.

string
branches_url
required

A template for the API URL to get information about branches in the repository.

string
collaborators_url
required

A template for the API URL to get information about collaborators of the repository.

string
comments_url
required

A template for the API URL to get information about comments on the repository.

string
commits_url
required

A template for the API URL to get information about commits on the repository.

string
compare_url
required

A template for the API URL to compare two commits or refs.

string
contents_url
required

A template for the API URL to get the contents of the repository.

string
contributors_url
required

A template for the API URL to list the contributors to the repository.

string format: uri
deployments_url
required

The API URL to list the deployments of the repository.

string format: uri
downloads_url
required

The API URL to list the downloads on the repository.

string format: uri
events_url
required

The API URL to list the events of the repository.

string format: uri
forks_url
required

The API URL to list the forks of the repository.

string format: uri
git_commits_url
required

A template for the API URL to get information about Git commits of the repository.

string
git_refs_url
required

A template for the API URL to get information about Git refs of the repository.

string
git_tags_url
required

A template for the API URL to get information about Git tags of the repository.

string
issue_comment_url
required

A template for the API URL to get information about issue comments on the repository.

string
issue_events_url
required

A template for the API URL to get information about issue events on the repository.

string
issues_url
required

A template for the API URL to get information about issues on the repository.

string
keys_url
required

A template for the API URL to get information about deploy keys on the repository.

string
labels_url
required

A template for the API URL to get information about labels of the repository.

string
languages_url
required

The API URL to get information about the languages of the repository.

string format: uri
merges_url
required

The API URL to merge branches in the repository.

string format: uri
milestones_url
required

A template for the API URL to get information about milestones of the repository.

string
notifications_url
required

A template for the API URL to get information about notifications on the repository.

string
pulls_url
required

A template for the API URL to get information about pull requests on the repository.

string
releases_url
required

A template for the API URL to get information about releases on the repository.

string
stargazers_url
required

The API URL to list the stargazers on the repository.

string format: uri
statuses_url
required

A template for the API URL to get information about statuses of a commit.

string
subscribers_url
required

The API URL to list the subscribers on the repository.

string format: uri
subscription_url
required

The API URL to subscribe to notifications for this repository.

string format: uri
tags_url
required

The API URL to get information about tags on the repository.

string format: uri
teams_url
required

The API URL to list the teams on the repository.

string format: uri
trees_url
required

A template for the API URL to create or retrieve a raw Git tree of the repository.

string
hooks_url
required

The API URL to list the hooks on the repository.

string format: uri
actor
required
Simple User

A GitHub user.

object
name
string
nullable
email
string
nullable
login
required
string
id
required
integer format: int64
node_id
required
string
avatar_url
required
string format: uri
gravatar_id
required
string
nullable
url
required
string format: uri
html_url
required
string format: uri
followers_url
required
string format: uri
following_url
required
string
gists_url
required
string
starred_url
required
string
subscriptions_url
required
string format: uri
organizations_url
required
string format: uri
repos_url
required
string format: uri
events_url
required
string
received_events_url
required
string format: uri
type
required
string
site_admin
required
boolean
starred_at
string
user_view_type
string
query_language
required

The language targeted by the CodeQL query

string
Allowed values: actions cpp csharp go java javascript python ruby rust swift
query_pack_url
required

The download url for the query pack.

string
created_at

The date and time at which the variant analysis was created, in ISO 8601 format’:’ YYYY-MM-DDTHH:MM:SSZ.

string format: date-time
updated_at

The date and time at which the variant analysis was last updated, in ISO 8601 format’:’ YYYY-MM-DDTHH:MM:SSZ.

string format: date-time
completed_at

The date and time at which the variant analysis was completed, in ISO 8601 format’:’ YYYY-MM-DDTHH:MM:SSZ. Will be null if the variant analysis has not yet completed or this information is not available.

string format: date-time
nullable
status
required
string
Allowed values: in_progress succeeded failed cancelled
actions_workflow_run_id

The GitHub Actions workflow run used to execute this variant analysis. This is only available if the workflow run has started.

integer
failure_reason

The reason for a failure of the variant analysis. This is only available if the variant analysis has failed.

string
Allowed values: no_repos_queried actions_workflow_run_failed internal_error
scanned_repositories
Array<object>
object
repository
required
Repository Identifier

Repository Identifier

object
id
required

A unique identifier of the repository.

integer
name
required

The name of the repository.

string
full_name
required

The full, globally unique, name of the repository.

string
private
required

Whether the repository is private.

boolean
stargazers_count
required
integer
updated_at
required
string format: date-time
nullable
analysis_status
required

The new status of the CodeQL variant analysis repository task.

string
Allowed values: pending in_progress succeeded failed canceled timed_out
result_count

The number of results in the case of a successful analysis. This is only available for successful analyses.

integer
artifact_size_in_bytes

The size of the artifact. This is only available for successful analyses.

integer
failure_message

The reason of the failure of this repo task. This is only available if the repository task has failed.

string
skipped_repositories

Information about repositories that were skipped from processing. This information is only available to the user that initiated the variant analysis.

object
access_mismatch_repos
required
object
repository_count
required

The total number of repositories that were skipped for this reason.

integer
repositories
required

A list of repositories that were skipped. This list may not include all repositories that were skipped. This is only available when the repository was found and the user has access to it.

Array<object>
Repository Identifier

Repository Identifier

object
id
required

A unique identifier of the repository.

integer
name
required

The name of the repository.

string
full_name
required

The full, globally unique, name of the repository.

string
private
required

Whether the repository is private.

boolean
stargazers_count
required
integer
updated_at
required
string format: date-time
nullable
not_found_repos
required
object
repository_count
required

The total number of repositories that were skipped for this reason.

integer
repository_full_names
required

A list of full repository names that were skipped. This list may not include all repositories that were skipped.

Array<string>
no_codeql_db_repos
required
object
repository_count
required

The total number of repositories that were skipped for this reason.

integer
repositories
required

A list of repositories that were skipped. This list may not include all repositories that were skipped. This is only available when the repository was found and the user has access to it.

Array<object>
Repository Identifier

Repository Identifier

object
id
required

A unique identifier of the repository.

integer
name
required

The name of the repository.

string
full_name
required

The full, globally unique, name of the repository.

string
private
required

Whether the repository is private.

boolean
stargazers_count
required
integer
updated_at
required
string format: date-time
nullable
over_limit_repos
required
object
repository_count
required

The total number of repositories that were skipped for this reason.

integer
repositories
required

A list of repositories that were skipped. This list may not include all repositories that were skipped. This is only available when the repository was found and the user has access to it.

Array<object>
Repository Identifier

Repository Identifier

object
id
required

A unique identifier of the repository.

integer
name
required

The name of the repository.

string
full_name
required

The full, globally unique, name of the repository.

string
private
required

Whether the repository is private.

boolean
stargazers_count
required
integer
updated_at
required
string format: date-time
nullable
Examples

Response for a successful variant analysis submission 

{
  "summary": "Default response",
  "value": {
    "id": 1,
    "controller_repo": {
      "id": 1296269,
      "node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
      "name": "Hello-World",
      "full_name": "octocat/Hello-World",
      "owner": {
        "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
      },
      "private": false,
      "html_url": "https://github.com/octocat/Hello-World",
      "description": "This your first repo!",
      "fork": false,
      "url": "https://api.github.com/repos/octocat/Hello-World",
      "archive_url": "https://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
      "assignees_url": "https://api.github.com/repos/octocat/Hello-World/assignees{/user}",
      "blobs_url": "https://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
      "branches_url": "https://api.github.com/repos/octocat/Hello-World/branches{/branch}",
      "collaborators_url": "https://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
      "comments_url": "https://api.github.com/repos/octocat/Hello-World/comments{/number}",
      "commits_url": "https://api.github.com/repos/octocat/Hello-World/commits{/sha}",
      "compare_url": "https://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
      "contents_url": "https://api.github.com/repos/octocat/Hello-World/contents/{+path}",
      "contributors_url": "https://api.github.com/repos/octocat/Hello-World/contributors",
      "deployments_url": "https://api.github.com/repos/octocat/Hello-World/deployments",
      "downloads_url": "https://api.github.com/repos/octocat/Hello-World/downloads",
      "events_url": "https://api.github.com/repos/octocat/Hello-World/events",
      "forks_url": "https://api.github.com/repos/octocat/Hello-World/forks",
      "git_commits_url": "https://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
      "git_refs_url": "https://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
      "git_tags_url": "https://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
      "issue_comment_url": "https://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
      "issue_events_url": "https://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
      "issues_url": "https://api.github.com/repos/octocat/Hello-World/issues{/number}",
      "keys_url": "https://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
      "labels_url": "https://api.github.com/repos/octocat/Hello-World/labels{/name}",
      "languages_url": "https://api.github.com/repos/octocat/Hello-World/languages",
      "merges_url": "https://api.github.com/repos/octocat/Hello-World/merges",
      "milestones_url": "https://api.github.com/repos/octocat/Hello-World/milestones{/number}",
      "notifications_url": "https://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
      "pulls_url": "https://api.github.com/repos/octocat/Hello-World/pulls{/number}",
      "releases_url": "https://api.github.com/repos/octocat/Hello-World/releases{/id}",
      "stargazers_url": "https://api.github.com/repos/octocat/Hello-World/stargazers",
      "statuses_url": "https://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
      "subscribers_url": "https://api.github.com/repos/octocat/Hello-World/subscribers",
      "subscription_url": "https://api.github.com/repos/octocat/Hello-World/subscription",
      "tags_url": "https://api.github.com/repos/octocat/Hello-World/tags",
      "teams_url": "https://api.github.com/repos/octocat/Hello-World/teams",
      "trees_url": "https://api.github.com/repos/octocat/Hello-World/git/trees{/sha}",
      "hooks_url": "https://api.github.com/repos/octocat/Hello-World/hooks"
    },
    "actor": {
      "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
    },
    "query_language": "python",
    "query_pack_url": "https://www.example.com",
    "created_at": "2022-09-12T12:14:32Z",
    "updated_at": "2022-09-12T12:14:32Z",
    "completed_at": "2022-09-12T13:15:33Z",
    "status": "succeeded",
    "actions_workflow_run_id": 3453588,
    "scanned_repositories": [
      {
        "repository": {
          "id": 1296269,
          "name": "Hello-World",
          "full_name": "octocat/Hello-World",
          "private": false
        },
        "analysis_status": "succeeded",
        "result_count": 532,
        "artifact_size_in_bytes": 12345
      }
    ],
    "skipped_repositories": {
      "access_mismatch_repos": {
        "repository_count": 2,
        "repositories": [
          {
            "id": 1,
            "name": "octo-repo1",
            "full_name": "octo-org/octo-repo1",
            "private": false
          },
          {
            "id": 2,
            "name": "octo-repo2",
            "full_name": "octo-org/octo-repo2",
            "private": false
          }
        ]
      },
      "not_found_repos": {
        "repository_count": 3,
        "repository_full_names": [
          "octo-org/octo-repo4",
          "octo-org/octo-repo5",
          "octo-org/octo-repo6"
        ]
      },
      "no_codeql_db_repos": {
        "repository_count": 2,
        "repositories": [
          {
            "id": 7,
            "name": "octo-repo7",
            "full_name": "octo-org/octo-repo7",
            "private": false
          },
          {
            "id": 8,
            "name": "octo-repo8",
            "full_name": "octo-org/octo-repo8",
            "private": false
          }
        ]
      },
      "over_limit_repos": {
        "repository_count": 2,
        "repositories": [
          {
            "id": 9,
            "name": "octo-repo9",
            "full_name": "octo-org/octo-repo9",
            "private": false
          },
          {
            "id": 10,
            "name": "octo-repo10",
            "full_name": "octo-org/octo-repo10",
            "private": false
          }
        ]
      }
    }
  }
}

404

Section titled “ 404 ”

Resource not found

Media type application/json
Basic Error

Basic Error

object
message
string
documentation_url
string
url
string
status
string
Example generated 
{
  "message": "example",
  "documentation_url": "example",
  "url": "example",
  "status": "example"
}

422

Section titled “ 422 ”

Unable to process variant analysis submission

Media type application/json
Basic Error

Basic Error

object
message
string
documentation_url
string
url
string
status
string
Example generated 
{
  "message": "example",
  "documentation_url": "example",
  "url": "example",
  "status": "example"
}

503

Section titled “ 503 ”

Service unavailable

Media type application/json
object
code
string
message
string
documentation_url
string
Example generated 
{
  "code": "example",
  "message": "example",
  "documentation_url": "example"
}