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

Create a CodeQL variant analysis

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.

RetriesRetries up to 2×, 500ms backoff, 30s timeout.

2 parameters · 5 body fields

ownerstringrequired

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

repostringrequired

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

languagestringrequired

The language targeted by the CodeQL query

Allowed:actionscppcsharpgojavajavascriptpythonrubyrustswift

query_packstringrequired

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

repositoriesarray<string>optional

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.

repository_listsarray<string>optional

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

repository_ownersarray<string>optional

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.

4 status codes

201Variant analysis submitted for processing

idintegerrequired

The ID of the variant analysis.

controller_repoobjectrequired

A GitHub repository.

actorobjectrequired

A GitHub user.

query_languagestringrequired

The language targeted by the CodeQL query

Allowed:actionscppcsharpgojavajavascriptpythonrubyrustswift

query_pack_urlstringrequired

The download url for the query pack.

created_atstringoptional

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

updated_atstringoptional

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

completed_atstringoptional

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.

statusstringrequired

Allowed:in_progresssucceededfailedcancelled

actions_workflow_run_idintegeroptional

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

failure_reasonstringoptional

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

Allowed:no_repos_queriedactions_workflow_run_failedinternal_error

scanned_repositoriesarray<object>optional

skipped_repositoriesobjectoptional

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

404Resource not found

messagestringoptional

documentation_urlstringoptional

urlstringoptional

statusstringoptional

422Unable to process variant analysis submission

messagestringoptional

documentation_urlstringoptional

urlstringoptional

statusstringoptional

503Service unavailable

codestringoptional

messagestringoptional

documentation_urlstringoptional

Error handling

A 404 is returned: Resource not found. A 422 is returned: Unable to process variant analysis submission. A 503 is returned: Service unavailable.

import { Client } from "acme-sdk";

const client = new Client({
  baseUrl: "https://api.acme.com",
  auth: { bearer: process.env.API_TOKEN },
  retry: {
    maxAttempts: 3,
    retryOn: [
      408,
      425,
      429,
      500,
      502,
      503,
      504,
    ],
    backoffMs: 500,
    maxBackoffMs: 8000,
  },
  timeoutMs: 30000,
});

const result = await client.variantAnalyses.create({
  owner: "octocat",
  repo: "hello-world",
  language: "example",
  queryPack: "example",
  repositories: "hello-world",
});

{
  "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
          }
        ]
      }
    }
  }
}

Request

Response

Errors