GitHub v3 REST API

List check runs in a check suite **Note:** The Checks API only looks for pushes in the repository where the check suite or check run were created. Pushes to a branch in a forked repository are not detected and return an empty `pull_requests` array. Lists check runs for a check suite using its `id`. GitHub Apps must have the `checks:read` permission on a private repository or pull access to a public repository to get check runs. OAuth Apps and authenticated users must have the `repo` scope to get check runs in a private repository.

List check suites for a Git reference **Note:** The Checks API only looks for pushes in the repository where the check suite or check run were created. Pushes to a branch in a forked repository are not detected and return an empty `pull_requests` array and a `null` value for `head_branch`. Lists check suites for a commit `ref`. The `ref` can be a SHA, branch name, or a tag name. GitHub Apps must have the `checks:read` permission on a private repository or pull access to a public repository to list check suites. OAuth Apps and authenticated users must have the `repo` scope to get check suites in a private repository.

Rerequest a check run Triggers GitHub to rerequest an existing check run, without pushing new code to a repository. This endpoint will trigger the [`check_run` webhook](https://docs.github.com/[email protected]/webhooks/event-payloads/#check_run) event with the action `rerequested`. When a check run is `rerequested`, its `status` is reset to `queued` and the `conclusion` is cleared. To rerequest a check run, your GitHub App must have the `checks:read` permission on a private repository or pull access to a public repository.

Rerequest a check suite Triggers GitHub to rerequest an existing check suite, without pushing new code to a repository. This endpoint will trigger the [`check_suite` webhook](https://docs.github.com/[email protected]/webhooks/event-payloads/#check_suite) event with the action `rerequested`. When a check suite is `rerequested`, its `status` is reset to `queued` and the `conclusion` is cleared. To rerequest a check suite, your GitHub App must have the `checks:read` permission on a private repository or pull access to a public repository.

Update repository preferences for check suites Changes the default automatic flow when creating check suites. By default, a check suite is automatically created each time code is pushed to a repository. When you disable the automatic creation of check suites, you can manually [Create a check suite](https://docs.github.com/[email protected]/rest/reference/checks#create-a-check-suite). You must have admin permissions in the repository to set preferences for check suites.

Update a check run **Note:** The Checks API only looks for pushes in the repository where the check suite or check run were created. Pushes to a branch in a forked repository are not detected and return an empty `pull_requests` array. Updates a check run for a specific commit in a repository. Your GitHub App must have the `checks:write` permission to edit check runs.

Delete a code scanning analysis from a repository Deletes a specified code scanning analysis from a repository. For private repositories, you must use an access token with the `repo` scope. For public repositories, you must use an access token with `public_repo` and `repo:security_events` scopes. GitHub Apps must have the `security_events` write permission to use this endpoint. 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. **Note**: The ability to delete analyses was introduced in GitHub Enterprise Server 3.1. You can delete analyses that were generated prior to installing this release, however, if you do so, you will lose information about fixed alerts for all such analyses, for the relevant code scanning tool. We recommend that you only delete analyses that were generated with earlier releases if you don't need the details of fixed alerts from pre-3.1 releases. When you list the analyses for a repository, one or more will be identified as deletable in the response: ``` "deletable": true ``` 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` * `analysis_key` * `environment` 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: ``` Analysis specified is not deletable. ``` The response from a successful `DELETE` operation provides you with two alternative URLs for deleting the next analysis in the set (see the example default response below). Use the `next_analysis_url` URL if you want to avoid accidentally deleting the final analysis in the 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 the deletable analysis for one of the sets, step through deleting the analyses in that set, and 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.

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. **Deprecation notice**: The instances field is deprecated and will, in future, not be included in the response for this endpoint. The example response reflects this change. The same information can now be retrieved via a GET request to the URL specified by `instances_url`.

Get a code scanning analysis for a repository Gets a specified code scanning analysis 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. 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. If you use the Accept header `application/sarif+json`, the response contains the analysis data that was uploaded. This is formatted as [SARIF version 2.1.0](https://docs.oasis-open.org/sarif/sarif/v2.1.0/cs01/sarif-v2.1.0-cs01.html).

Get information about a SARIF upload Gets information about a SARIF upload, including the status and the URL of the analysis that was uploaded so that you can retrieve details of the analysis. For more information, see "[Get a code scanning analysis for a repository](/rest/reference/code-scanning#get-a-code-scanning-analysis-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.

List instances of a code scanning alert Lists all instances of the specified 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.

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. The response includes a `most_recent_instance` object. This provides details of the most recent instance of this alert for the default branch or for the specified Git reference (if you used `ref` in the request).

List code scanning analyses for a repository 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. 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. **Deprecation notice**: The `tool_name` field is deprecated 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.

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.

Upload an analysis as SARIF data Uploads SARIF data 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. There are two places where you can upload code scanning results. - If you upload to a pull request, for example `--ref refs/pull/42/merge` or `--ref refs/pull/42/head`, then the results appear as alerts in a pull request check. For more information, see "[Triaging code scanning alerts in pull requests](/code-security/secure-coding/triaging-code-scanning-alerts-in-pull-requests)." - If you upload to a branch, for example `--ref refs/heads/my-branch`, then the results appear in the **Security** tab for your repository. For more information, see "[Managing code scanning alerts for your repository](/code-security/secure-coding/managing-code-scanning-alerts-for-your-repository#viewing-the-alerts-for-a-repository)." You must compress the SARIF-formatted analysis data that you want to upload, using `gzip`, and then encode it as a Base64 format string. For example: ``` gzip -c analysis-data.sarif | base64 -w0 ``` SARIF upload supports a maximum number of entries per the following data objects, and an analysis will be rejected if any of these objects is above its maximum value. For some objects, there are additional values over which the entries will be ignored while keeping the most important entries whenever applicable. To get the most out of your analysis when it includes data above the supported limits, try to optimize the analysis configuration. For example, for the CodeQL tool, identify and remove the most noisy queries. | **SARIF data** | **Maximum values** | **Additional limits** | |----------------------------------|:------------------:|----------------------------------------------------------------------------------| | Runs per file | 15 | | | Results per run | 25,000 | Only the top 5,000 results will be included, prioritized by severity. | | Rules per run | 25,000 | | | Thread Flow Locations per result | 10,000 | Only the top 1,000 Thread Flow Locations will be included, using prioritization. | | Location per result | 1,000 | Only 100 locations will be included. | The `202 Accepted` response includes an `id` value. You can use this ID to check the status of the upload by using it in the `/sarifs/{sarif_id}` endpoint. For more information, see "[Get information about a SARIF upload](/rest/reference/code-scanning#get-information-about-a-sarif-upload)."

Get all codes of conduct

Get a code of conduct

Get emojis Lists all the emojis available to use on GitHub Enterprise Server.

Add an authorized SSH key **Note:** The request body for this operation must be submitted as `application/x-www-form-urlencoded` data. You can submit a parameter value as a string, or you can use a tool such as `curl` to submit a parameter value as the contents of a text file. For more information, see the [`curl` documentation](https://curl.se/docs/manpage.html#--data-urlencode).

Add organization access to a self-hosted runner group in an enterprise Adds an organization to the list of selected organizations that can access a self-hosted runner group. The runner group must have `visibility` set to `selected`. For more information, see "[Create a self-hosted runner group for an enterprise](#create-a-self-hosted-runner-group-for-an-enterprise)." You must authenticate using an access token with the `manage_runners:enterprise` scope to use this endpoint.

Add a self-hosted runner to a group for an enterprise Adds a self-hosted runner to a runner group configured in an enterprise. You must authenticate using an access token with the `manage_runners:enterprise` scope to use this endpoint.

Create a GitHub license When you boot a GitHub instance for the first time, you can use the following endpoint to upload a license. Note that you need to `POST` to [`/setup/api/configure`](https://docs.github.com/[email protected]/rest/reference/enterprise-admin#start-a-configuration-process) to start the actual configuration process. When using this endpoint, your GitHub instance must have a password set. This can be accomplished two ways: 1. If you're working directly with the API before accessing the web interface, you must pass in the password parameter to set your password. 2. If you set up your instance via the web interface before accessing the API, your calls to this endpoint do not need the password parameter. **Note:** The request body for this operation must be submitted as `multipart/form-data` data. You can can reference the license file by prefixing the filename with the `@` symbol using `curl`. For more information, see the [`curl` documentation](https://curl.se/docs/manpage.html#-F).

Create a global webhook

Create an impersonation OAuth token

Create an organization

Create a pre-receive environment

Create a pre-receive hook

Create a registration token for an enterprise Returns a token that you can pass to the `config` script. The token expires after one hour. You must authenticate using an access token with the `manage_runners:enterprise` scope to use this endpoint. #### Example using registration token Configure your self-hosted runner, replacing `TOKEN` with the registration token provided by this endpoint. ``` ./config.sh --url https://github.com/enterprises/octo-enterprise --token TOKEN ```

Create a remove token for an enterprise Returns a token that you can pass to the `config` script to remove a self-hosted runner from an enterprise. The token expires after one hour. You must authenticate using an access token with the `manage_runners:enterprise` scope to use this endpoint. #### Example using remove token To remove your self-hosted runner from an enterprise, replace `TOKEN` with the remove token provided by this endpoint. ``` ./config.sh remove --token TOKEN ```

Create a self-hosted runner group for an enterprise Creates a new self-hosted runner group for an enterprise. You must authenticate using an access token with the `manage_runners:enterprise` scope to use this endpoint.

Create a user If an external authentication mechanism is used, the login name should match the login name in the external system. If you are using LDAP authentication, you should also [update the LDAP mapping](https://docs.github.com/[email protected]/rest/reference/enterprise-admin#update-ldap-mapping-for-a-user) for the user. The login name will be normalized to only contain alphanumeric characters or single hyphens. For example, if you send `"octo_cat"` as the login, a user named `"octo-cat"` will be created. If the login name or email address is already associated with an account, the server will return a `422` response.

Delete a global webhook

Delete an impersonation OAuth token

Delete a personal access token Deletes a personal access token. Returns a `403 - Forbidden` status when a personal access token is in use. For example, if you access this endpoint with the same personal access token that you are trying to delete, you will receive this error.

Delete a pre-receive environment If you attempt to delete an environment that cannot be deleted, you will receive a `422 Unprocessable Entity` response. The possible error messages are: * _Cannot modify or delete the default environment_ * _Cannot delete environment that has hooks_ * _Cannot delete environment when download is in progress_

Delete a pre-receive hook

Delete a public key

Delete a self-hosted runner from an enterprise Forces the removal of a self-hosted runner from an enterprise. You can use this endpoint to completely remove the runner when the machine you were using no longer exists. You must authenticate using an access token with the `manage_runners:enterprise` scope to use this endpoint.

Delete a self-hosted runner group from an enterprise Deletes a self-hosted runner group for an enterprise. You must authenticate using an access token with the `manage_runners:enterprise` scope to use this endpoint.

Delete a user Deleting a user will delete all their repositories, gists, applications, and personal settings. [Suspending a user](https://docs.github.com/[email protected]/rest/reference/enterprise-admin#suspend-a-user) is often a better option. You can delete any user account except your own.

Demote a site administrator You can demote any user account except your own.

Disable a selected organization for GitHub Actions in an enterprise Removes an organization from the list of selected organizations that are enabled for GitHub Actions in an enterprise. To use this endpoint, the enterprise permission policy for `enabled_organizations` must be configured to `selected`. For more information, see "[Set GitHub Actions permissions for an enterprise](#set-github-actions-permissions-for-an-enterprise)." You must authenticate using an access token with the `admin:enterprise` scope to use this endpoint.

Enable or disable maintenance mode **Note:** The request body for this operation must be submitted as `application/x-www-form-urlencoded` data. You can submit a parameter value as a string, or you can use a tool such as `curl` to submit a parameter value as the contents of a text file. For more information, see the [`curl` documentation](https://curl.se/docs/manpage.html#--data-urlencode).

Enable a selected organization for GitHub Actions in an enterprise Adds an organization to the list of selected organizations that are enabled for GitHub Actions in an enterprise. To use this endpoint, the enterprise permission policy for `enabled_organizations` must be configured to `selected`. For more information, see "[Set GitHub Actions permissions for an enterprise](#set-github-actions-permissions-for-an-enterprise)." You must authenticate using an access token with the `admin:enterprise` scope to use this endpoint.

Get all authorized SSH keys

Get all statistics

Get allowed actions for an enterprise Gets the selected actions that are allowed in an enterprise. To use this endpoint, the enterprise permission policy for `allowed_actions` must be configured to `selected`. For more information, see "[Set GitHub Actions permissions for an enterprise](#set-github-actions-permissions-for-an-enterprise)." You must authenticate using an access token with the `admin:enterprise` scope to use this endpoint.

Get the global announcement banner Gets the current message and expiration date of the global announcement banner in your enterprise.

Get the audit log for an enterprise Gets the audit log for an enterprise. To use this endpoint, you must be an enterprise admin, and you must use an access token with the `admin:enterprise` scope.

Get comment statistics