octokit/rest.js
Usage
Import the Octokit constructor based on your platform.
Browsers
@octokit/rest
directly from esm.sh
<script type="module">
import { Octokit } from "https://esm.sh/@octokit/rest";
</script>
Node
npm install @octokit/rest
import { Octokit } from "@octokit/rest";
import { Octokit } from "@octokit/rest";
Now instantiate your octokit API. All options are optional, but authentication is strongly encouraged.
const octokit = new Octokit({
You can set auth
to a personal access token string.
Learn more about authentication.
auth: "secret123",
Setting a user agent is required. It defaults to octokit/rest.js v1.2.3
where v1.2.3
is the current version of @octokit/rest
, but you should set it to something that identifies your app or script.
userAgent: 'myApp v1.2.3',
API Previews can be enabled globally by setting the previews
option. They can be set per-request as well.
Learn more about API Previews.
previews: ['jean-grey', 'symmetra'],
A default time zone can be enabled by setting the timeZone
option.
timeZone: 'Europe/Amsterdam',
Learn more about using time zones with the GitHub API.
In order to use Octokit with GitHub Enterprise, set the baseUrl
option.
baseUrl: 'https://api.github.com',
For custom logging, pass an object with debug
, info
, warn
and error
methods as the log
option.
Learn more about logging and debugging.
log: {
debug: () => {},
info: () => {},
warn: console.warn,
error: console.error
},
Custom request options can be passed as request.*
options. See @octokit/request
options. The same options can be passed to each endpoint request method.
request: {
agent: undefined,
fetch: undefined,
timeout: 0
}
})
Most of GitHub’s REST API endpoints have matching methods. All endpoint methods are asynchronous, in order to use await
in the code examples, we wrap them into an anonymous async function.
(async () => {
For example to retrieve a pull request, use octokit.rest.pulls.get()
. We recommend to use the search above to find the endpoint method you are looking for
const { data: pullRequest } = await octokit.rest.pulls.get({
owner: "octokit",
repo: "rest.js",
pull_number: 123,
});
Some API endpoints support alternative response formats, see Media types. For example, to request the above pull request in a diff format, pass the mediaType.format
option.
Learn more about request formats.
const { data: diff } = await octokit.rest.pulls.get({
owner: "octokit",
repo: "rest.js",
pull_number: 123,
mediaType: {
format: "diff",
},
});
For the API endpoints that do not have a matching method, such as the root endpoint or legacy endpoints, you can send custom requests.
Learn more about custom requests.
const { data: root } = await octokit.request("GET /");
You can also register custom endpoint methods, which is particularly useful if you participate in a private beta.
Learn more about custom endpoint methods.
await octokit.registerEndpoints({
misc: {
getRoot: {
method: "GET",
url: "/",
},
},
});
Some endpoints return a list which has to be paginated in order to retrieve the complete data set.
Learn more about pagination.
octokit.paginate(octokit.rest.issues.listForRepo, {
owner: 'octokit',
repo: 'rest.js'
})
.then(issues => {
// issues is an array of all issue objects
})
})
You can add more functionality with plugins. We recommend the retry and throttling plugins.
Learn more about throttling, automatic retries and building your own Plugins.
import { retry } from "@octokit/plugin-retry";
import { throttling } from "@octokit/plugin-throttling";
const MyOctokit = Octokit.plugin(retry, throttling);
Octokit.plugin()
returns a new constructor. The same options can be passed to the constructor. The options are passed on to all plugin functions as the 2nd argument.
const myOctokit = new MyOctokit({
auth: "secret123",
throttle: {
onRateLimit: (retryAfter, options) => {
myOctokit.log.warn(
`Request quota exhausted for request ${options.method} ${options.url}`,
);
if (options.request.retryCount === 0) {
// only retries once
myOctokit.log.info(`Retrying after ${retryAfter} seconds!`);
return true;
}
},
onSecondaryRateLimit: (retryAfter, options, octokit) => {
// does not retry, only logs a warning
octokit.log.warn(
`Secondary quota detected for request ${options.method} ${options.url}`,
);
},
},
retry: {
doNotRetry: ["429"],
},
});
Authentication
Authentication is optional for some REST API endpoints accessing public data, but is required for GraphQL queries. Using authentication also increases your API rate limit.
GitHub supports different authentication strategies:
- Personal access token (create). This is the default authentication strategy. Set the
options.auth
option to the token innew Octokit(options)
. Learn more about the built-in@octokit/auth-token
authentication strategy. - OAuth Apps: authenticate using user access token created by an OAuth app, to which you granted selected permissions, or as the OAuth App itself (OAuth using
client_id
andclient_secret
). Learn more about the optional@octokit/auth-oauth-app
authentication strategy - GitHub Apps: authenticate using an installation access token or as GitHub App itself. Learn more about the optional
@octokit/auth-app
authentication strategy. - GitHub Actions: authenticate using the
GITHUB_TOKEN
secret which is provided to GitHub Actions Workflows. Learn more about the optional@octokit/auth-action
authentication strategy.
Learn more about all official and community authentication strategies.
By default, @octokit/rest
authenticates using the token authentication strategy. Pass in a token using options.auth
. It can be a personal access token, an OAuth token, an installation access token or a JSON Web Token for GitHub App authentication. The Authorization
request header will be set according to the type of token.
import { Octokit } from "@octokit/rest";
const octokit = new Octokit({
auth: "mypersonalaccesstoken123",
});
// sends request with `Authorization: token mypersonalaccesstoken123` header
const { data } = await octokit.request("/user");
To use a different authentication strategy, set options.authStrategy
.
Here is an example for GitHub App authentication
import { Octokit } from "@octokit/rest";
import { createAppAuth } from "@octokit/auth-app";
const appOctokit = new Octokit({
authStrategy: createAppAuth,
auth: {
appId: 123,
privateKey: process.env.PRIVATE_KEY,
// optional: this will make appOctokit authenticate as app (JWT)
// or installation (access token), depending on the request URL
installationId: 123,
},
});
const { data } = await appOctokit.request("/app");
The .auth()
method returned by the current authentication strategy can be accessed at octokit.auth()
. Example
const { token } = await appOctokit.auth({
type: "installation",
// defaults to `options.auth.installationId` set in the constructor
installationId: 123,
});
Request formats & aborts
Some API endpoints support alternative response formats, see Media types.
For example, to request a pull request as diff format, set the mediaType.format
option
const { data: prDiff } = await octokit.rest.pulls.get({
owner: "octokit",
repo: "rest.js",
pull_number: 1278,
mediaType: {
format: "diff",
},
});
The AbortController interface can be used to abort one or more requests as and when desired. When the request is initiated, an AbortSignal instance can be passed as an option inside the request's options object.
const controller = new AbortController();
const { data: prDiff } = await octokit.rest.pulls.get({
owner: "octokit",
repo: "rest.js",
pull_number: 1278,
request: {
signal: controller.signal,
},
});
Use controller.abort()
to abort the request when desired.
Custom requests
To send custom requests you can use the lower-level octokit.request()
method
octokit.request("GET /");
The baseUrl
, headers and other defaults are already set. For more information on the octokit.request()
API see octokit/request.js
All the endpoint methods such as octokit.rest.repos.get()
are aliases of octokit.request()
with pre-bound default options. So you can use the @octokit/request
API to get the default options or get generic request option to use with your preferred request library.
const defaultOptions = octokit.rest.repos.get.endpoint.DEFAULTS;
const requestOptions = octokit.rest.repos.get.endpoint({
owner: "octokit",
repo: "rest.js",
});
Note that authentication is not applied when retrieving request options from the *.endpoint
APIs.
Pagination
All endpoint methods starting with .list*
do not return all results at once but instead return the first 30 items by default, see also GitHub’s REST API pagination documentation.
To automatically receive all results across all pages, you can use the octokit.paginate()
method:
octokit
.paginate("GET /repos/{owner}/{repo}/issues", {
owner: "octokit",
repo: "rest.js",
})
.then((issues) => {
// issues is an array of all issue objects. It is not wrapped in a { data, headers, status, url } object
// like results from `octokit.request()` or any of the endpoint methods such as `octokit.rest.issues.listForRepo()`
});
octokit.paginate()
accepts the same options as octokit.request()
. You can optionally pass an additional function to map the results from each response. The map must return a new value, usually an array with mapped data.
Note: the map function is called with the { data, headers, status, url }
response object. The data
property is guaranteed to be an array of the result items, even for list endpoints that respond with an object instead of an array, such as the search endpoints.
octokit
.paginate(
"GET /repos/{owner}/{repo}/issues",
{ owner: "octokit", repo: "rest.js" },
(response) => response.data.map((issue) => issue.title),
)
.then((issueTitles) => {
// issueTitles is now an array with the titles only
});
To stop paginating early, you can call the done()
function passed as 2nd argument to the response map function. Note that you still have to return the value you want to map the response to, otherwise the last response will be mapped to undefined.
octokit.paginate(
"GET /repos/{owner}/{repo}/issues",
{ owner: "octokit", repo: "rest.js" },
(response, done) => {
if (response.data.find((issue) => issue.body.includes("something"))) {
done();
}
return response.data;
},
);
To paginate responses for one of the registered endpoint methods such as octokit.rest.issues.listForRepo()
you can pass the method directly as first argument to octokit.paginate
:
octokit
.paginate(octokit.rest.issues.listForRepo, {
owner: "octokit",
repo: "rest.js",
})
.then((issues) => {
// issues is an array of all issue objects
});
If your runtime environment supports async iterators (such as most modern browsers and Node 10+), you can iterate through each response
for await (const response of octokit.paginate.iterator(
octokit.rest.issues.listForRepo,
{
owner: "octokit",
repo: "rest.js",
},
)) {
// do whatever you want with each response, break out of the loop, etc.
}
octokit.paginate.iterator()
accepts the same options as octokit.paginate()
.
Hooks
You can customize Octokit’s request lifecycle with hooks. Available methods are
octokit.hook.before("request", async (options) => {
validate(options);
});
octokit.hook.after("request", async (response, options) => {
console.log(`${options.method} ${options.url}: ${response.status}`);
});
octokit.hook.error("request", async (error, options) => {
if (error.status === 304) {
return findInCache(error.response.headers.etag);
}
throw error;
});
octokit.hook.wrap("request", async (request, options) => {
// add logic before, after, catch errors or replace the request altogether
return request(options);
});
See before-after-hook for more details on the 4 methods.
Custom endpoint methods
You can register custom endpoint methods such as octokit.rest.repos.get()
by extending the octokit object
Object.assign(octokit.foo, {
bar: {
method: "PATCH",
url: "/repos/{owner}/{repo}/foo",
headers: {
accept: "application/vnd.github.foo-bar-preview+json",
},
params: {
owner: {
required: true,
type: "string",
},
repo: {
required: true,
type: "string",
},
baz: {
required: true,
type: "string",
enum: ["qux", "quux", "quuz"],
},
},
},
});
octokit.foo.bar({
owner: "octokit",
repo: "rest.js",
baz: "quz",
});
This is useful when you participate in private beta features and prefer the convenience of methods for the new endpoints instead of using octokit.request()
.
Plugins
You can customize and extend Octokit’s functionality using plugins
// index.js
import { Octokit } from "@octokit/rest";
import myPlugin from "./lib/my-plugin.js";
import octokitPluginExample from "octokit-plugin-example";
const MyOctokit = Octokit.plugin(myPlugin, octokitPluginExample);
// lib/my-plugin.js
const plugin = (octokit, options = { greeting: "Hello" }) => {
// hook into the request lifecycle
octokit.hook.wrap("request", async (request, options) => {
const time = Date.now();
const response = await request(options);
octokit.log.info(
`${options.method} ${options.url} – ${response.status} in ${
Date.now() - time
}ms`,
);
return response;
});
// add a custom method: octokit.helloWorld()
return {
helloWorld: () => console.log(`${options.greeting}, world!`),
};
};
export default plugin;
.plugin
accepts a function or an array of functions.
We recommend using Octokit’s log methods to help users of your plugin with debugging.
You can add new methods to the octokit
instance passed as the first argument to
the plugin function. The 2nd argument is the options object passed to the
constructor when instantiating the octokit
client.
const octokit = new MyOctokit({ greeting: "Hola" });
octokit.helloWorld();
// Hola, world!
Throttling
When you send too many requests in too little time you will likely hit errors due to rate and/or abuse limits.
In order to automatically throttle requests as recommended in GitHub’s best practices for integrators, we recommend you install the @octokit/plugin-throttling
plugin.
The throttle.onSecondaryRateLimit
and throttle.onRateLimit
options are required.
Return true
from these functions to automatically retry the request after retryAfter
seconds. Return false
or undefined
to skip retry and throw the error. For rate limit errors, retryAfter
defaults to seconds until X-RateLimit-Reset
. For abuse errors, retryAfter
defaults to the retry-after
header but is a minimum of five seconds.
import { Octokit } from "@octokit/rest";
import { throttling } from "@octokit/plugin-throttling";
const MyOctokit = Octokit.plugin(throttling);
const octokit = new MyOctokit({
auth: "token " + process.env.TOKEN,
throttle: {
onRateLimit: (retryAfter, options) => {
octokit.log.warn(
`Request quota exhausted for request ${options.method} ${options.url}`,
);
// Retry twice after hitting a rate limit error, then give up
if (options.request.retryCount <= 2) {
console.log(`Retrying after ${retryAfter} seconds!`);
return true;
}
},
onSecondaryRateLimit: (retryAfter, options, octokit) => {
// does not retry, only logs a warning
octokit.log.warn(
`Secondary quota detected for request ${options.method} ${options.url}`,
);
},
},
});
Automatic retries
Many common request errors can be easily remediated by retrying the request. We recommend installing the @octokit/plugin-retry
plugin for Automatic retries in these cases
import { Octokit } from "@octokit/rest";
import { retry } from "@octokit/plugin-retry";
const MyOctokit = Octokit.plugin(retry);
const octokit = new MyOctokit();
// all requests sent with the `octokit` instance are now retried up to 3 times for recoverable errors.
Logging
Octokit
has 4 built-in log methods
octokit.log.debug(message[, additionalInfo])
octokit.log.info(message[, additionalInfo])
octokit.log.warn(message[, additionalInfo])
octokit.log.error(message[, additionalInfo])
They can be configured using the log
client option. By default, octokit.log.debug()
and octokit.log.info()
are no-ops, while the other two call console.warn()
and console.error()
respectively.
This is useful if you build reusable plugins.
Debug
The simplest way to receive debug information is to set the log
client option to console
.
import { Octokit } from "@octokit/rest";
const octokit = new Octokit({
log: console,
});
octokit.request("/");
This will log
request { method: 'GET',
baseUrl: 'https://api.github.com',
headers:
{ accept: 'application/vnd.github.v3+json',
'user-agent':
'octokit.js/0.0.0-development Node.js/10.15.0 (macOS Mojave; x64)' },
request: {},
url: '/' }
GET / - 200 in 514ms
If you like to support a configurable log level, we recommend using the console-log-level module
import { Octokit } from "@octokit/rest";
import consoleLogLevel from "console-log-level";
const octokit = new Octokit({
log: consoleLogLevel({ level: "info" }),
});
octokit.request("/");
This will only log
GET / - 200 in 514ms
Actions
Add custom labels to a self-hosted runner for an organization
Adds custom labels to a self-hosted runner configured in an organization.
Authenticated users must have admin access to the organization to use this endpoint.
OAuth tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.actions.addCustomLabelsToSelfHostedRunnerForOrg({
org,
runner_id,
labels,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
runner_id | yes |
Unique identifier of the self-hosted runner. |
labels | yes |
The names of the custom labels to add to the runner. |
See also: GitHub Developer Guide documentation.
Add custom labels to a self-hosted runner for a repository
Adds custom labels to a self-hosted runner configured in a repository.
Authenticated users must have admin access to the organization to use this endpoint.
OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.addCustomLabelsToSelfHostedRunnerForRepo({
owner,
repo,
runner_id,
labels,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
runner_id | yes |
Unique identifier of the self-hosted runner. |
labels | yes |
The names of the custom labels to add to the runner. |
See also: GitHub Developer Guide documentation.
Add selected repository to an organization secret
Adds a repository to an organization secret when the visibility
for
repository access is set to selected
. For more information about setting the visibility, see Create or
update an organization secret.
Authenticated users must have collaborator access to a repository to create, update, or read secrets.
OAuth tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint. If the repository is private, OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.addSelectedRepoToOrgSecret({
org,
secret_name,
repository_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
secret_name | yes |
The name of the secret. |
repository_id | yes |
See also: GitHub Developer Guide documentation.
Add selected repository to an organization variable
Adds a repository to an organization variable that is available to selected repositories.
Organization variables that are available to selected repositories have their visibility
field set to selected
.
Authenticated users must have collaborator access to a repository to create, update, or read secrets.
OAuth tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint. If the repository is private, OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.addSelectedRepoToOrgVariable({
org,
name,
repository_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
name | yes |
The name of the variable. |
repository_id | yes |
See also: GitHub Developer Guide documentation.
Approve a workflow run for a fork pull request
Approves a workflow run for a pull request from a public fork of a first time contributor. For more information, see "Approving workflow runs from public forks."
OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.approveWorkflowRun({
owner,
repo,
run_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
run_id | yes |
The unique identifier of the workflow run. |
See also: GitHub Developer Guide documentation.
Cancel a workflow run
Cancels a workflow run using its id
.
OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.cancelWorkflowRun({
owner,
repo,
run_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
run_id | yes |
The unique identifier of the workflow run. |
See also: GitHub Developer Guide documentation.
Create an environment variable
Create an environment variable that you can reference in a GitHub Actions workflow.
Authenticated users must have collaborator access to a repository to create, update, or read variables.
OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.createEnvironmentVariable({
owner,
repo,
environment_name,
name,
value,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
environment_name | yes |
The name of the environment. The name must be URL encoded. For example, any slashes in the name must be replaced with |
name | yes |
The name of the variable. |
value | yes |
The value of the variable. |
See also: GitHub Developer Guide documentation.
Create or update an environment secret
Creates or updates an environment secret with an encrypted value. Encrypt your secret using LibSodium. For more information, see "Encrypting secrets for the REST API."
Authenticated users must have collaborator access to a repository to create, update, or read secrets.
OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.createOrUpdateEnvironmentSecret({
owner,
repo,
environment_name,
secret_name,
encrypted_value,
key_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
environment_name | yes |
The name of the environment. The name must be URL encoded. For example, any slashes in the name must be replaced with |
secret_name | yes |
The name of the secret. |
encrypted_value | yes |
Value for your secret, encrypted with LibSodium using the public key retrieved from the Get an environment public key endpoint. |
key_id | yes |
ID of the key you used to encrypt the secret. |
See also: GitHub Developer Guide documentation.
Create or update an organization secret
Creates or updates an organization secret with an encrypted value. Encrypt your secret using
LibSodium. You must authenticate using an access
token with the admin:org
scope to use this endpoint. GitHub Apps must have the secrets
organization permission to
use this endpoint.
Example encrypting a secret using Node.js
Encrypt your secret using the tweetsodium library.
const sodium = require('tweetsodium');
const key = "base64-encoded-public-key";
const value = "plain-text-secret";
// Convert the message and key to Uint8Array's (Buffer implements that interface)
const messageBytes = Buffer.from(value);
const keyBytes = Buffer.from(key, 'base64');
// Encrypt using LibSodium.
const encryptedBytes = sodium.seal(messageBytes, keyBytes);
// Base64 the encrypted secret
const encrypted = Buffer.from(encryptedBytes).toString('base64');
console.log(encrypted);
Example encrypting a secret using Python
Encrypt your secret using pynacl with Python 3.
from base64 import b64encode
from nacl import encoding, public
def encrypt(public_key: str, secret_value: str) -> str:
"""Encrypt a Unicode string using the public key."""
public_key = public.PublicKey(public_key.encode("utf-8"), encoding.Base64Encoder())
sealed_box = public.SealedBox(public_key)
encrypted = sealed_box.encrypt(secret_value.encode("utf-8"))
return b64encode(encrypted).decode("utf-8")
Example encrypting a secret using C#
Encrypt your secret using the Sodium.Core package.
var secretValue = System.Text.Encoding.UTF8.GetBytes("mySecret");
var publicKey = Convert.FromBase64String("2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvvcCU=");
var sealedPublicKeyBox = Sodium.SealedPublicKeyBox.Create(secretValue, publicKey);
Console.WriteLine(Convert.ToBase64String(sealedPublicKeyBox));
Example encrypting a secret using Ruby
Encrypt your secret using the rbnacl gem.
require "rbnacl"
require "base64"
key = Base64.decode64("+ZYvJDZMHUfBkJdyq5Zm9SKqeuBQ4sj+6sfjlH4CgG0=")
public_key = RbNaCl::PublicKey.new(key)
box = RbNaCl::Boxes::Sealed.from_public_key(public_key)
encrypted_secret = box.encrypt("my_secret")
# Print the base64 encoded secret
puts Base64.strict_encode64(encrypted_secret)
octokit.rest.actions.createOrUpdateOrgSecret({
org,
secret_name,
visibility,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
secret_name | yes |
The name of the secret. |
encrypted_value | no |
Value for your secret, encrypted with LibSodium using the public key retrieved from the Get an organization public key endpoint. |
key_id | no |
ID of the key you used to encrypt the secret. |
visibility | yes |
Which type of organization repositories have access to the organization secret. |
selected_repository_ids | no |
An array of repository ids that can access the organization secret. You can only provide a list of repository ids when the |
See also: GitHub Developer Guide documentation.
Create or update a repository secret
Creates or updates a repository secret with an encrypted value. Encrypt your secret using LibSodium. For more information, see "Encrypting secrets for the REST API."
Authenticated users must have collaborator access to a repository to create, update, or read secrets.
OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.createOrUpdateRepoSecret({
owner,
repo,
secret_name,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
secret_name | yes |
The name of the secret. |
encrypted_value | no |
Value for your secret, encrypted with LibSodium using the public key retrieved from the Get a repository public key endpoint. |
key_id | no |
ID of the key you used to encrypt the secret. |
See also: GitHub Developer Guide documentation.
Create an organization variable
Creates an organization variable that you can reference in a GitHub Actions workflow.
Authenticated users must have collaborator access to a repository to create, update, or read variables.
OAuth tokens and personal access tokens (classic) need theadmin:org
scope to use this endpoint. If the repository is private, OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.createOrgVariable({
org,
name,
value,
visibility,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
name | yes |
The name of the variable. |
value | yes |
The value of the variable. |
visibility | yes |
The type of repositories in the organization that can access the variable. |
selected_repository_ids | no |
An array of repository ids that can access the organization variable. You can only provide a list of repository ids when the |
See also: GitHub Developer Guide documentation.
Create a registration token for an organization
Returns a token that you can pass to the config
script. The token expires after one hour.
For example, you can replace TOKEN
in the following example with the registration token provided by this endpoint to configure your self-hosted runner:
./config.sh --url https://github.com/octo-org --token TOKEN
Authenticated users must have admin access to the organization to use this endpoint.
OAuth tokens and personal access tokens (classic) need theadmin:org
scope to use this endpoint. If the repository is private, OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.createRegistrationTokenForOrg({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
See also: GitHub Developer Guide documentation.
Create a registration token for a repository
Returns a token that you can pass to the config
script. The token expires after one hour.
For example, you can replace TOKEN
in the following example with the registration token provided by this endpoint to configure your self-hosted runner:
./config.sh --url https://github.com/octo-org --token TOKEN
Authenticated users must have admin access to the repository to use this endpoint.
OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.createRegistrationTokenForRepo({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Create a remove token for an organization
Returns a token that you can pass to the config
script to remove a self-hosted runner from an organization. The token expires after one hour.
For example, you can replace TOKEN
in the following example with the registration token provided by this endpoint to remove your self-hosted runner from an organization:
./config.sh remove --token TOKEN
Authenticated users must have admin access to the organization to use this endpoint.
OAuth tokens and personal access tokens (classic) need theadmin:org
scope to use this endpoint. If the repository is private, OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.createRemoveTokenForOrg({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
See also: GitHub Developer Guide documentation.
Create a remove token for a repository
Returns a token that you can pass to the config
script to remove a self-hosted runner from an repository. The token expires after one hour.
For example, you can replace TOKEN
in the following example with the registration token provided by this endpoint to remove your self-hosted runner from an organization:
./config.sh remove --token TOKEN
Authenticated users must have admin access to the repository to use this endpoint.
OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.createRemoveTokenForRepo({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Create a repository variable
Creates a repository variable that you can reference in a GitHub Actions workflow.
Authenticated users must have collaborator access to a repository to create, update, or read variables.
OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.createRepoVariable({
owner,
repo,
name,
value,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
name | yes |
The name of the variable. |
value | yes |
The value of the variable. |
See also: GitHub Developer Guide documentation.
Create a workflow dispatch event
You can use this endpoint to manually trigger a GitHub Actions workflow run. You can replace workflow_id
with the workflow file name. For example, you could use main.yaml
.
You must configure your GitHub Actions workflow to run when the workflow_dispatch
webhook event occurs. The inputs
are configured in the workflow file. For more information about how to configure the workflow_dispatch
event in the workflow file, see "Events that trigger workflows."
OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.createWorkflowDispatch({
owner,
repo,
workflow_id,
ref,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
workflow_id | yes |
The ID of the workflow. You can also pass the workflow file name as a string. |
ref | yes |
The git reference for the workflow. The reference can be a branch or tag name. |
inputs | no |
Input keys and values configured in the workflow file. The maximum number of properties is 10. Any default properties configured in the workflow file will be used when |
inputs.* | no |
See also: GitHub Developer Guide documentation.
Delete a GitHub Actions cache for a repository (using a cache ID)
Deletes a GitHub Actions cache for a repository, using a cache ID.
OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.deleteActionsCacheById({
owner,
repo,
cache_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
cache_id | yes |
The unique identifier of the GitHub Actions cache. |
See also: GitHub Developer Guide documentation.
Delete GitHub Actions caches for a repository (using a cache key)
Deletes one or more GitHub Actions caches for a repository, using a complete cache key. By default, all caches that match the provided key are deleted, but you can optionally provide a Git ref to restrict deletions to caches that match both the provided key and the Git ref.
OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.deleteActionsCacheByKey({
owner,
repo,
key,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
key | yes |
A key for identifying the cache. |
ref | no |
The full Git reference for narrowing down the cache. The |
See also: GitHub Developer Guide documentation.
Delete an artifact
Deletes an artifact for a workflow run.
OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.deleteArtifact({
owner,
repo,
artifact_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
artifact_id | yes |
The unique identifier of the artifact. |
See also: GitHub Developer Guide documentation.
Delete an environment secret
Deletes a secret in an environment using the secret name.
Authenticated users must have collaborator access to a repository to create, update, or read secrets.
OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.deleteEnvironmentSecret({
owner,
repo,
environment_name,
secret_name,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
environment_name | yes |
The name of the environment. The name must be URL encoded. For example, any slashes in the name must be replaced with |
secret_name | yes |
The name of the secret. |
See also: GitHub Developer Guide documentation.
Delete an environment variable
Deletes an environment variable using the variable name.
Authenticated users must have collaborator access to a repository to create, update, or read variables.
OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.deleteEnvironmentVariable({
owner,
repo,
name,
environment_name,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
name | yes |
The name of the variable. |
environment_name | yes |
The name of the environment. The name must be URL encoded. For example, any slashes in the name must be replaced with |
See also: GitHub Developer Guide documentation.
Delete an organization secret
Deletes a secret in an organization using the secret name.
Authenticated users must have collaborator access to a repository to create, update, or read secrets.
OAuth tokens and personal access tokens (classic) need theadmin:org
scope to use this endpoint. If the repository is private, OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.deleteOrgSecret({
org,
secret_name,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
secret_name | yes |
The name of the secret. |
See also: GitHub Developer Guide documentation.
Delete an organization variable
Deletes an organization variable using the variable name.
Authenticated users must have collaborator access to a repository to create, update, or read variables.
OAuth tokens and personal access tokens (classic) need theadmin:org
scope to use this endpoint. If the repository is private, OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.deleteOrgVariable({
org,
name,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
name | yes |
The name of the variable. |
See also: GitHub Developer Guide documentation.
Delete a repository secret
Deletes a secret in a repository using the secret name.
Authenticated users must have collaborator access to a repository to create, update, or read secrets.
OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.deleteRepoSecret({
owner,
repo,
secret_name,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
secret_name | yes |
The name of the secret. |
See also: GitHub Developer Guide documentation.
Delete a repository variable
Deletes a repository variable using the variable name.
Authenticated users must have collaborator access to a repository to create, update, or read variables.
OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.deleteRepoVariable({
owner,
repo,
name,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
name | yes |
The name of the variable. |
See also: GitHub Developer Guide documentation.
Delete a self-hosted runner from an organization
Forces the removal of a self-hosted runner from an organization. You can use this endpoint to completely remove the runner when the machine you were using no longer exists.
Authenticated users must have admin access to the organization to use this endpoint.
OAuth tokens and personal access tokens (classic) need theadmin:org
scope to use this endpoint. If the repository is private, OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.deleteSelfHostedRunnerFromOrg({
org,
runner_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
runner_id | yes |
Unique identifier of the self-hosted runner. |
See also: GitHub Developer Guide documentation.
Delete a self-hosted runner from a repository
Forces the removal of a self-hosted runner from a repository. You can use this endpoint to completely remove the runner when the machine you were using no longer exists.
Authenticated users must have admin access to the repository to use this endpoint.
OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.deleteSelfHostedRunnerFromRepo({
owner,
repo,
runner_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
runner_id | yes |
Unique identifier of the self-hosted runner. |
See also: GitHub Developer Guide documentation.
Delete a workflow run
Deletes a specific workflow run.
Anyone with write access to the repository can use this endpoint.
If the repository is private, OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.deleteWorkflowRun({
owner,
repo,
run_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
run_id | yes |
The unique identifier of the workflow run. |
See also: GitHub Developer Guide documentation.
Delete workflow run logs
Deletes all logs for a workflow run.
OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.deleteWorkflowRunLogs({
owner,
repo,
run_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
run_id | yes |
The unique identifier of the workflow run. |
See also: GitHub Developer Guide documentation.
Disable a selected repository for GitHub Actions in an organization
Removes a repository from the list of selected repositories that are enabled for GitHub Actions in an organization. To use this endpoint, the organization permission policy for enabled_repositories
must be configured to selected
. For more information, see "Set GitHub Actions permissions for an organization."
OAuth tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.actions.disableSelectedRepositoryGithubActionsOrganization({
org,
repository_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
repository_id | yes |
The unique identifier of the repository. |
See also: GitHub Developer Guide documentation.
Disable a workflow
Disables a workflow and sets the state
of the workflow to disabled_manually
. You can replace workflow_id
with the workflow file name. For example, you could use main.yaml
.
OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.disableWorkflow({
owner,
repo,
workflow_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
workflow_id | yes |
The ID of the workflow. You can also pass the workflow file name as a string. |
See also: GitHub Developer Guide documentation.
Download an artifact
Gets a redirect URL to download an archive for a repository. This URL expires after 1 minute. Look for Location:
in
the response header to find the URL for the download. The :archive_format
must be zip
.
OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.downloadArtifact({
owner,
repo,
artifact_id,
archive_format,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
artifact_id | yes |
The unique identifier of the artifact. |
archive_format | yes |
See also: GitHub Developer Guide documentation.
Download job logs for a workflow run
Gets a redirect URL to download a plain text file of logs for a workflow job. This link expires after 1 minute. Look
for Location:
in the response header to find the URL for the download.
Anyone with read access to the repository can use this endpoint.
If the repository is private, OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.downloadJobLogsForWorkflowRun({
owner,
repo,
job_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
job_id | yes |
The unique identifier of the job. |
See also: GitHub Developer Guide documentation.
Download workflow run attempt logs
Gets a redirect URL to download an archive of log files for a specific workflow run attempt. This link expires after
1 minute. Look for Location:
in the response header to find the URL for the download.
Anyone with read access to the repository can use this endpoint.
If the repository is private, OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.downloadWorkflowRunAttemptLogs({
owner,
repo,
run_id,
attempt_number,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
run_id | yes |
The unique identifier of the workflow run. |
attempt_number | yes |
The attempt number of the workflow run. |
See also: GitHub Developer Guide documentation.
Download workflow run logs
Gets a redirect URL to download an archive of log files for a workflow run. This link expires after 1 minute. Look for
Location:
in the response header to find the URL for the download.
Anyone with read access to the repository can use this endpoint.
If the repository is private, OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.downloadWorkflowRunLogs({
owner,
repo,
run_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
run_id | yes |
The unique identifier of the workflow run. |
See also: GitHub Developer Guide documentation.
Enable a selected repository for GitHub Actions in an organization
Adds a repository to the list of selected repositories that are enabled for GitHub Actions in an organization. To use this endpoint, the organization permission policy for enabled_repositories
must be must be configured to selected
. For more information, see "Set GitHub Actions permissions for an organization."
OAuth tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.actions.enableSelectedRepositoryGithubActionsOrganization({
org,
repository_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
repository_id | yes |
The unique identifier of the repository. |
See also: GitHub Developer Guide documentation.
Enable a workflow
Enables a workflow and sets the state
of the workflow to active
. You can replace workflow_id
with the workflow file name. For example, you could use main.yaml
.
OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.enableWorkflow({
owner,
repo,
workflow_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
workflow_id | yes |
The ID of the workflow. You can also pass the workflow file name as a string. |
See also: GitHub Developer Guide documentation.
Force cancel a workflow run
Cancels a workflow run and bypasses conditions that would otherwise cause a workflow execution to continue, such as an always()
condition on a job.
You should only use this endpoint to cancel a workflow run when the workflow run is not responding to POST /repos/{owner}/{repo}/actions/runs/{run_id}/cancel
.
OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.forceCancelWorkflowRun({
owner,
repo,
run_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
run_id | yes |
The unique identifier of the workflow run. |
See also: GitHub Developer Guide documentation.
Create configuration for a just-in-time runner for an organization
Generates a configuration that can be passed to the runner application at startup.
The authenticated user must have admin access to the organization.
OAuth tokens and personal access tokens (classic) need theadmin:org
scope to use this endpoint. If the repository is private, OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.generateRunnerJitconfigForOrg({
org,
name,
runner_group_id,
labels,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
name | yes |
The name of the new runner. |
runner_group_id | yes |
The ID of the runner group to register the runner to. |
labels | yes |
The names of the custom labels to add to the runner. Minimum items: 1. Maximum items: 100. |
work_folder | no |
The working directory to be used for job execution, relative to the runner install directory. |
See also: GitHub Developer Guide documentation.
Create configuration for a just-in-time runner for a repository
Generates a configuration that can be passed to the runner application at startup.
The authenticated user must have admin access to the repository.
OAuth tokens and personal access tokens (classic) need therepo
scope to use this endpoint.
octokit.rest.actions.generateRunnerJitconfigForRepo({
owner,
repo,
name,
runner_group_id,
labels,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
name | yes |
The name of the new runner. |
runner_group_id | yes |
The ID of the runner group to register the runner to. |
labels | yes |
The names of the custom labels to add to the runner. Minimum items: 1. Maximum items: 100. |
work_folder | no |
The working directory to be used for job execution, relative to the runner install directory. |
See also: GitHub Developer Guide documentation.
List GitHub Actions caches for a repository
Lists the GitHub Actions caches for a repository.
OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.getActionsCacheList({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
ref | no |
The full Git reference for narrowing down the cache. The |
key | no |
An explicit key or prefix for identifying the cache |
sort | no |
The property to sort the results by. |
direction | no |
The direction to sort the results by. |
See also: GitHub Developer Guide documentation.
Get GitHub Actions cache usage for a repository
Gets GitHub Actions cache usage for a repository. The data fetched using this API is refreshed approximately every 5 minutes, so values returned from this endpoint may take at least 5 minutes to get updated.
Anyone with read access to the repository can use this endpoint.
If the repository is private, OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.getActionsCacheUsage({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
List repositories with GitHub Actions cache usage for an organization
Lists repositories and their GitHub Actions cache usage for an organization. The data fetched using this API is refreshed approximately every 5 minutes, so values returned from this endpoint may take at least 5 minutes to get updated.
OAuth tokens and personal access tokens (classic) need the read:org
scope to use this endpoint.
octokit.rest.actions.getActionsCacheUsageByRepoForOrg({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
Get GitHub Actions cache usage for an organization
Gets the total GitHub Actions cache usage for an organization. The data fetched using this API is refreshed approximately every 5 minutes, so values returned from this endpoint may take at least 5 minutes to get updated.
OAuth tokens and personal access tokens (classic) need the read:org
scope to use this endpoint.
octokit.rest.actions.getActionsCacheUsageForOrg({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
See also: GitHub Developer Guide documentation.
Get allowed actions and reusable workflows for an organization
Gets the selected actions and reusable workflows that are allowed in an organization. To use this endpoint, the organization permission policy for allowed_actions
must be configured to selected
. For more information, see "Set GitHub Actions permissions for an organization."
OAuth tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.actions.getAllowedActionsOrganization({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
See also: GitHub Developer Guide documentation.
Get allowed actions and reusable workflows for a repository
Gets the settings for selected actions and reusable workflows that are allowed in a repository. To use this endpoint, the repository policy for allowed_actions
must be configured to selected
. For more information, see "Set GitHub Actions permissions for a repository."
OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.getAllowedActionsRepository({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Get an artifact
Gets a specific artifact for a workflow run.
Anyone with read access to the repository can use this endpoint.
If the repository is private, OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.getArtifact({
owner,
repo,
artifact_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
artifact_id | yes |
The unique identifier of the artifact. |
See also: GitHub Developer Guide documentation.
Get the customization template for an OIDC subject claim for a repository
Gets the customization template for an OpenID Connect (OIDC) subject claim.
OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.getCustomOidcSubClaimForRepo({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Get an environment public key
Get the public key for an environment, which you need to encrypt environment secrets. You need to encrypt a secret before you can create or update secrets.
Anyone with read access to the repository can use this endpoint.
If the repository is private, OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.getEnvironmentPublicKey({
owner,
repo,
environment_name,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
environment_name | yes |
The name of the environment. The name must be URL encoded. For example, any slashes in the name must be replaced with |
See also: GitHub Developer Guide documentation.
Get an environment secret
Gets a single environment secret without revealing its encrypted value.
Authenticated users must have collaborator access to a repository to create, update, or read secrets.
OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.getEnvironmentSecret({
owner,
repo,
environment_name,
secret_name,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
environment_name | yes |
The name of the environment. The name must be URL encoded. For example, any slashes in the name must be replaced with |
secret_name | yes |
The name of the secret. |
See also: GitHub Developer Guide documentation.
Get an environment variable
Gets a specific variable in an environment.
Authenticated users must have collaborator access to a repository to create, update, or read variables.
OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.getEnvironmentVariable({
owner,
repo,
environment_name,
name,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
environment_name | yes |
The name of the environment. The name must be URL encoded. For example, any slashes in the name must be replaced with |
name | yes |
The name of the variable. |
See also: GitHub Developer Guide documentation.
Get default workflow permissions for an organization
Gets the default workflow permissions granted to the GITHUB_TOKEN
when running workflows in an organization,
as well as whether GitHub Actions can submit approving pull request reviews. For more information, see
"Setting the permissions of the GITHUB_TOKEN for your organization."
OAuth tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.actions.getGithubActionsDefaultWorkflowPermissionsOrganization({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
See also: GitHub Developer Guide documentation.
Get default workflow permissions for a repository
Gets the default workflow permissions granted to the GITHUB_TOKEN
when running workflows in a repository,
as well as if GitHub Actions can submit approving pull request reviews.
For more information, see "Setting the permissions of the GITHUB_TOKEN for your repository."
OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.getGithubActionsDefaultWorkflowPermissionsRepository({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Get GitHub Actions permissions for an organization
Gets the GitHub Actions permissions policy for repositories and allowed actions and reusable workflows in an organization.
OAuth tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.actions.getGithubActionsPermissionsOrganization({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
See also: GitHub Developer Guide documentation.
Get GitHub Actions permissions for a repository
Gets the GitHub Actions permissions policy for a repository, including whether GitHub Actions is enabled and the actions and reusable workflows allowed to run in the repository.
OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.getGithubActionsPermissionsRepository({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Get a job for a workflow run
Gets a specific job in a workflow run.
Anyone with read access to the repository can use this endpoint.
If the repository is private, OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.getJobForWorkflowRun({
owner,
repo,
job_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
job_id | yes |
The unique identifier of the job. |
See also: GitHub Developer Guide documentation.
Get an organization public key
Gets your public key, which you need to encrypt secrets. You need to encrypt a secret before you can create or update secrets.
The authenticated user must have collaborator access to a repository to create, update, or read secrets.
OAuth tokens and personal access tokens (classic) need theadmin:org
scope to use this endpoint. If the repository is private, OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.getOrgPublicKey({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
See also: GitHub Developer Guide documentation.
Get an organization secret
Gets a single organization secret without revealing its encrypted value.
The authenticated user must have collaborator access to a repository to create, update, or read secrets
OAuth tokens and personal access tokens (classic) need theadmin:org
scope to use this endpoint. If the repository is private, OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.getOrgSecret({
org,
secret_name,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
secret_name | yes |
The name of the secret. |
See also: GitHub Developer Guide documentation.
Get an organization variable
Gets a specific variable in an organization.
The authenticated user must have collaborator access to a repository to create, update, or read variables.
OAuth tokens and personal access tokens (classic) need theadmin:org
scope to use this endpoint. If the repository is private, OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.getOrgVariable({
org,
name,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
name | yes |
The name of the variable. |
See also: GitHub Developer Guide documentation.
Get pending deployments for a workflow run
Get all deployment environments for a workflow run that are waiting for protection rules to pass.
Anyone with read access to the repository can use this endpoint.
If the repository is private, OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.getPendingDeploymentsForRun({
owner,
repo,
run_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
run_id | yes |
The unique identifier of the workflow run. |
See also: GitHub Developer Guide documentation.
Get GitHub Actions permissions for a repository
Deprecated: This method has been renamed to actions.getGithubActionsPermissionsRepository
Gets the GitHub Actions permissions policy for a repository, including whether GitHub Actions is enabled and the actions and reusable workflows allowed to run in the repository.
OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.getRepoPermissions({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Get a repository public key
Gets your public key, which you need to encrypt secrets. You need to encrypt a secret before you can create or update secrets.
Anyone with read access to the repository can use this endpoint.
If the repository is private, OAuth tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.getRepoPublicKey({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Get a repository secret
Gets a single repository secret without revealing its encrypted value.
The authenticated user must have collaborator access to the repository to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.getRepoSecret({
owner,
repo,
secret_name,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
secret_name | yes |
The name of the secret. |
See also: GitHub Developer Guide documentation.
Get a repository variable
Gets a specific variable in a repository.
The authenticated user must have collaborator access to the repository to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.getRepoVariable({
owner,
repo,
name,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
name | yes |
The name of the variable. |
See also: GitHub Developer Guide documentation.
Get the review history for a workflow run
Anyone with read access to the repository can use this endpoint.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint with a private repository.
octokit.rest.actions.getReviewsForRun({
owner,
repo,
run_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
run_id | yes |
The unique identifier of the workflow run. |
See also: GitHub Developer Guide documentation.
Get a self-hosted runner for an organization
Gets a specific self-hosted runner configured in an organization.
Authenticated users must have admin access to the organization to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint. If the repository is private, the repo
scope is also required.
octokit.rest.actions.getSelfHostedRunnerForOrg({
org,
runner_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
runner_id | yes |
Unique identifier of the self-hosted runner. |
See also: GitHub Developer Guide documentation.
Get a self-hosted runner for a repository
Gets a specific self-hosted runner configured in a repository.
Authenticated users must have admin access to the repository to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.getSelfHostedRunnerForRepo({
owner,
repo,
runner_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
runner_id | yes |
Unique identifier of the self-hosted runner. |
See also: GitHub Developer Guide documentation.
Get a workflow
Gets a specific workflow. You can replace workflow_id
with the workflow
file name. For example, you could use main.yaml
.
Anyone with read access to the repository can use this endpoint.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint with a private repository.
octokit.rest.actions.getWorkflow({
owner,
repo,
workflow_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
workflow_id | yes |
The ID of the workflow. You can also pass the workflow file name as a string. |
See also: GitHub Developer Guide documentation.
Get the level of access for workflows outside of the repository
Gets the level of access that workflows outside of the repository have to actions and reusable workflows in the repository. This endpoint only applies to private repositories. For more information, see "Allowing access to components in a private repository."
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.getWorkflowAccessToRepository({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Get a workflow run
Gets a specific workflow run.
Anyone with read access to the repository can use this endpoint.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint with a private repository.
octokit.rest.actions.getWorkflowRun({
owner,
repo,
run_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
run_id | yes |
The unique identifier of the workflow run. |
exclude_pull_requests | no |
If |
See also: GitHub Developer Guide documentation.
Get a workflow run attempt
Gets a specific workflow run attempt.
Anyone with read access to the repository can use this endpoint.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint with a private repository.
octokit.rest.actions.getWorkflowRunAttempt({
owner,
repo,
run_id,
attempt_number,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
run_id | yes |
The unique identifier of the workflow run. |
attempt_number | yes |
The attempt number of the workflow run. |
exclude_pull_requests | no |
If |
See also: GitHub Developer Guide documentation.
Get workflow run usage
Gets the number of billable minutes and total run time for a specific workflow run. Billable minutes only apply to workflows in private repositories that use GitHub-hosted runners. Usage is listed for each GitHub-hosted runner operating system in milliseconds. Any job re-runs are also included in the usage. The usage does not include the multiplier for macOS and Windows runners and is not rounded up to the nearest whole minute. For more information, see "Managing billing for GitHub Actions".
Anyone with read access to the repository can use this endpoint.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint with a private repository.
octokit.rest.actions.getWorkflowRunUsage({
owner,
repo,
run_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
run_id | yes |
The unique identifier of the workflow run. |
See also: GitHub Developer Guide documentation.
Get workflow usage
Gets the number of billable minutes used by a specific workflow during the current billing cycle. Billable minutes only apply to workflows in private repositories that use GitHub-hosted runners. Usage is listed for each GitHub-hosted runner operating system in milliseconds. Any job re-runs are also included in the usage. The usage does not include the multiplier for macOS and Windows runners and is not rounded up to the nearest whole minute. For more information, see "Managing billing for GitHub Actions".
You can replace workflow_id
with the workflow file name. For example, you could use main.yaml
.
Anyone with read access to the repository can use this endpoint.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint with a private repository.
octokit.rest.actions.getWorkflowUsage({
owner,
repo,
workflow_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
workflow_id | yes |
The ID of the workflow. You can also pass the workflow file name as a string. |
See also: GitHub Developer Guide documentation.
List artifacts for a repository
Lists all artifacts for a repository.
Anyone with read access to the repository can use this endpoint.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint with a private repository.
octokit.rest.actions.listArtifactsForRepo({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
name | no |
The name field of an artifact. When specified, only artifacts with this name will be returned. |
See also: GitHub Developer Guide documentation.
List environment secrets
Lists all secrets available in an environment without revealing their encrypted values.
Authenticated users must have collaborator access to a repository to create, update, or read secrets.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.listEnvironmentSecrets({
owner,
repo,
environment_name,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
environment_name | yes |
The name of the environment. The name must be URL encoded. For example, any slashes in the name must be replaced with |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List environment variables
Lists all environment variables.
Authenticated users must have collaborator access to a repository to create, update, or read variables.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.listEnvironmentVariables({
owner,
repo,
environment_name,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
environment_name | yes |
The name of the environment. The name must be URL encoded. For example, any slashes in the name must be replaced with |
per_page | no |
The number of results per page (max 30). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List jobs for a workflow run
Lists jobs for a workflow run. You can use parameters to narrow the list of results. For more information about using parameters, see Parameters.
Anyone with read access to the repository can use this endpoint.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint with a private repository.
octokit.rest.actions.listJobsForWorkflowRun({
owner,
repo,
run_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
run_id | yes |
The unique identifier of the workflow run. |
filter | no |
Filters jobs by their |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List jobs for a workflow run attempt
Lists jobs for a specific workflow run attempt. You can use parameters to narrow the list of results. For more information about using parameters, see Parameters.
Anyone with read access to the repository can use this endpoint.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint with a private repository.
octokit.rest.actions.listJobsForWorkflowRunAttempt({
owner,
repo,
run_id,
attempt_number,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
run_id | yes |
The unique identifier of the workflow run. |
attempt_number | yes |
The attempt number of the workflow run. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List labels for a self-hosted runner for an organization
Lists all labels for a self-hosted runner configured in an organization.
Authenticated users must have admin access to the organization to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint. If the repository is private, the repo
scope is also required.
octokit.rest.actions.listLabelsForSelfHostedRunnerForOrg({
org,
runner_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
runner_id | yes |
Unique identifier of the self-hosted runner. |
See also: GitHub Developer Guide documentation.
List labels for a self-hosted runner for a repository
Lists all labels for a self-hosted runner configured in a repository.
Authenticated users must have admin access to the repository to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.listLabelsForSelfHostedRunnerForRepo({
owner,
repo,
runner_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
runner_id | yes |
Unique identifier of the self-hosted runner. |
See also: GitHub Developer Guide documentation.
List organization secrets
Lists all secrets available in an organization without revealing their encrypted values.
Authenticated users must have collaborator access to a repository to create, update, or read secrets.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint. If the repository is private, the repo
scope is also required.
octokit.rest.actions.listOrgSecrets({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List organization variables
Lists all organization variables.
Authenticated users must have collaborator access to a repository to create, update, or read variables.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint. If the repository is private, the repo
scope is also required.
octokit.rest.actions.listOrgVariables({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
per_page | no |
The number of results per page (max 30). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List repository organization secrets
Lists all organization secrets shared with a repository without revealing their encrypted values.
Authenticated users must have collaborator access to a repository to create, update, or read secrets.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.listRepoOrganizationSecrets({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List repository organization variables
Lists all organization variables shared with a repository.
Authenticated users must have collaborator access to a repository to create, update, or read variables.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.listRepoOrganizationVariables({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
per_page | no |
The number of results per page (max 30). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List repository secrets
Lists all secrets available in a repository without revealing their encrypted values.
Authenticated users must have collaborator access to a repository to create, update, or read secrets.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.listRepoSecrets({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List repository variables
Lists all repository variables.
Authenticated users must have collaborator access to a repository to create, update, or read variables.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.listRepoVariables({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
per_page | no |
The number of results per page (max 30). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List repository workflows
Lists the workflows in a repository.
Anyone with read access to the repository can use this endpoint.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint with a private repository.
octokit.rest.actions.listRepoWorkflows({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List runner applications for an organization
Lists binaries for the runner application that you can download and run.
Authenticated users must have admin access to the organization to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint. If the repository is private, the repo
scope is also required.
octokit.rest.actions.listRunnerApplicationsForOrg({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
See also: GitHub Developer Guide documentation.
List runner applications for a repository
Lists binaries for the runner application that you can download and run.
Authenticated users must have admin access to the repository to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.listRunnerApplicationsForRepo({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
List selected repositories for an organization secret
Lists all repositories that have been selected when the visibility
for repository access to a secret is set to selected
.
Authenticated users must have collaborator access to a repository to create, update, or read secrets.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint. If the repository is private, the repo
scope is also required.
octokit.rest.actions.listSelectedReposForOrgSecret({
org,
secret_name,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
secret_name | yes |
The name of the secret. |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List selected repositories for an organization variable
Lists all repositories that can access an organization variable that is available to selected repositories.
Authenticated users must have collaborator access to a repository to create, update, or read variables.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint. If the repository is private, the repo
scope is also required.
octokit.rest.actions.listSelectedReposForOrgVariable({
org,
name,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
name | yes |
The name of the variable. |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List selected repositories enabled for GitHub Actions in an organization
Lists the selected repositories that are enabled for GitHub Actions in an organization. To use this endpoint, the organization permission policy for enabled_repositories
must be configured to selected
. For more information, see "Set GitHub Actions permissions for an organization."
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.actions.listSelectedRepositoriesEnabledGithubActionsOrganization({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List self-hosted runners for an organization
Lists all self-hosted runners configured in an organization.
Authenticated users must have admin access to the organization to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint. If the repository is private, the repo
scope is also required.
octokit.rest.actions.listSelfHostedRunnersForOrg({
org,
});
Parameters
name | required | description |
---|---|---|
name | no |
The name of a self-hosted runner. |
org | yes |
The organization name. The name is not case sensitive. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List self-hosted runners for a repository
Lists all self-hosted runners configured in a repository.
Authenticated users must have admin access to the repository to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.listSelfHostedRunnersForRepo({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
name | no |
The name of a self-hosted runner. |
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List workflow run artifacts
Lists artifacts for a workflow run.
Anyone with read access to the repository can use this endpoint.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint with a private repository.
octokit.rest.actions.listWorkflowRunArtifacts({
owner,
repo,
run_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
run_id | yes |
The unique identifier of the workflow run. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
name | no |
The name field of an artifact. When specified, only artifacts with this name will be returned. |
See also: GitHub Developer Guide documentation.
List workflow runs for a workflow
List all workflow runs for a workflow. You can replace workflow_id
with the workflow file name. For example, you could use main.yaml
. You can use parameters to narrow the list of results. For more information about using parameters, see Parameters.
Anyone with read access to the repository can use this endpoint
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint with a private repository.
octokit.rest.actions.listWorkflowRuns({
owner,
repo,
workflow_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
workflow_id | yes |
The ID of the workflow. You can also pass the workflow file name as a string. |
actor | no |
Returns someone's workflow runs. Use the login for the user who created the |
branch | no |
Returns workflow runs associated with a branch. Use the name of the branch of the |
event | no |
Returns workflow run triggered by the event you specify. For example, |
status | no |
Returns workflow runs with the check run |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
created | no |
Returns workflow runs created within the given date-time range. For more information on the syntax, see "Understanding the search syntax." |
exclude_pull_requests | no |
If |
check_suite_id | no |
Returns workflow runs with the |
head_sha | no |
Only returns workflow runs that are associated with the specified |
See also: GitHub Developer Guide documentation.
List workflow runs for a repository
Lists all workflow runs for a repository. You can use parameters to narrow the list of results. For more information about using parameters, see Parameters.
Anyone with read access to the repository can use this endpoint.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint with a private repository.
This API will return up to 1,000 results for each search when using the following parameters: actor
, branch
, check_suite_id
, created
, event
, head_sha
, status
.
octokit.rest.actions.listWorkflowRunsForRepo({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
actor | no |
Returns someone's workflow runs. Use the login for the user who created the |
branch | no |
Returns workflow runs associated with a branch. Use the name of the branch of the |
event | no |
Returns workflow run triggered by the event you specify. For example, |
status | no |
Returns workflow runs with the check run |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
created | no |
Returns workflow runs created within the given date-time range. For more information on the syntax, see "Understanding the search syntax." |
exclude_pull_requests | no |
If |
check_suite_id | no |
Returns workflow runs with the |
head_sha | no |
Only returns workflow runs that are associated with the specified |
See also: GitHub Developer Guide documentation.
Re-run a job from a workflow run
Re-run a job and its dependent jobs in a workflow run.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.reRunJobForWorkflowRun({
owner,
repo,
job_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
job_id | yes |
The unique identifier of the job. |
enable_debug_logging | no |
Whether to enable debug logging for the re-run. |
See also: GitHub Developer Guide documentation.
Re-run a workflow
Re-runs your workflow run using its id
.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.reRunWorkflow({
owner,
repo,
run_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
run_id | yes |
The unique identifier of the workflow run. |
enable_debug_logging | no |
Whether to enable debug logging for the re-run. |
See also: GitHub Developer Guide documentation.
Re-run failed jobs from a workflow run
Re-run all of the failed jobs and their dependent jobs in a workflow run using the id
of the workflow run.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.reRunWorkflowFailedJobs({
owner,
repo,
run_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
run_id | yes |
The unique identifier of the workflow run. |
enable_debug_logging | no |
Whether to enable debug logging for the re-run. |
See also: GitHub Developer Guide documentation.
Remove all custom labels from a self-hosted runner for an organization
Remove all custom labels from a self-hosted runner configured in an organization. Returns the remaining read-only labels from the runner.
Authenticated users must have admin access to the organization to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint. If the repository is private, the repo
scope is also required.
octokit.rest.actions.removeAllCustomLabelsFromSelfHostedRunnerForOrg({
org,
runner_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
runner_id | yes |
Unique identifier of the self-hosted runner. |
See also: GitHub Developer Guide documentation.
Remove all custom labels from a self-hosted runner for a repository
Remove all custom labels from a self-hosted runner configured in a repository. Returns the remaining read-only labels from the runner.
Authenticated users must have admin access to the repository to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.removeAllCustomLabelsFromSelfHostedRunnerForRepo({
owner,
repo,
runner_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
runner_id | yes |
Unique identifier of the self-hosted runner. |
See also: GitHub Developer Guide documentation.
Remove a custom label from a self-hosted runner for an organization
Remove a custom label from a self-hosted runner configured in an organization. Returns the remaining labels from the runner.
This endpoint returns a 404 Not Found
status if the custom label is not
present on the runner.
Authenticated users must have admin access to the organization to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint. If the repository is private, the repo
scope is also required.
octokit.rest.actions.removeCustomLabelFromSelfHostedRunnerForOrg({
org,
runner_id,
name,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
runner_id | yes |
Unique identifier of the self-hosted runner. |
name | yes |
The name of a self-hosted runner's custom label. |
See also: GitHub Developer Guide documentation.
Remove a custom label from a self-hosted runner for a repository
Remove a custom label from a self-hosted runner configured in a repository. Returns the remaining labels from the runner.
This endpoint returns a 404 Not Found
status if the custom label is not
present on the runner.
Authenticated users must have admin access to the repository to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.removeCustomLabelFromSelfHostedRunnerForRepo({
owner,
repo,
runner_id,
name,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
runner_id | yes |
Unique identifier of the self-hosted runner. |
name | yes |
The name of a self-hosted runner's custom label. |
See also: GitHub Developer Guide documentation.
Remove selected repository from an organization secret
Removes a repository from an organization secret when the visibility
for repository access is set to selected
. The visibility is set when you Create
or update an organization secret.
Authenticated users must have collaborator access to a repository to create, update, or read secrets.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint. If the repository is private, the repo
scope is also required.
octokit.rest.actions.removeSelectedRepoFromOrgSecret({
org,
secret_name,
repository_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
secret_name | yes |
The name of the secret. |
repository_id | yes |
See also: GitHub Developer Guide documentation.
Remove selected repository from an organization variable
Removes a repository from an organization variable that is
available to selected repositories. Organization variables that are available to
selected repositories have their visibility
field set to selected
.
Authenticated users must have collaborator access to a repository to create, update, or read variables.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint. If the repository is private, the repo
scope is also required.
octokit.rest.actions.removeSelectedRepoFromOrgVariable({
org,
name,
repository_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
name | yes |
The name of the variable. |
repository_id | yes |
See also: GitHub Developer Guide documentation.
Review custom deployment protection rules for a workflow run
Approve or reject custom deployment protection rules provided by a GitHub App for a workflow run. For more information, see "Using environments for deployment."
Note: GitHub Apps can only review their own custom deployment protection rules.
To approve or reject pending deployments that are waiting for review from a specific person or team, see POST /repos/{owner}/{repo}/actions/runs/{run_id}/pending_deployments
.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint with a private repository.
octokit.rest.actions.reviewCustomGatesForRun({
owner,
repo,
run_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
run_id | yes |
The unique identifier of the workflow run. |
See also: GitHub Developer Guide documentation.
Review pending deployments for a workflow run
Approve or reject pending deployments that are waiting on approval by a required reviewer.
Required reviewers with read access to the repository contents and deployments can use this endpoint.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.reviewPendingDeploymentsForRun({
owner,
repo,
run_id,
environment_ids,
state,
comment,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
run_id | yes |
The unique identifier of the workflow run. |
environment_ids | yes |
The list of environment ids to approve or reject |
state | yes |
Whether to approve or reject deployment to the specified environments. |
comment | yes |
A comment to accompany the deployment review |
See also: GitHub Developer Guide documentation.
Set allowed actions and reusable workflows for an organization
Sets the actions and reusable workflows that are allowed in an organization. To use this endpoint, the organization permission policy for allowed_actions
must be configured to selected
. For more information, see "Set GitHub Actions permissions for an organization."
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.actions.setAllowedActionsOrganization({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
github_owned_allowed | no |
Whether GitHub-owned actions are allowed. For example, this includes the actions in the |
verified_allowed | no |
Whether actions from GitHub Marketplace verified creators are allowed. Set to |
patterns_allowed | no |
Specifies a list of string-matching patterns to allow specific action(s) and reusable workflow(s). Wildcards, tags, and SHAs are allowed. For example, Note: The |
See also: GitHub Developer Guide documentation.
Set allowed actions and reusable workflows for a repository
Sets the actions and reusable workflows that are allowed in a repository. To use this endpoint, the repository permission policy for allowed_actions
must be configured to selected
. For more information, see "Set GitHub Actions permissions for a repository."
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.setAllowedActionsRepository({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
github_owned_allowed | no |
Whether GitHub-owned actions are allowed. For example, this includes the actions in the |
verified_allowed | no |
Whether actions from GitHub Marketplace verified creators are allowed. Set to |
patterns_allowed | no |
Specifies a list of string-matching patterns to allow specific action(s) and reusable workflow(s). Wildcards, tags, and SHAs are allowed. For example, Note: The |
See also: GitHub Developer Guide documentation.
Set custom labels for a self-hosted runner for an organization
Remove all previous custom labels and set the new custom labels for a specific self-hosted runner configured in an organization.
Authenticated users must have admin access to the organization to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint. If the repository is private, the repo
scope is also required.
octokit.rest.actions.setCustomLabelsForSelfHostedRunnerForOrg({
org,
runner_id,
labels,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
runner_id | yes |
Unique identifier of the self-hosted runner. |
labels | yes |
The names of the custom labels to set for the runner. You can pass an empty array to remove all custom labels. |
See also: GitHub Developer Guide documentation.
Set custom labels for a self-hosted runner for a repository
Remove all previous custom labels and set the new custom labels for a specific self-hosted runner configured in a repository.
Authenticated users must have admin access to the repository to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.setCustomLabelsForSelfHostedRunnerForRepo({
owner,
repo,
runner_id,
labels,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
runner_id | yes |
Unique identifier of the self-hosted runner. |
labels | yes |
The names of the custom labels to set for the runner. You can pass an empty array to remove all custom labels. |
See also: GitHub Developer Guide documentation.
Set the customization template for an OIDC subject claim for a repository
Sets the customization template and opt-in
or opt-out
flag for an OpenID Connect (OIDC) subject claim for a repository.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.setCustomOidcSubClaimForRepo({
owner,
repo,
use_default,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
use_default | yes |
Whether to use the default template or not. If |
include_claim_keys | no |
Array of unique strings. Each claim key can only contain alphanumeric characters and underscores. |
See also: GitHub Developer Guide documentation.
Set default workflow permissions for an organization
Sets the default workflow permissions granted to the GITHUB_TOKEN
when running workflows in an organization, and sets if GitHub Actions
can submit approving pull request reviews. For more information, see
"Setting the permissions of the GITHUB_TOKEN for your organization."
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.actions.setGithubActionsDefaultWorkflowPermissionsOrganization({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
default_workflow_permissions | no |
The default workflow permissions granted to the GITHUB_TOKEN when running workflows. |
can_approve_pull_request_reviews | no |
Whether GitHub Actions can approve pull requests. Enabling this can be a security risk. |
See also: GitHub Developer Guide documentation.
Set default workflow permissions for a repository
Sets the default workflow permissions granted to the GITHUB_TOKEN
when running workflows in a repository, and sets if GitHub Actions
can submit approving pull request reviews.
For more information, see "Setting the permissions of the GITHUB_TOKEN for your repository."
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.setGithubActionsDefaultWorkflowPermissionsRepository({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
default_workflow_permissions | no |
The default workflow permissions granted to the GITHUB_TOKEN when running workflows. |
can_approve_pull_request_reviews | no |
Whether GitHub Actions can approve pull requests. Enabling this can be a security risk. |
See also: GitHub Developer Guide documentation.
Set GitHub Actions permissions for an organization
Sets the GitHub Actions permissions policy for repositories and allowed actions and reusable workflows in an organization.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.actions.setGithubActionsPermissionsOrganization({
org,
enabled_repositories,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
enabled_repositories | yes |
The policy that controls the repositories in the organization that are allowed to run GitHub Actions. |
allowed_actions | no |
The permissions policy that controls the actions and reusable workflows that are allowed to run. |
See also: GitHub Developer Guide documentation.
Set GitHub Actions permissions for a repository
Sets the GitHub Actions permissions policy for enabling GitHub Actions and allowed actions and reusable workflows in the repository.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.setGithubActionsPermissionsRepository({
owner,
repo,
enabled,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
enabled | yes |
Whether GitHub Actions is enabled on the repository. |
allowed_actions | no |
The permissions policy that controls the actions and reusable workflows that are allowed to run. |
See also: GitHub Developer Guide documentation.
Set selected repositories for an organization secret
Replaces all repositories for an organization secret when the visibility
for repository access is set to selected
. The visibility is set when you Create
or update an organization secret.
Authenticated users must have collaborator access to a repository to create, update, or read secrets.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint. If the repository is private, the repo
scope is also required.
octokit.rest.actions.setSelectedReposForOrgSecret({
org,
secret_name,
selected_repository_ids,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
secret_name | yes |
The name of the secret. |
selected_repository_ids | yes |
An array of repository ids that can access the organization secret. You can only provide a list of repository ids when the |
See also: GitHub Developer Guide documentation.
Set selected repositories for an organization variable
Replaces all repositories for an organization variable that is available
to selected repositories. Organization variables that are available to selected
repositories have their visibility
field set to selected
.
Authenticated users must have collaborator access to a repository to create, update, or read variables.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint. If the repository is private, the repo
scope is also required.
octokit.rest.actions.setSelectedReposForOrgVariable({
org,
name,
selected_repository_ids,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
name | yes |
The name of the variable. |
selected_repository_ids | yes |
The IDs of the repositories that can access the organization variable. |
See also: GitHub Developer Guide documentation.
Set selected repositories enabled for GitHub Actions in an organization
Replaces the list of selected repositories that are enabled for GitHub Actions in an organization. To use this endpoint, the organization permission policy for enabled_repositories
must be configured to selected
. For more information, see "Set GitHub Actions permissions for an organization."
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.actions.setSelectedRepositoriesEnabledGithubActionsOrganization({
org,
selected_repository_ids,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
selected_repository_ids | yes |
List of repository IDs to enable for GitHub Actions. |
See also: GitHub Developer Guide documentation.
Set the level of access for workflows outside of the repository
Sets the level of access that workflows outside of the repository have to actions and reusable workflows in the repository. This endpoint only applies to private repositories. For more information, see "Allowing access to components in a private repository".
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.setWorkflowAccessToRepository({
owner,
repo,
access_level,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
access_level | yes |
Defines the level of access that workflows outside of the repository have to actions and reusable workflows within the repository.
|
See also: GitHub Developer Guide documentation.
Update an environment variable
Updates an environment variable that you can reference in a GitHub Actions workflow.
Authenticated users must have collaborator access to a repository to create, update, or read variables.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.updateEnvironmentVariable({
owner,
repo,
environment_name,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
name | no |
The name of the variable. |
environment_name | yes |
The name of the environment. The name must be URL encoded. For example, any slashes in the name must be replaced with |
value | no |
The value of the variable. |
See also: GitHub Developer Guide documentation.
Update an organization variable
Updates an organization variable that you can reference in a GitHub Actions workflow.
Authenticated users must have collaborator access to a repository to create, update, or read variables.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint. If the repository is private, the repo
scope is also required.
octokit.rest.actions.updateOrgVariable({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
name | no |
The name of the variable. |
value | no |
The value of the variable. |
visibility | no |
The type of repositories in the organization that can access the variable. |
selected_repository_ids | no |
An array of repository ids that can access the organization variable. You can only provide a list of repository ids when the |
See also: GitHub Developer Guide documentation.
Update a repository variable
Updates a repository variable that you can reference in a GitHub Actions workflow.
Authenticated users must have collaborator access to a repository to create, update, or read variables.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.actions.updateRepoVariable({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
name | no |
The name of the variable. |
value | no |
The value of the variable. |
See also: GitHub Developer Guide documentation.
Activity
Check if a repository is starred by the authenticated user
Whether the authenticated user has starred the repository.
octokit.rest.activity.checkRepoIsStarredByAuthenticatedUser({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Delete a repository subscription
This endpoint should only be used to stop watching a repository. To control whether or not you wish to receive notifications from a repository, set the repository's subscription manually.
octokit.rest.activity.deleteRepoSubscription({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Delete a thread subscription
Mutes all future notifications for a conversation until you comment on the thread or get an @mention. If you are watching the repository of the thread, you will still receive notifications. To ignore future notifications for a repository you are watching, use the Set a thread subscription endpoint and set ignore
to true
.
octokit.rest.activity.deleteThreadSubscription({
thread_id,
});
Parameters
name | required | description |
---|---|---|
thread_id | yes |
The unique identifier of the notification thread. This corresponds to the value returned in the |
See also: GitHub Developer Guide documentation.
Get feeds
Lists the feeds available to the authenticated user. The response provides a URL for each feed. You can then get a specific feed by sending a request to one of the feed URLs.
- Timeline: The GitHub global public timeline
- User: The public timeline for any user, using
uri_template
. For more information, see "Hypermedia." - Current user public: The public timeline for the authenticated user
- Current user: The private timeline for the authenticated user
- Current user actor: The private timeline for activity created by the authenticated user
- Current user organizations: The private timeline for the organizations the authenticated user is a member of.
- Security advisories: A collection of public announcements that provide information about security-related vulnerabilities in software on GitHub.
By default, timeline resources are returned in JSON. You can specify the application/atom+xml
type in the Accept
header to return timeline resources in Atom format. For more information, see "Media types."
Note: Private feeds are only returned when authenticating via Basic Auth since current feed URIs use the older, non revocable auth tokens.
octokit.rest.activity.getFeeds();
Parameters
This endpoint has no parameters
See also: GitHub Developer Guide documentation.
Get a repository subscription
Gets information about whether the authenticated user is subscribed to the repository.
octokit.rest.activity.getRepoSubscription({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Get a thread
Gets information about a notification thread.
octokit.rest.activity.getThread({
thread_id,
});
Parameters
name | required | description |
---|---|---|
thread_id | yes |
The unique identifier of the notification thread. This corresponds to the value returned in the |
See also: GitHub Developer Guide documentation.
Get a thread subscription for the authenticated user
This checks to see if the current user is subscribed to a thread. You can also get a repository subscription.
Note that subscriptions are only generated if a user is participating in a conversation--for example, they've replied to the thread, were @mentioned, or manually subscribe to a thread.
octokit.rest.activity.getThreadSubscriptionForAuthenticatedUser({
thread_id,
});
Parameters
name | required | description |
---|---|---|
thread_id | yes |
The unique identifier of the notification thread. This corresponds to the value returned in the |
See also: GitHub Developer Guide documentation.
List events for the authenticated user
If you are authenticated as the given user, you will see your private events. Otherwise, you'll only see public events.
octokit.rest.activity.listEventsForAuthenticatedUser({
username,
});
Parameters
name | required | description |
---|---|---|
username | yes |
The handle for the GitHub user account. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List notifications for the authenticated user
List all notifications for the current user, sorted by most recently updated.
octokit.rest.activity.listNotificationsForAuthenticatedUser();
Parameters
name | required | description |
---|---|---|
all | no |
If |
participating | no |
If |
since | no |
Only show results that were last updated after the given time. This is a timestamp in ISO 8601 format: |
before | no |
Only show notifications updated before the given time. This is a timestamp in ISO 8601 format: |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
per_page | no |
The number of results per page (max 50). For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List organization events for the authenticated user
This is the user's organization dashboard. You must be authenticated as the user to view this.
octokit.rest.activity.listOrgEventsForAuthenticatedUser({
username,
org,
});
Parameters
name | required | description |
---|---|---|
username | yes |
The handle for the GitHub user account. |
org | yes |
The organization name. The name is not case sensitive. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List public events
We delay the public events feed by five minutes, which means the most recent event returned by the public events API actually occurred at least five minutes ago.
octokit.rest.activity.listPublicEvents();
Parameters
name | required | description |
---|---|---|
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List public events for a network of repositories
octokit.rest.activity.listPublicEventsForRepoNetwork({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List public events for a user
octokit.rest.activity.listPublicEventsForUser({
username,
});
Parameters
name | required | description |
---|---|---|
username | yes |
The handle for the GitHub user account. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List public organization events
octokit.rest.activity.listPublicOrgEvents({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List events received by the authenticated user
These are events that you've received by watching repositories and following users. If you are authenticated as the given user, you will see private events. Otherwise, you'll only see public events.
octokit.rest.activity.listReceivedEventsForUser({
username,
});
Parameters
name | required | description |
---|---|---|
username | yes |
The handle for the GitHub user account. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List public events received by a user
octokit.rest.activity.listReceivedPublicEventsForUser({
username,
});
Parameters
name | required | description |
---|---|---|
username | yes |
The handle for the GitHub user account. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List repository events
Note: This API is not built to serve real-time use cases. Depending on the time of day, event latency can be anywhere from 30s to 6h.
octokit.rest.activity.listRepoEvents({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List repository notifications for the authenticated user
Lists all notifications for the current user in the specified repository.
octokit.rest.activity.listRepoNotificationsForAuthenticatedUser({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
all | no |
If |
participating | no |
If |
since | no |
Only show results that were last updated after the given time. This is a timestamp in ISO 8601 format: |
before | no |
Only show notifications updated before the given time. This is a timestamp in ISO 8601 format: |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List repositories starred by the authenticated user
Lists repositories the authenticated user has starred.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github.star+json
: Includes a timestamp of when the star was created.
octokit.rest.activity.listReposStarredByAuthenticatedUser();
Parameters
name | required | description |
---|---|---|
sort | no |
The property to sort the results by. |
direction | no |
The direction to sort the results by. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List repositories starred by a user
Lists repositories a user has starred.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github.star+json
: Includes a timestamp of when the star was created.
octokit.rest.activity.listReposStarredByUser({
username,
});
Parameters
name | required | description |
---|---|---|
username | yes |
The handle for the GitHub user account. |
sort | no |
The property to sort the results by. |
direction | no |
The direction to sort the results by. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List repositories watched by a user
Lists repositories a user is watching.
octokit.rest.activity.listReposWatchedByUser({
username,
});
Parameters
name | required | description |
---|---|---|
username | yes |
The handle for the GitHub user account. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List stargazers
Lists the people that have starred the repository.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github.star+json
: Includes a timestamp of when the star was created.
octokit.rest.activity.listStargazersForRepo({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List repositories watched by the authenticated user
Lists repositories the authenticated user is watching.
octokit.rest.activity.listWatchedReposForAuthenticatedUser();
Parameters
name | required | description |
---|---|---|
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List watchers
Lists the people watching the specified repository.
octokit.rest.activity.listWatchersForRepo({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
Mark notifications as read
Marks all notifications as "read" for the current user. If the number of notifications is too large to complete in one request, you will receive a 202 Accepted
status and GitHub will run an asynchronous process to mark notifications as "read." To check whether any "unread" notifications remain, you can use the List notifications for the authenticated user endpoint and pass the query parameter all=false
.
octokit.rest.activity.markNotificationsAsRead();
Parameters
name | required | description |
---|---|---|
last_read_at | no |
Describes the last point that notifications were checked. Anything updated since this time will not be marked as read. If you omit this parameter, all notifications are marked as read. This is a timestamp in ISO 8601 format: |
read | no |
Whether the notification has been read. |
See also: GitHub Developer Guide documentation.
Mark repository notifications as read
Marks all notifications in a repository as "read" for the current user. If the number of notifications is too large to complete in one request, you will receive a 202 Accepted
status and GitHub will run an asynchronous process to mark notifications as "read." To check whether any "unread" notifications remain, you can use the List repository notifications for the authenticated user endpoint and pass the query parameter all=false
.
octokit.rest.activity.markRepoNotificationsAsRead({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
last_read_at | no |
Describes the last point that notifications were checked. Anything updated since this time will not be marked as read. If you omit this parameter, all notifications are marked as read. This is a timestamp in ISO 8601 format: |
See also: GitHub Developer Guide documentation.
Mark a thread as done
Marks a thread as "done." Marking a thread as "done" is equivalent to marking a notification in your notification inbox on GitHub as done: https://github.com/notifications.
octokit.rest.activity.markThreadAsDone({
thread_id,
});
Parameters
name | required | description |
---|---|---|
thread_id | yes |
The unique identifier of the notification thread. This corresponds to the value returned in the |
See also: GitHub Developer Guide documentation.
Mark a thread as read
Marks a thread as "read." Marking a thread as "read" is equivalent to clicking a notification in your notification inbox on GitHub: https://github.com/notifications.
octokit.rest.activity.markThreadAsRead({
thread_id,
});
Parameters
name | required | description |
---|---|---|
thread_id | yes |
The unique identifier of the notification thread. This corresponds to the value returned in the |
See also: GitHub Developer Guide documentation.
Set a repository subscription
If you would like to watch a repository, set subscribed
to true
. If you would like to ignore notifications made within a repository, set ignored
to true
. If you would like to stop watching a repository, delete the repository's subscription completely.
octokit.rest.activity.setRepoSubscription({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
subscribed | no |
Determines if notifications should be received from this repository. |
ignored | no |
Determines if all notifications should be blocked from this repository. |
See also: GitHub Developer Guide documentation.
Set a thread subscription
If you are watching a repository, you receive notifications for all threads by default. Use this endpoint to ignore future notifications for threads until you comment on the thread or get an @mention.
You can also use this endpoint to subscribe to threads that you are currently not receiving notifications for or to subscribed to threads that you have previously ignored.
Unsubscribing from a conversation in a repository that you are not watching is functionally equivalent to the Delete a thread subscription endpoint.
octokit.rest.activity.setThreadSubscription({
thread_id,
});
Parameters
name | required | description |
---|---|---|
thread_id | yes |
The unique identifier of the notification thread. This corresponds to the value returned in the |
ignored | no |
Whether to block all notifications from a thread. |
See also: GitHub Developer Guide documentation.
Star a repository for the authenticated user
Note that you'll need to set Content-Length
to zero when calling out to this endpoint. For more information, see "HTTP method."
octokit.rest.activity.starRepoForAuthenticatedUser({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Unstar a repository for the authenticated user
Unstar a repository that the authenticated user has previously starred.
octokit.rest.activity.unstarRepoForAuthenticatedUser({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Apps
Add a repository to an app installation
Deprecated: This method has been renamed to apps.addRepoToInstallationForAuthenticatedUser
Add a single repository to an installation. The authenticated user must have admin access to the repository.
octokit.rest.apps.addRepoToInstallation({
installation_id,
repository_id,
});
Parameters
name | required | description |
---|---|---|
installation_id | yes |
The unique identifier of the installation. |
repository_id | yes |
The unique identifier of the repository. |
See also: GitHub Developer Guide documentation.
Add a repository to an app installation
Add a single repository to an installation. The authenticated user must have admin access to the repository.
octokit.rest.apps.addRepoToInstallationForAuthenticatedUser({
installation_id,
repository_id,
});
Parameters
name | required | description |
---|---|---|
installation_id | yes |
The unique identifier of the installation. |
repository_id | yes |
The unique identifier of the repository. |
See also: GitHub Developer Guide documentation.
Check a token
OAuth applications and GitHub applications with OAuth authorizations can use this API method for checking OAuth token validity without exceeding the normal rate limits for failed login attempts. Authentication works differently with this particular endpoint. You must use Basic Authentication to use this endpoint, where the username is the application client_id
and the password is its client_secret
. Invalid tokens will return 404 NOT FOUND
.
octokit.rest.apps.checkToken({
client_id,
access_token,
});
Parameters
name | required | description |
---|---|---|
client_id | yes |
The client ID of the GitHub app. |
access_token | yes |
The access_token of the OAuth or GitHub application. |
See also: GitHub Developer Guide documentation.
Create a GitHub App from a manifest
Use this endpoint to complete the handshake necessary when implementing the GitHub App Manifest flow. When you create a GitHub App with the manifest flow, you receive a temporary code
used to retrieve the GitHub App's id
, pem
(private key), and webhook_secret
.
octokit.rest.apps.createFromManifest({
code,
});
Parameters
name | required | description |
---|---|---|
code | yes |
See also: GitHub Developer Guide documentation.
Create an installation access token for an app
Creates an installation access token that enables a GitHub App to make authenticated API requests for the app's installation on an organization or individual account. Installation tokens expire one hour from the time you create them. Using an expired token produces a status code of 401 - Unauthorized
, and requires creating a new installation token. By default the installation token has access to all repositories that the installation can access.
Optionally, you can use the repositories
or repository_ids
body parameters to specify individual repositories that the installation access token can access. If you don't use repositories
or repository_ids
to grant access to specific repositories, the installation access token will have access to all repositories that the installation was granted access to. The installation access token cannot be granted access to repositories that the installation was not granted access to. Up to 500 repositories can be listed in this manner.
Optionally, use the permissions
body parameter to specify the permissions that the installation access token should have. If permissions
is not specified, the installation access token will have all of the permissions that were granted to the app. The installation access token cannot be granted permissions that the app was not granted.
When using the repository or permission parameters to reduce the access of the token, the complexity of the token is increased due to both the number of permissions in the request and the number of repositories the token will have access to. If the complexity is too large, the token will fail to be issued. If this occurs, the error message will indicate the maximum number of repositories that should be requested. For the average application requesting 8 permissions, this limit is around 5000 repositories. With fewer permissions requested, more repositories are supported.
You must use a JWT to access this endpoint.
octokit.rest.apps.createInstallationAccessToken({
installation_id,
});
Parameters
name | required | description |
---|---|---|
installation_id | yes |
The unique identifier of the installation. |
repositories | no |
List of repository names that the token should have access to |
repository_ids | no |
List of repository IDs that the token should have access to |
permissions | no |
The permissions granted to the user access token. |
permissions.actions | no |
The level of permission to grant the access token for GitHub Actions workflows, workflow runs, and artifacts. |
permissions.administration | no |
The level of permission to grant the access token for repository creation, deletion, settings, teams, and collaborators creation. |
permissions.checks | no |
The level of permission to grant the access token for checks on code. |
permissions.codespaces | no |
The level of permission to grant the access token to create, edit, delete, and list Codespaces. |
permissions.contents | no |
The level of permission to grant the access token for repository contents, commits, branches, downloads, releases, and merges. |
permissions.dependabot_secrets | no |
The leve of permission to grant the access token to manage Dependabot secrets. |
permissions.deployments | no |
The level of permission to grant the access token for deployments and deployment statuses. |
permissions.environments | no |
The level of permission to grant the access token for managing repository environments. |
permissions.issues | no |
The level of permission to grant the access token for issues and related comments, assignees, labels, and milestones. |
permissions.metadata | no |
The level of permission to grant the access token to search repositories, list collaborators, and access repository metadata. |
permissions.packages | no |
The level of permission to grant the access token for packages published to GitHub Packages. |
permissions.pages | no |
The level of permission to grant the access token to retrieve Pages statuses, configuration, and builds, as well as create new builds. |
permissions.pull_requests | no |
The level of permission to grant the access token for pull requests and related comments, assignees, labels, milestones, and merges. |
permissions.repository_custom_properties | no |
The level of permission to grant the access token to view and edit custom properties for a repository, when allowed by the property. |
permissions.repository_hooks | no |
The level of permission to grant the access token to manage the post-receive hooks for a repository. |
permissions.repository_projects | no |
The level of permission to grant the access token to manage repository projects, columns, and cards. |
permissions.secret_scanning_alerts | no |
The level of permission to grant the access token to view and manage secret scanning alerts. |
permissions.secrets | no |
The level of permission to grant the access token to manage repository secrets. |
permissions.security_events | no |
The level of permission to grant the access token to view and manage security events like code scanning alerts. |
permissions.single_file | no |
The level of permission to grant the access token to manage just a single file. |
permissions.statuses | no |
The level of permission to grant the access token for commit statuses. |
permissions.vulnerability_alerts | no |
The level of permission to grant the access token to manage Dependabot alerts. |
permissions.workflows | no |
The level of permission to grant the access token to update GitHub Actions workflow files. |
permissions.members | no |
The level of permission to grant the access token for organization teams and members. |
permissions.organization_administration | no |
The level of permission to grant the access token to manage access to an organization. |
permissions.organization_custom_roles | no |
The level of permission to grant the access token for custom repository roles management. |
permissions.organization_custom_org_roles | no |
The level of permission to grant the access token for custom organization roles management. |
permissions.organization_custom_properties | no |
The level of permission to grant the access token for custom property management. |
permissions.organization_copilot_seat_management | no |
The level of permission to grant the access token for managing access to GitHub Copilot for members of an organization with a Copilot Business subscription. This property is in beta and is subject to change. |
permissions.organization_announcement_banners | no |
The level of permission to grant the access token to view and manage announcement banners for an organization. |
permissions.organization_events | no |
The level of permission to grant the access token to view events triggered by an activity in an organization. |
permissions.organization_hooks | no |
The level of permission to grant the access token to manage the post-receive hooks for an organization. |
permissions.organization_personal_access_tokens | no |
The level of permission to grant the access token for viewing and managing fine-grained personal access token requests to an organization. |
permissions.organization_personal_access_token_requests | no |
The level of permission to grant the access token for viewing and managing fine-grained personal access tokens that have been approved by an organization. |
permissions.organization_plan | no |
The level of permission to grant the access token for viewing an organization's plan. |
permissions.organization_projects | no |
The level of permission to grant the access token to manage organization projects and projects beta (where available). |
permissions.organization_packages | no |
The level of permission to grant the access token for organization packages published to GitHub Packages. |
permissions.organization_secrets | no |
The level of permission to grant the access token to manage organization secrets. |
permissions.organization_self_hosted_runners | no |
The level of permission to grant the access token to view and manage GitHub Actions self-hosted runners available to an organization. |
permissions.organization_user_blocking | no |
The level of permission to grant the access token to view and manage users blocked by the organization. |
permissions.team_discussions | no |
The level of permission to grant the access token to manage team discussions and related comments. |
permissions.email_addresses | no |
The level of permission to grant the access token to manage the email addresses belonging to a user. |
permissions.followers | no |
The level of permission to grant the access token to manage the followers belonging to a user. |
permissions.git_ssh_keys | no |
The level of permission to grant the access token to manage git SSH keys. |
permissions.gpg_keys | no |
The level of permission to grant the access token to view and manage GPG keys belonging to a user. |
permissions.interaction_limits | no |
The level of permission to grant the access token to view and manage interaction limits on a repository. |
permissions.profile | no |
The level of permission to grant the access token to manage the profile settings belonging to a user. |
permissions.starring | no |
The level of permission to grant the access token to list and manage repositories a user is starring. |
See also: GitHub Developer Guide documentation.
Delete an app authorization
OAuth and GitHub application owners can revoke a grant for their application and a specific user. You must use Basic Authentication when accessing this endpoint, using the OAuth application's client_id
and client_secret
as the username and password. You must also provide a valid OAuth access_token
as an input parameter and the grant for the token's owner will be deleted.
Deleting an application's grant will also delete all OAuth tokens associated with the application for the user. Once deleted, the application will have no access to the user's account and will no longer be listed on the application authorizations settings screen within GitHub.
octokit.rest.apps.deleteAuthorization({
client_id,
access_token,
});
Parameters
name | required | description |
---|---|---|
client_id | yes |
The client ID of the GitHub app. |
access_token | yes |
The OAuth access token used to authenticate to the GitHub API. |
See also: GitHub Developer Guide documentation.
Delete an installation for the authenticated app
Uninstalls a GitHub App on a user, organization, or business account. If you prefer to temporarily suspend an app's access to your account's resources, then we recommend the "Suspend an app installation" endpoint.
You must use a JWT to access this endpoint.
octokit.rest.apps.deleteInstallation({
installation_id,
});
Parameters
name | required | description |
---|---|---|
installation_id | yes |
The unique identifier of the installation. |
See also: GitHub Developer Guide documentation.
Delete an app token
OAuth or GitHub application owners can revoke a single token for an OAuth application or a GitHub application with an OAuth authorization. You must use Basic Authentication when accessing this endpoint, using the application's client_id
and client_secret
as the username and password.
octokit.rest.apps.deleteToken({
client_id,
access_token,
});
Parameters
name | required | description |
---|---|---|
client_id | yes |
The client ID of the GitHub app. |
access_token | yes |
The OAuth access token used to authenticate to the GitHub API. |
See also: GitHub Developer Guide documentation.
Get the authenticated app
Returns the GitHub App associated with the authentication credentials used. To see how many app installations are associated with this GitHub App, see the installations_count
in the response. For more details about your app's installations, see the "List installations for the authenticated app" endpoint.
You must use a JWT to access this endpoint.
octokit.rest.apps.getAuthenticated();
Parameters
This endpoint has no parameters
See also: GitHub Developer Guide documentation.
Get an app
Note: The :app_slug
is just the URL-friendly name of your GitHub App. You can find this on the settings page for your GitHub App (e.g., https://github.com/settings/apps/:app_slug
).
octokit.rest.apps.getBySlug({
app_slug,
});
Parameters
name | required | description |
---|---|---|
app_slug | yes |
See also: GitHub Developer Guide documentation.
Get an installation for the authenticated app
Enables an authenticated GitHub App to find an installation's information using the installation id.
You must use a JWT to access this endpoint.
octokit.rest.apps.getInstallation({
installation_id,
});
Parameters
name | required | description |
---|---|---|
installation_id | yes |
The unique identifier of the installation. |
See also: GitHub Developer Guide documentation.
Get an organization installation for the authenticated app
Enables an authenticated GitHub App to find the organization's installation information.
You must use a JWT to access this endpoint.
octokit.rest.apps.getOrgInstallation({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
See also: GitHub Developer Guide documentation.
Get a repository installation for the authenticated app
Enables an authenticated GitHub App to find the repository's installation information. The installation's account type will be either an organization or a user account, depending which account the repository belongs to.
You must use a JWT to access this endpoint.
octokit.rest.apps.getRepoInstallation({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Get a subscription plan for an account
Shows whether the user or organization account actively subscribes to a plan listed by the authenticated GitHub App. When someone submits a plan change that won't be processed until the end of their billing cycle, you will also see the upcoming pending change.
GitHub Apps must use a JWT to access this endpoint. OAuth apps must use basic authentication with their client ID and client secret to access this endpoint.
octokit.rest.apps.getSubscriptionPlanForAccount({
account_id,
});
Parameters
name | required | description |
---|---|---|
account_id | yes |
account_id parameter |
See also: GitHub Developer Guide documentation.
Get a subscription plan for an account (stubbed)
Shows whether the user or organization account actively subscribes to a plan listed by the authenticated GitHub App. When someone submits a plan change that won't be processed until the end of their billing cycle, you will also see the upcoming pending change.
GitHub Apps must use a JWT to access this endpoint. OAuth apps must use basic authentication with their client ID and client secret to access this endpoint.
octokit.rest.apps.getSubscriptionPlanForAccountStubbed({
account_id,
});
Parameters
name | required | description |
---|---|---|
account_id | yes |
account_id parameter |
See also: GitHub Developer Guide documentation.
Get a user installation for the authenticated app
Enables an authenticated GitHub App to find the user’s installation information.
You must use a JWT to access this endpoint.
octokit.rest.apps.getUserInstallation({
username,
});
Parameters
name | required | description |
---|---|---|
username | yes |
The handle for the GitHub user account. |
See also: GitHub Developer Guide documentation.
Get a webhook configuration for an app
Returns the webhook configuration for a GitHub App. For more information about configuring a webhook for your app, see "Creating a GitHub App."
You must use a JWT to access this endpoint.
octokit.rest.apps.getWebhookConfigForApp();
Parameters
This endpoint has no parameters
See also: GitHub Developer Guide documentation.
Get a delivery for an app webhook
Returns a delivery for the webhook configured for a GitHub App.
You must use a JWT to access this endpoint.
octokit.rest.apps.getWebhookDelivery({
delivery_id,
});
Parameters
name | required | description |
---|---|---|
delivery_id | yes |
See also: GitHub Developer Guide documentation.
List accounts for a plan
Returns user and organization accounts associated with the specified plan, including free plans. For per-seat pricing, you see the list of accounts that have purchased the plan, including the number of seats purchased. When someone submits a plan change that won't be processed until the end of their billing cycle, you will also see the upcoming pending change.
GitHub Apps must use a JWT to access this endpoint. OAuth apps must use basic authentication with their client ID and client secret to access this endpoint.
octokit.rest.apps.listAccountsForPlan({
plan_id,
});
Parameters
name | required | description |
---|---|---|
plan_id | yes |
The unique identifier of the plan. |
sort | no |
The property to sort the results by. |
direction | no |
To return the oldest accounts first, set to |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List accounts for a plan (stubbed)
Returns repository and organization accounts associated with the specified plan, including free plans. For per-seat pricing, you see the list of accounts that have purchased the plan, including the number of seats purchased. When someone submits a plan change that won't be processed until the end of their billing cycle, you will also see the upcoming pending change.
GitHub Apps must use a JWT to access this endpoint. OAuth apps must use basic authentication with their client ID and client secret to access this endpoint.
octokit.rest.apps.listAccountsForPlanStubbed({
plan_id,
});
Parameters
name | required | description |
---|---|---|
plan_id | yes |
The unique identifier of the plan. |
sort | no |
The property to sort the results by. |
direction | no |
To return the oldest accounts first, set to |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List repositories accessible to the user access token
List repositories that the authenticated user has explicit permission (:read
, :write
, or :admin
) to access for an installation.
The authenticated user has explicit permission to access repositories they own, repositories where they are a collaborator, and repositories that they can access through an organization membership.
The access the user has to each repository is included in the hash under the permissions
key.
octokit.rest.apps.listInstallationReposForAuthenticatedUser({
installation_id,
});
Parameters
name | required | description |
---|---|---|
installation_id | yes |
The unique identifier of the installation. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List installation requests for the authenticated app
Lists all the pending installation requests for the authenticated GitHub App.
octokit.rest.apps.listInstallationRequestsForAuthenticatedApp();
Parameters
name | required | description |
---|---|---|
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List installations for the authenticated app
You must use a JWT to access this endpoint.
The permissions the installation has are included under the permissions
key.
octokit.rest.apps.listInstallations();
Parameters
name | required | description |
---|---|---|
per_page | no |
The number of results per page (max 100). |
page | no |
Page number of the results to fetch. |
since | no |
Only show results that were last updated after the given time. This is a timestamp in ISO 8601 format: |
outdated | no |
See also: GitHub Developer Guide documentation.
List app installations accessible to the user access token
Lists installations of your GitHub App that the authenticated user has explicit permission (:read
, :write
, or :admin
) to access.
The authenticated user has explicit permission to access repositories they own, repositories where they are a collaborator, and repositories that they can access through an organization membership.
You can find the permissions for the installation under the permissions
key.
octokit.rest.apps.listInstallationsForAuthenticatedUser();
Parameters
name | required | description |
---|---|---|
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List plans
Lists all plans that are part of your GitHub Marketplace listing.
GitHub Apps must use a JWT to access this endpoint. OAuth apps must use basic authentication with their client ID and client secret to access this endpoint.
octokit.rest.apps.listPlans();
Parameters
name | required | description |
---|---|---|
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List plans (stubbed)
Lists all plans that are part of your GitHub Marketplace listing.
GitHub Apps must use a JWT to access this endpoint. OAuth apps must use basic authentication with their client ID and client secret to access this endpoint.
octokit.rest.apps.listPlansStubbed();
Parameters
name | required | description |
---|---|---|
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List repositories accessible to the app installation
List repositories that an app installation can access.
octokit.rest.apps.listReposAccessibleToInstallation();
Parameters
name | required | description |
---|---|---|
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List subscriptions for the authenticated user
Lists the active subscriptions for the authenticated user.
octokit.rest.apps.listSubscriptionsForAuthenticatedUser();
Parameters
name | required | description |
---|---|---|
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List subscriptions for the authenticated user (stubbed)
Lists the active subscriptions for the authenticated user.
octokit.rest.apps.listSubscriptionsForAuthenticatedUserStubbed();
Parameters
name | required | description |
---|---|---|
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List deliveries for an app webhook
Returns a list of webhook deliveries for the webhook configured for a GitHub App.
You must use a JWT to access this endpoint.
octokit.rest.apps.listWebhookDeliveries();
Parameters
name | required | description |
---|---|---|
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
cursor | no |
Used for pagination: the starting delivery from which the page of deliveries is fetched. Refer to the |
redelivery | no |
See also: GitHub Developer Guide documentation.
Redeliver a delivery for an app webhook
Redeliver a delivery for the webhook configured for a GitHub App.
You must use a JWT to access this endpoint.
octokit.rest.apps.redeliverWebhookDelivery({
delivery_id,
});
Parameters
name | required | description |
---|---|---|
delivery_id | yes |
See also: GitHub Developer Guide documentation.
Remove a repository from an app installation
Deprecated: This method has been renamed to apps.removeRepoFromInstallationForAuthenticatedUser
Remove a single repository from an installation. The authenticated user must have admin access to the repository. The installation must have the repository_selection
of selected
.
octokit.rest.apps.removeRepoFromInstallation({
installation_id,
repository_id,
});
Parameters
name | required | description |
---|---|---|
installation_id | yes |
The unique identifier of the installation. |
repository_id | yes |
The unique identifier of the repository. |
See also: GitHub Developer Guide documentation.
Remove a repository from an app installation
Remove a single repository from an installation. The authenticated user must have admin access to the repository. The installation must have the repository_selection
of selected
.
octokit.rest.apps.removeRepoFromInstallationForAuthenticatedUser({
installation_id,
repository_id,
});
Parameters
name | required | description |
---|---|---|
installation_id | yes |
The unique identifier of the installation. |
repository_id | yes |
The unique identifier of the repository. |
See also: GitHub Developer Guide documentation.
Reset a token
OAuth applications and GitHub applications with OAuth authorizations can use this API method to reset a valid OAuth token without end-user involvement. Applications must save the "token" property in the response because changes take effect immediately. You must use Basic Authentication when accessing this endpoint, using the application's client_id
and client_secret
as the username and password. Invalid tokens will return 404 NOT FOUND
.
octokit.rest.apps.resetToken({
client_id,
access_token,
});
Parameters
name | required | description |
---|---|---|
client_id | yes |
The client ID of the GitHub app. |
access_token | yes |
The access_token of the OAuth or GitHub application. |
See also: GitHub Developer Guide documentation.
Revoke an installation access token
Revokes the installation token you're using to authenticate as an installation and access this endpoint.
Once an installation token is revoked, the token is invalidated and cannot be used. Other endpoints that require the revoked installation token must have a new installation token to work. You can create a new token using the "Create an installation access token for an app" endpoint.
octokit.rest.apps.revokeInstallationAccessToken();
Parameters
This endpoint has no parameters
See also: GitHub Developer Guide documentation.
Create a scoped access token
Use a non-scoped user access token to create a repository-scoped and/or permission-scoped user access token. You can specify which repositories the token can access and which permissions are granted to the token.
Invalid tokens will return 404 NOT FOUND
.
You must use Basic Authentication
when accessing this endpoint, using the client_id
and client_secret
of the GitHub App
as the username and password.
octokit.rest.apps.scopeToken({
client_id,
access_token,
});
Parameters
name | required | description |
---|---|---|
client_id | yes |
The client ID of the GitHub app. |
access_token | yes |
The access token used to authenticate to the GitHub API. |
target | no |
The name of the user or organization to scope the user access token to. Required unless |
target_id | no |
The ID of the user or organization to scope the user access token to. Required unless |
repositories | no |
The list of repository names to scope the user access token to. |
repository_ids | no |
The list of repository IDs to scope the user access token to. |
permissions | no |
The permissions granted to the user access token. |
permissions.actions | no |
The level of permission to grant the access token for GitHub Actions workflows, workflow runs, and artifacts. |
permissions.administration | no |
The level of permission to grant the access token for repository creation, deletion, settings, teams, and collaborators creation. |
permissions.checks | no |
The level of permission to grant the access token for checks on code. |
permissions.codespaces | no |
The level of permission to grant the access token to create, edit, delete, and list Codespaces. |
permissions.contents | no |
The level of permission to grant the access token for repository contents, commits, branches, downloads, releases, and merges. |
permissions.dependabot_secrets | no |
The leve of permission to grant the access token to manage Dependabot secrets. |
permissions.deployments | no |
The level of permission to grant the access token for deployments and deployment statuses. |
permissions.environments | no |
The level of permission to grant the access token for managing repository environments. |
permissions.issues | no |
The level of permission to grant the access token for issues and related comments, assignees, labels, and milestones. |
permissions.metadata | no |
The level of permission to grant the access token to search repositories, list collaborators, and access repository metadata. |
permissions.packages | no |
The level of permission to grant the access token for packages published to GitHub Packages. |
permissions.pages | no |
The level of permission to grant the access token to retrieve Pages statuses, configuration, and builds, as well as create new builds. |
permissions.pull_requests | no |
The level of permission to grant the access token for pull requests and related comments, assignees, labels, milestones, and merges. |
permissions.repository_custom_properties | no |
The level of permission to grant the access token to view and edit custom properties for a repository, when allowed by the property. |
permissions.repository_hooks | no |
The level of permission to grant the access token to manage the post-receive hooks for a repository. |
permissions.repository_projects | no |
The level of permission to grant the access token to manage repository projects, columns, and cards. |
permissions.secret_scanning_alerts | no |
The level of permission to grant the access token to view and manage secret scanning alerts. |
permissions.secrets | no |
The level of permission to grant the access token to manage repository secrets. |
permissions.security_events | no |
The level of permission to grant the access token to view and manage security events like code scanning alerts. |
permissions.single_file | no |
The level of permission to grant the access token to manage just a single file. |
permissions.statuses | no |
The level of permission to grant the access token for commit statuses. |
permissions.vulnerability_alerts | no |
The level of permission to grant the access token to manage Dependabot alerts. |
permissions.workflows | no |
The level of permission to grant the access token to update GitHub Actions workflow files. |
permissions.members | no |
The level of permission to grant the access token for organization teams and members. |
permissions.organization_administration | no |
The level of permission to grant the access token to manage access to an organization. |
permissions.organization_custom_roles | no |
The level of permission to grant the access token for custom repository roles management. |
permissions.organization_custom_org_roles | no |
The level of permission to grant the access token for custom organization roles management. |
permissions.organization_custom_properties | no |
The level of permission to grant the access token for custom property management. |
permissions.organization_copilot_seat_management | no |
The level of permission to grant the access token for managing access to GitHub Copilot for members of an organization with a Copilot Business subscription. This property is in beta and is subject to change. |
permissions.organization_announcement_banners | no |
The level of permission to grant the access token to view and manage announcement banners for an organization. |
permissions.organization_events | no |
The level of permission to grant the access token to view events triggered by an activity in an organization. |
permissions.organization_hooks | no |
The level of permission to grant the access token to manage the post-receive hooks for an organization. |
permissions.organization_personal_access_tokens | no |
The level of permission to grant the access token for viewing and managing fine-grained personal access token requests to an organization. |
permissions.organization_personal_access_token_requests | no |
The level of permission to grant the access token for viewing and managing fine-grained personal access tokens that have been approved by an organization. |
permissions.organization_plan | no |
The level of permission to grant the access token for viewing an organization's plan. |
permissions.organization_projects | no |
The level of permission to grant the access token to manage organization projects and projects beta (where available). |
permissions.organization_packages | no |
The level of permission to grant the access token for organization packages published to GitHub Packages. |
permissions.organization_secrets | no |
The level of permission to grant the access token to manage organization secrets. |
permissions.organization_self_hosted_runners | no |
The level of permission to grant the access token to view and manage GitHub Actions self-hosted runners available to an organization. |
permissions.organization_user_blocking | no |
The level of permission to grant the access token to view and manage users blocked by the organization. |
permissions.team_discussions | no |
The level of permission to grant the access token to manage team discussions and related comments. |
permissions.email_addresses | no |
The level of permission to grant the access token to manage the email addresses belonging to a user. |
permissions.followers | no |
The level of permission to grant the access token to manage the followers belonging to a user. |
permissions.git_ssh_keys | no |
The level of permission to grant the access token to manage git SSH keys. |
permissions.gpg_keys | no |
The level of permission to grant the access token to view and manage GPG keys belonging to a user. |
permissions.interaction_limits | no |
The level of permission to grant the access token to view and manage interaction limits on a repository. |
permissions.profile | no |
The level of permission to grant the access token to manage the profile settings belonging to a user. |
permissions.starring | no |
The level of permission to grant the access token to list and manage repositories a user is starring. |
See also: GitHub Developer Guide documentation.
Suspend an app installation
Suspends a GitHub App on a user, organization, or business account, which blocks the app from accessing the account's resources. When a GitHub App is suspended, the app's access to the GitHub API or webhook events is blocked for that account.
You must use a JWT to access this endpoint.
octokit.rest.apps.suspendInstallation({
installation_id,
});
Parameters
name | required | description |
---|---|---|
installation_id | yes |
The unique identifier of the installation. |
See also: GitHub Developer Guide documentation.
Unsuspend an app installation
Removes a GitHub App installation suspension.
You must use a JWT to access this endpoint.
octokit.rest.apps.unsuspendInstallation({
installation_id,
});
Parameters
name | required | description |
---|---|---|
installation_id | yes |
The unique identifier of the installation. |
See also: GitHub Developer Guide documentation.
Update a webhook configuration for an app
Updates the webhook configuration for a GitHub App. For more information about configuring a webhook for your app, see "Creating a GitHub App."
You must use a JWT to access this endpoint.
octokit.rest.apps.updateWebhookConfigForApp();
Parameters
name | required | description |
---|---|---|
url | no |
The URL to which the payloads will be delivered. |
content_type | no |
The media type used to serialize the payloads. Supported values include |
secret | no |
If provided, the |
insecure_ssl | no |
See also: GitHub Developer Guide documentation.
Billing
Get GitHub Actions billing for an organization
Gets the summary of the free and paid GitHub Actions minutes used.
Paid minutes only apply to workflows in private repositories that use GitHub-hosted runners. Minutes used is listed for each GitHub-hosted runner operating system. Any job re-runs are also included in the usage. The usage returned includes any minute multipliers for macOS and Windows runners, and is rounded up to the nearest whole minute. For more information, see "Managing billing for GitHub Actions".
OAuth app tokens and personal access tokens (classic) need the repo
or admin:org
scope to use this endpoint.
octokit.rest.billing.getGithubActionsBillingOrg({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
See also: GitHub Developer Guide documentation.
Get GitHub Actions billing for a user
Gets the summary of the free and paid GitHub Actions minutes used.
Paid minutes only apply to workflows in private repositories that use GitHub-hosted runners. Minutes used is listed for each GitHub-hosted runner operating system. Any job re-runs are also included in the usage. The usage returned includes any minute multipliers for macOS and Windows runners, and is rounded up to the nearest whole minute. For more information, see "Managing billing for GitHub Actions".
OAuth app tokens and personal access tokens (classic) need the user
scope to use this endpoint.
octokit.rest.billing.getGithubActionsBillingUser({
username,
});
Parameters
name | required | description |
---|---|---|
username | yes |
The handle for the GitHub user account. |
See also: GitHub Developer Guide documentation.
Get GitHub Packages billing for an organization
Gets the free and paid storage used for GitHub Packages in gigabytes.
Paid minutes only apply to packages stored for private repositories. For more information, see "Managing billing for GitHub Packages."
OAuth app tokens and personal access tokens (classic) need the repo
or admin:org
scope to use this endpoint.
octokit.rest.billing.getGithubPackagesBillingOrg({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
See also: GitHub Developer Guide documentation.
Get GitHub Packages billing for a user
Gets the free and paid storage used for GitHub Packages in gigabytes.
Paid minutes only apply to packages stored for private repositories. For more information, see "Managing billing for GitHub Packages."
OAuth app tokens and personal access tokens (classic) need the user
scope to use this endpoint.
octokit.rest.billing.getGithubPackagesBillingUser({
username,
});
Parameters
name | required | description |
---|---|---|
username | yes |
The handle for the GitHub user account. |
See also: GitHub Developer Guide documentation.
Get shared storage billing for an organization
Gets the estimated paid and estimated total storage used for GitHub Actions and GitHub Packages.
Paid minutes only apply to packages stored for private repositories. For more information, see "Managing billing for GitHub Packages."
OAuth app tokens and personal access tokens (classic) need the repo
or admin:org
scope to use this endpoint.
octokit.rest.billing.getSharedStorageBillingOrg({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
See also: GitHub Developer Guide documentation.
Get shared storage billing for a user
Gets the estimated paid and estimated total storage used for GitHub Actions and GitHub Packages.
Paid minutes only apply to packages stored for private repositories. For more information, see "Managing billing for GitHub Packages."
OAuth app tokens and personal access tokens (classic) need the user
scope to use this endpoint.
octokit.rest.billing.getSharedStorageBillingUser({
username,
});
Parameters
name | required | description |
---|---|---|
username | yes |
The handle for the GitHub user account. |
See also: GitHub Developer Guide documentation.
Checks
Create 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.
Creates a new check run for a specific commit in a repository. Your GitHub App must have the checks:write
permission to create check runs.
In a check suite, GitHub limits the number of check runs with the same name to 1000. Once these check runs exceed 1000, GitHub will start to automatically delete older check runs.
octokit.rest.checks.create({
owner,
repo,
name,
head_sha,
output.title,
output.summary,
output.annotations[].path,
output.annotations[].start_line,
output.annotations[].end_line,
output.annotations[].annotation_level,
output.annotations[].message,
output.images[].alt,
output.images[].image_url,
actions[].label,
actions[].description,
actions[].identifier
})
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository. The name is not case sensitive. |
name | yes |
The name of the check. For example, "code-coverage". |
head_sha | yes |
The SHA of the commit. |
details_url | no |
The URL of the integrator's site that has the full details of the check. If the integrator does not provide this, then the homepage of the GitHub app is used. |
external_id | no |
A reference for the run on the integrator's system. |
status | no |
The current status. |
started_at | no |
The time that the check run began. This is a timestamp in ISO 8601 format: |
conclusion | no |
Required if you provide |
completed_at | no |
The time the check completed. This is a timestamp in ISO 8601 format: |
output | no |
Check runs can accept a variety of data in the |
output.title | yes |
The title of the check run. |
output.summary | yes |
The summary of the check run. This parameter supports Markdown. Maximum length: 65535 characters. |
output.text | no |
The details of the check run. This parameter supports Markdown. Maximum length: 65535 characters. |
output.annotations | no |
Adds information from your analysis to specific lines of code. Annotations are visible on GitHub in the Checks and Files changed tab of the pull request. The Checks API limits the number of annotations to a maximum of 50 per API request. To create more than 50 annotations, you have to make multiple requests to the Update a check run endpoint. Each time you update the check run, annotations are appended to the list of annotations that already exist for the check run. GitHub Actions are limited to 10 warning annotations and 10 error annotations per step. For details about how you can view annotations on GitHub, see "About status checks". |
output.annotations[].path | yes |
The path of the file to add an annotation to. For example, |
output.annotations[].start_line | yes |
The start line of the annotation. Line numbers start at 1. |
output.annotations[].end_line | yes |
The end line of the annotation. |
output.annotations[].start_column | no |
The start column of the annotation. Annotations only support |
output.annotations[].end_column | no |
The end column of the annotation. Annotations only support |
output.annotations[].annotation_level | yes |
The level of the annotation. |
output.annotations[].message | yes |
A short description of the feedback for these lines of code. The maximum size is 64 KB. |
output.annotations[].title | no |
The title that represents the annotation. The maximum size is 255 characters. |
output.annotations[].raw_details | no |
Details about this annotation. The maximum size is 64 KB. |
output.images | no |
Adds images to the output displayed in the GitHub pull request UI. |
output.images[].alt | yes |
The alternative text for the image. |
output.images[].image_url | yes |
The full URL of the image. |
output.images[].caption | no |
A short image description. |
actions | no |
Displays a button on GitHub that can be clicked to alert your app to do additional tasks. For example, a code linting app can display a button that automatically fixes detected errors. The button created in this object is displayed after the check run completes. When a user clicks the button, GitHub sends the |
actions[].label | yes |
The text to be displayed on a button in the web UI. The maximum size is 20 characters. |
actions[].description | yes |
A short explanation of what this action would do. The maximum size is 40 characters. |
actions[].identifier | yes |
A reference for the action on the integrator's system. The maximum size is 20 characters. |
See also: GitHub Developer Guide documentation.
Create a check suite
Creates a check suite manually. By default, check suites are automatically created when you create a check run. You only need to use this endpoint for manually creating check suites when you've disabled automatic creation using "Update repository preferences for check suites".
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
.
OAuth apps and personal access tokens (classic) cannot use this endpoint.
octokit.rest.checks.createSuite({
owner,
repo,
head_sha,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
head_sha | yes |
The sha of the head commit. |
See also: GitHub Developer Guide documentation.
Get a check run
Gets a single check run using its id
.
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.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint on a private repository.
octokit.rest.checks.get({
owner,
repo,
check_run_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
check_run_id | yes |
The unique identifier of the check run. |
See also: GitHub Developer Guide documentation.
Get a check suite
Gets a single check suite using its id
.
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
.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint on a private repository.
octokit.rest.checks.getSuite({
owner,
repo,
check_suite_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
check_suite_id | yes |
The unique identifier of the check suite. |
See also: GitHub Developer Guide documentation.
List check run annotations
Lists annotations for a check run using the annotation id
.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint on a private repository.
octokit.rest.checks.listAnnotations({
owner,
repo,
check_run_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
check_run_id | yes |
The unique identifier of the check run. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List check runs for a Git reference
Lists check runs for a commit ref. The ref
can be a SHA, branch name, or a tag name.
Note: The endpoints to manage checks only look 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.
If there are more than 1000 check suites on a single git reference, this endpoint will limit check runs to the 1000 most recent check suites. To iterate over all possible check runs, use the List check suites for a Git reference endpoint and provide the check_suite_id
parameter to the List check runs in a check suite endpoint.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint on a private repository.
octokit.rest.checks.listForRef({
owner,
repo,
ref,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
ref | yes |
The commit reference. Can be a commit SHA, branch name ( |
check_name | no |
Returns check runs with the specified |
status | no |
Returns check runs with the specified |
filter | no |
Filters check runs by their |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
app_id | no |
See also: GitHub Developer Guide documentation.
List check runs in a check suite
Lists check runs for a check suite using its id
.
Note: The endpoints to manage checks only look 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.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint on a private repository.
octokit.rest.checks.listForSuite({
owner,
repo,
check_suite_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
check_suite_id | yes |
The unique identifier of the check suite. |
check_name | no |
Returns check runs with the specified |
status | no |
Returns check runs with the specified |
filter | no |
Filters check runs by their |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List check suites for a Git reference
Lists check suites for a commit ref
. The ref
can be a SHA, branch name, or a tag name.
Note: The endpoints to manage checks only look 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
.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint on a private repository.
octokit.rest.checks.listSuitesForRef({
owner,
repo,
ref,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
ref | yes |
The commit reference. Can be a commit SHA, branch name ( |
app_id | no |
Filters check suites by GitHub App |
check_name | no |
Returns check runs with the specified |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
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 event with the action rerequested
. When a check run is rerequested
, its status
is reset to queued
and the conclusion
is cleared.
For more information about how to re-run GitHub Actions jobs, see "Re-run a job from a workflow run".
OAuth apps and personal access tokens (classic) cannot use this endpoint.
octokit.rest.checks.rerequestRun({
owner,
repo,
check_run_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
check_run_id | yes |
The unique identifier of the check run. |
See also: GitHub Developer Guide documentation.
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 event with the action rerequested
. When a check suite is rerequested
, its status
is reset to queued
and the conclusion
is cleared.
OAuth apps and personal access tokens (classic) cannot use this endpoint.
octokit.rest.checks.rerequestSuite({
owner,
repo,
check_suite_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
check_suite_id | yes |
The unique identifier of the check suite. |
See also: GitHub Developer Guide documentation.
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. You must have admin permissions in the repository to set preferences for check suites.
octokit.rest.checks.setSuitesPreferences({
owner,
repo,
auto_trigger_checks[].app_id,
auto_trigger_checks[].setting
})
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
auto_trigger_checks | no |
Enables or disables automatic creation of CheckSuite events upon pushes to the repository. Enabled by default. |
auto_trigger_checks[].app_id | yes |
The |
auto_trigger_checks[].setting | yes |
Set to |
See also: GitHub Developer Guide documentation.
Update a check run
Updates a check run for a specific commit in a repository.
Note: The endpoints to manage checks only look 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.
OAuth apps and personal access tokens (classic) cannot use this endpoint.
octokit.rest.checks.update({
owner,
repo,
check_run_id,
output.summary,
output.annotations[].path,
output.annotations[].start_line,
output.annotations[].end_line,
output.annotations[].annotation_level,
output.annotations[].message,
output.images[].alt,
output.images[].image_url,
actions[].label,
actions[].description,
actions[].identifier
})
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
check_run_id | yes |
The unique identifier of the check run. |
name | no |
The name of the check. For example, "code-coverage". |
details_url | no |
The URL of the integrator's site that has the full details of the check. |
external_id | no |
A reference for the run on the integrator's system. |
started_at | no |
This is a timestamp in ISO 8601 format: |
status | no |
The current status of the check run. Only GitHub Actions can set a status of |
conclusion | no |
Required if you provide |
completed_at | no |
The time the check completed. This is a timestamp in ISO 8601 format: |
output | no |
Check runs can accept a variety of data in the |
output.title | no |
Required. |
output.summary | yes |
Can contain Markdown. |
output.text | no |
Can contain Markdown. |
output.annotations | no |
Adds information from your analysis to specific lines of code. Annotations are visible in GitHub's pull request UI. Annotations are visible in GitHub's pull request UI. The Checks API limits the number of annotations to a maximum of 50 per API request. To create more than 50 annotations, you have to make multiple requests to the Update a check run endpoint. Each time you update the check run, annotations are appended to the list of annotations that already exist for the check run. GitHub Actions are limited to 10 warning annotations and 10 error annotations per step. For details about annotations in the UI, see "About status checks". |
output.annotations[].path | yes |
The path of the file to add an annotation to. For example, |
output.annotations[].start_line | yes |
The start line of the annotation. Line numbers start at 1. |
output.annotations[].end_line | yes |
The end line of the annotation. |
output.annotations[].start_column | no |
The start column of the annotation. Annotations only support |
output.annotations[].end_column | no |
The end column of the annotation. Annotations only support |
output.annotations[].annotation_level | yes |
The level of the annotation. |
output.annotations[].message | yes |
A short description of the feedback for these lines of code. The maximum size is 64 KB. |
output.annotations[].title | no |
The title that represents the annotation. The maximum size is 255 characters. |
output.annotations[].raw_details | no |
Details about this annotation. The maximum size is 64 KB. |
output.images | no |
Adds images to the output displayed in the GitHub pull request UI. |
output.images[].alt | yes |
The alternative text for the image. |
output.images[].image_url | yes |
The full URL of the image. |
output.images[].caption | no |
A short image description. |
actions | no |
Possible further actions the integrator can perform, which a user may trigger. Each action includes a |
actions[].label | yes |
The text to be displayed on a button in the web UI. The maximum size is 20 characters. |
actions[].description | yes |
A short explanation of what this action would do. The maximum size is 40 characters. |
actions[].identifier | yes |
A reference for the action on the integrator's system. The maximum size is 20 characters. |
See also: GitHub Developer Guide documentation.
Code-Scanning
Delete a code scanning analysis from a repository
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:
"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
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:
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:
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.
octokit.rest.codeScanning.deleteAnalysis({
owner,
repo,
analysis_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
analysis_id | yes |
The ID of the analysis, as returned from the |
confirm_delete | no |
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 |
See also: GitHub Developer Guide documentation.
Get a code scanning alert
Gets a single code scanning alert.
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.
octokit.rest.codeScanning.getAlert({
owner,
repo,
alert_number,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
alert_number | yes |
The number that identifies an alert. You can find this at the end of the URL for a code scanning alert within GitHub, and in the |
alert_id | no |
The number that identifies an alert. You can find this at the end of the URL for a code scanning alert within GitHub, and in the |
See also: GitHub Developer Guide documentation.
Get a code scanning analysis for a repository
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 thegithub/alertNumber
andgithub/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.
octokit.rest.codeScanning.getAnalysis({
owner,
repo,
analysis_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
analysis_id | yes |
The ID of the analysis, as returned from the |
See also: GitHub Developer Guide documentation.
Get a CodeQL database for a repository
Gets a CodeQL database for a language in a repository.
By default this endpoint returns JSON metadata about the CodeQL database. To
download the CodeQL database binary content, set the Accept
header of the request
to application/zip
, and make sure
your HTTP client is configured to follow redirects or use the Location
header
to make a second request to get the redirect URL.
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.
octokit.rest.codeScanning.getCodeqlDatabase({
owner,
repo,
language,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
language | yes |
The language of the CodeQL database. |
See also: GitHub Developer Guide documentation.
Get a code scanning default setup configuration
Gets a code scanning default setup configuration.
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.
octokit.rest.codeScanning.getDefaultSetup({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
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."
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.
octokit.rest.codeScanning.getSarif({
owner,
repo,
sarif_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
sarif_id | yes |
The SARIF ID obtained after uploading. |
See also: GitHub Developer Guide documentation.
List instances of a code scanning alert
Lists all instances of the specified code scanning alert.
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.
octokit.rest.codeScanning.listAlertInstances({
owner,
repo,
alert_number,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
alert_number | yes |
The number that identifies an alert. You can find this at the end of the URL for a code scanning alert within GitHub, and in the |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
ref | no |
The Git reference for the results you want to list. The |
See also: GitHub Developer Guide documentation.
List code scanning alerts for an organization
Lists code scanning alerts for the default branch for all eligible repositories in an organization. Eligible repositories are repositories that are owned by organizations that you own or for which you are a security manager. For more information, see "Managing security managers in your organization."
The authenticated user must be an owner or security manager for the organization to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the security_events
or repo
s cope to use this endpoint with private or public repositories, or the public_repo
scope to use this endpoint with only public repositories.
octokit.rest.codeScanning.listAlertsForOrg({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
tool_name | no |
The name of a code scanning tool. Only results by this tool will be listed. You can specify the tool by using either |
tool_guid | no |
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 |
before | no |
A cursor, as given in the Link header. If specified, the query only searches for results before this cursor. For more information, see "Using pagination in the REST API." |
after | no |
A cursor, as given in the Link header. If specified, the query only searches for results after this cursor. For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
direction | no |
The direction to sort the results by. |
state | no |
If specified, only code scanning alerts with this state will be returned. |
sort | no |
The property by which to sort the results. |
severity | no |
If specified, only code scanning alerts with this severity will be returned. |
See also: GitHub Developer Guide documentation.
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 with private repos, the public_repo
scope also grants permission to read
security events on public repos only. 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).
octokit.rest.codeScanning.listAlertsForRepo({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository. The name is not case sensitive. |
tool_name | no |
The name of a code scanning tool. Only results by this tool will be listed. You can specify the tool by using either |
tool_guid | no |
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 |
page | no |
Page number of the results to fetch. |
per_page | no |
The number of results per page (max 100). |
ref | no |
The Git reference for the results you want to list. The |
direction | no |
The direction to sort the results by. |
sort | no |
The property by which to sort the results. |
state | no |
Set to |
See also: GitHub Developer Guide documentation.
List instances of a code scanning alert
Deprecated: This method has been renamed to codeScanning.listAlertInstances
Lists all instances of the specified code scanning alert.
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.
octokit.rest.codeScanning.listAlertsInstances({
owner,
repo,
alert_number,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
alert_number | yes |
The number that identifies an alert. You can find this at the end of the URL for a code scanning alert within GitHub, and in the |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
ref | no |
The Git reference for the results you want to list. The |
See also: GitHub Developer Guide documentation.
List CodeQL databases for a repository
Lists the CodeQL databases that are available in a repository.
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.
octokit.rest.codeScanning.listCodeqlDatabases({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
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.
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.
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.
octokit.rest.codeScanning.listRecentAnalyses({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
tool_name | no |
The name of a code scanning tool. Only results by this tool will be listed. You can specify the tool by using either |
tool_guid | no |
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 |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
ref | no |
The Git reference for the analyses you want to list. The |
sarif_id | no |
Filter analyses belonging to the same SARIF upload. |
direction | no |
The direction to sort the results by. |
sort | no |
The property by which to sort the results. |
See also: GitHub Developer Guide documentation.
Update a code scanning alert
Updates the status of a single code scanning alert.
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.
octokit.rest.codeScanning.updateAlert({
owner,
repo,
alert_number,
state,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
alert_number | yes |
The number that identifies an alert. You can find this at the end of the URL for a code scanning alert within GitHub, and in the |
state | yes |
Sets the state of the code scanning alert. You must provide |
dismissed_reason | no |
Required when the state is dismissed. The reason for dismissing or closing the alert. |
dismissed_comment | no |
The dismissal comment associated with the dismissal of the alert. |
See also: GitHub Developer Guide documentation.
Update a code scanning default setup configuration
Updates a code scanning default setup configuration.
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.
octokit.rest.codeScanning.updateDefaultSetup({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
state | no |
The desired state of code scanning default setup. |
query_suite | no |
CodeQL query suite to be used. |
languages | no |
CodeQL languages to be analyzed. |
See also: GitHub Developer Guide documentation.
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. For troubleshooting information, see "Troubleshooting SARIF uploads."
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." - 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."
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. For more information, see "SARIF results exceed one or more limits."
SARIF data | Maximum values | Additional limits |
---|---|---|
Runs per file | 20 | |
Results per run | 25,000 | Only the top 5,000 results will be included, prioritized by severity. |
Rules per run | 25,000 | |
Tool extensions per run | 100 | |
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. |
Tags per rule | 20 | Only 10 tags 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."
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.
octokit.rest.codeScanning.uploadSarif({
owner,
repo,
commit_sha,
ref,
sarif,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
commit_sha | yes |
The SHA of the commit to which the analysis you are uploading relates. |
ref | yes |
The full Git reference, formatted as |
sarif | yes |
A Base64 string representing the SARIF file to upload. You must first compress your SARIF file using |
checkout_uri | no |
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 | no |
The time that the analysis run began. This is a timestamp in ISO 8601 format: |
tool_name | no |
The name of the tool used to generate the code scanning analysis. If this parameter is not used, the tool name defaults to "API". If the uploaded SARIF contains a tool GUID, this will be available for filtering using the |
validate | no |
Whether the SARIF file will be validated according to the code scanning specifications. This parameter is intended to help integrators ensure that the uploaded SARIF files are correctly rendered by code scanning. |
See also: GitHub Developer Guide documentation.
Codes-of-Conduct
Get all codes of conduct
Returns array of all GitHub's codes of conduct.
octokit.rest.codesOfConduct.getAllCodesOfConduct();
Parameters
This endpoint has no parameters
See also: GitHub Developer Guide documentation.
Get a code of conduct
Returns information about the specified GitHub code of conduct.
octokit.rest.codesOfConduct.getConductCode({
key,
});
Parameters
name | required | description |
---|---|---|
key | yes |
See also: GitHub Developer Guide documentation.
Codespaces
Add a selected repository to a user secret
Adds a repository to the selected repositories for a user's development environment secret.
The authenticated user must have Codespaces access to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the codespace
or codespace:secrets
scope to use this endpoint.
octokit.rest.codespaces.addRepositoryForSecretForAuthenticatedUser({
secret_name,
repository_id,
});
Parameters
name | required | description |
---|---|---|
secret_name | yes |
The name of the secret. |
repository_id | yes |
See also: GitHub Developer Guide documentation.
Add selected repository to an organization secret
Adds a repository to an organization development environment secret when the visibility
for repository access is set to selected
. The visibility is set when you Create or update an organization secret.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.codespaces.addSelectedRepoToOrgSecret({
org,
secret_name,
repository_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
secret_name | yes |
The name of the secret. |
repository_id | yes |
See also: GitHub Developer Guide documentation.
Check if permissions defined by a devcontainer have been accepted by the authenticated user
Checks whether the permissions defined by a given devcontainer configuration have been accepted by the authenticated user.
OAuth app tokens and personal access tokens (classic) need the codespace
scope to use this endpoint.
octokit.rest.codespaces.checkPermissionsForDevcontainer({
owner,
repo,
ref,
devcontainer_path,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
ref | yes |
The git reference that points to the location of the devcontainer configuration to use for the permission check. The value of |
devcontainer_path | yes |
Path to the devcontainer.json configuration to use for the permission check. |
See also: GitHub Developer Guide documentation.
List machine types for a codespace
List the machine types a codespace can transition to use.
OAuth app tokens and personal access tokens (classic) need the codespace
scope to use this endpoint.
octokit.rest.codespaces.codespaceMachinesForAuthenticatedUser({
codespace_name,
});
Parameters
name | required | description |
---|---|---|
codespace_name | yes |
The name of the codespace. |
See also: GitHub Developer Guide documentation.
Create a codespace for the authenticated user
Creates a new codespace, owned by the authenticated user.
This endpoint requires either a repository_id
OR a pull_request
but not both.
OAuth app tokens and personal access tokens (classic) need the codespace
scope to use this endpoint.
octokit.rest.codespaces.createForAuthenticatedUser({
repository_id,
pull_request,
pull_request.pull_request_number,
pull_request.repository_id
})
Parameters
name | required | description |
---|---|---|
repository_id | yes |
Repository id for this codespace |
ref | no |
Git ref (typically a branch name) for this codespace |
location | no |
The requested location for a new codespace. Best efforts are made to respect this upon creation. Assigned by IP if not provided. |
geo | no |
The geographic area for this codespace. If not specified, the value is assigned by IP. This property replaces |
client_ip | no |
IP for location auto-detection when proxying a request |
machine | no |
Machine type to use for this codespace |
devcontainer_path | no |
Path to devcontainer.json config to use for this codespace |
multi_repo_permissions_opt_out | no |
Whether to authorize requested permissions from devcontainer.json |
working_directory | no |
Working directory for this codespace |
idle_timeout_minutes | no |
Time in minutes before codespace stops from inactivity |
display_name | no |
Display name for this codespace |
retention_period_minutes | no |
Duration in minutes after codespace has gone idle in which it will be deleted. Must be integer minutes between 0 and 43200 (30 days). |
pull_request | yes |
Pull request number for this codespace |
pull_request.pull_request_number | yes |
Pull request number |
pull_request.repository_id | yes |
Repository id for this codespace |
See also: GitHub Developer Guide documentation.
Create or update an organization secret
Creates or updates an organization development environment secret with an encrypted value. Encrypt your secret using LibSodium. For more information, see "Encrypting secrets for the REST API."
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.codespaces.createOrUpdateOrgSecret({
org,
secret_name,
visibility,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
secret_name | yes |
The name of the secret. |
encrypted_value | no |
The value for your secret, encrypted with LibSodium using the public key retrieved from the Get an organization public key endpoint. |
key_id | no |
The ID of the key you used to encrypt the secret. |
visibility | yes |
Which type of organization repositories have access to the organization secret. |
selected_repository_ids | no |
An array of repository IDs that can access the organization secret. You can only provide a list of repository IDs when the |
See also: GitHub Developer Guide documentation.
Create or update a repository secret
Creates or updates a repository development environment secret with an encrypted value. Encrypt your secret using LibSodium. For more information, see "Encrypting secrets for the REST API."
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.codespaces.createOrUpdateRepoSecret({
owner,
repo,
secret_name,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
secret_name | yes |
The name of the secret. |
encrypted_value | no |
Value for your secret, encrypted with LibSodium using the public key retrieved from the Get a repository public key endpoint. |
key_id | no |
ID of the key you used to encrypt the secret. |
See also: GitHub Developer Guide documentation.
Create or update a secret for the authenticated user
Creates or updates a development environment secret for a user's codespace with an encrypted value. Encrypt your secret using LibSodium. For more information, see "Encrypting secrets for the REST API."
The authenticated user must have Codespaces access to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the codespace
or codespace:secrets
scope to use this endpoint.
octokit.rest.codespaces.createOrUpdateSecretForAuthenticatedUser({
secret_name,
key_id,
});
Parameters
name | required | description |
---|---|---|
secret_name | yes |
The name of the secret. |
encrypted_value | no |
Value for your secret, encrypted with LibSodium using the public key retrieved from the Get the public key for the authenticated user endpoint. |
key_id | yes |
ID of the key you used to encrypt the secret. |
selected_repository_ids | no |
An array of repository ids that can access the user secret. You can manage the list of selected repositories using the List selected repositories for a user secret, Set selected repositories for a user secret, and Remove a selected repository from a user secret endpoints. |
See also: GitHub Developer Guide documentation.
Create a codespace from a pull request
Creates a codespace owned by the authenticated user for the specified pull request.
OAuth app tokens and personal access tokens (classic) need the codespace
scope to use this endpoint.
octokit.rest.codespaces.createWithPrForAuthenticatedUser({
owner,
repo,
pull_number,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
pull_number | yes |
The number that identifies the pull request. |
location | no |
The requested location for a new codespace. Best efforts are made to respect this upon creation. Assigned by IP if not provided. |
geo | no |
The geographic area for this codespace. If not specified, the value is assigned by IP. This property replaces |
client_ip | no |
IP for location auto-detection when proxying a request |
machine | no |
Machine type to use for this codespace |
devcontainer_path | no |
Path to devcontainer.json config to use for this codespace |
multi_repo_permissions_opt_out | no |
Whether to authorize requested permissions from devcontainer.json |
working_directory | no |
Working directory for this codespace |
idle_timeout_minutes | no |
Time in minutes before codespace stops from inactivity |
display_name | no |
Display name for this codespace |
retention_period_minutes | no |
Duration in minutes after codespace has gone idle in which it will be deleted. Must be integer minutes between 0 and 43200 (30 days). |
See also: GitHub Developer Guide documentation.
Create a codespace in a repository
Creates a codespace owned by the authenticated user in the specified repository.
OAuth app tokens and personal access tokens (classic) need the codespace
scope to use this endpoint.
octokit.rest.codespaces.createWithRepoForAuthenticatedUser({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
ref | no |
Git ref (typically a branch name) for this codespace |
location | no |
The requested location for a new codespace. Best efforts are made to respect this upon creation. Assigned by IP if not provided. |
geo | no |
The geographic area for this codespace. If not specified, the value is assigned by IP. This property replaces |
client_ip | no |
IP for location auto-detection when proxying a request |
machine | no |
Machine type to use for this codespace |
devcontainer_path | no |
Path to devcontainer.json config to use for this codespace |
multi_repo_permissions_opt_out | no |
Whether to authorize requested permissions from devcontainer.json |
working_directory | no |
Working directory for this codespace |
idle_timeout_minutes | no |
Time in minutes before codespace stops from inactivity |
display_name | no |
Display name for this codespace |
retention_period_minutes | no |
Duration in minutes after codespace has gone idle in which it will be deleted. Must be integer minutes between 0 and 43200 (30 days). |
See also: GitHub Developer Guide documentation.
Delete a codespace for the authenticated user
Deletes a user's codespace.
OAuth app tokens and personal access tokens (classic) need the codespace
scope to use this endpoint.
octokit.rest.codespaces.deleteForAuthenticatedUser({
codespace_name,
});
Parameters
name | required | description |
---|---|---|
codespace_name | yes |
The name of the codespace. |
See also: GitHub Developer Guide documentation.
Delete a codespace from the organization
Deletes a user's codespace.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.codespaces.deleteFromOrganization({
org,
username,
codespace_name,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
username | yes |
The handle for the GitHub user account. |
codespace_name | yes |
The name of the codespace. |
See also: GitHub Developer Guide documentation.
Delete an organization secret
Deletes an organization development environment secret using the secret name.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.codespaces.deleteOrgSecret({
org,
secret_name,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
secret_name | yes |
The name of the secret. |
See also: GitHub Developer Guide documentation.
Delete a repository secret
Deletes a development environment secret in a repository using the secret name.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.codespaces.deleteRepoSecret({
owner,
repo,
secret_name,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
secret_name | yes |
The name of the secret. |
See also: GitHub Developer Guide documentation.
Delete a secret for the authenticated user
Deletes a development environment secret from a user's codespaces using the secret name. Deleting the secret will remove access from all codespaces that were allowed to access the secret.
The authenticated user must have Codespaces access to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the codespace
or codespace:secrets
scope to use this endpoint.
octokit.rest.codespaces.deleteSecretForAuthenticatedUser({
secret_name,
});
Parameters
name | required | description |
---|---|---|
secret_name | yes |
The name of the secret. |
See also: GitHub Developer Guide documentation.
Export a codespace for the authenticated user
Triggers an export of the specified codespace and returns a URL and ID where the status of the export can be monitored.
If changes cannot be pushed to the codespace's repository, they will be pushed to a new or previously-existing fork instead.
OAuth app tokens and personal access tokens (classic) need the codespace
scope to use this endpoint.
octokit.rest.codespaces.exportForAuthenticatedUser({
codespace_name,
});
Parameters
name | required | description |
---|---|---|
codespace_name | yes |
The name of the codespace. |
See also: GitHub Developer Guide documentation.
List codespaces for a user in organization
Lists the codespaces that a member of an organization has for repositories in that organization.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.codespaces.getCodespacesForUserInOrg({
org,
username,
});
Parameters
name | required | description |
---|---|---|
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
org | yes |
The organization name. The name is not case sensitive. |
username | yes |
The handle for the GitHub user account. |
See also: GitHub Developer Guide documentation.
Get details about a codespace export
Gets information about an export of a codespace.
OAuth app tokens and personal access tokens (classic) need the codespace
scope to use this endpoint.
octokit.rest.codespaces.getExportDetailsForAuthenticatedUser({
codespace_name,
export_id,
});
Parameters
name | required | description |
---|---|---|
codespace_name | yes |
The name of the codespace. |
export_id | yes |
The ID of the export operation, or |
See also: GitHub Developer Guide documentation.
Get a codespace for the authenticated user
Gets information about a user's codespace.
OAuth app tokens and personal access tokens (classic) need the codespace
scope to use this endpoint.
octokit.rest.codespaces.getForAuthenticatedUser({
codespace_name,
});
Parameters
name | required | description |
---|---|---|
codespace_name | yes |
The name of the codespace. |
See also: GitHub Developer Guide documentation.
Get an organization public key
Gets a public key for an organization, which is required in order to encrypt secrets. You need to encrypt the value of a secret before you can create or update secrets.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.codespaces.getOrgPublicKey({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
See also: GitHub Developer Guide documentation.
Get an organization secret
Gets an organization development environment secret without revealing its encrypted value.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.codespaces.getOrgSecret({
org,
secret_name,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
secret_name | yes |
The name of the secret. |
See also: GitHub Developer Guide documentation.
Get public key for the authenticated user
Gets your public key, which you need to encrypt secrets. You need to encrypt a secret before you can create or update secrets.
The authenticated user must have Codespaces access to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the codespace
or codespace:secrets
scope to use this endpoint.
octokit.rest.codespaces.getPublicKeyForAuthenticatedUser();
Parameters
This endpoint has no parameters
See also: GitHub Developer Guide documentation.
Get a repository public key
Gets your public key, which you need to encrypt secrets. You need to encrypt a secret before you can create or update secrets.
Anyone with read access to the repository can use this endpoint.
If the repository is private, OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.codespaces.getRepoPublicKey({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Get a repository secret
Gets a single repository development environment secret without revealing its encrypted value.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.codespaces.getRepoSecret({
owner,
repo,
secret_name,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
secret_name | yes |
The name of the secret. |
See also: GitHub Developer Guide documentation.
Get a secret for the authenticated user
Gets a development environment secret available to a user's codespaces without revealing its encrypted value.
The authenticated user must have Codespaces access to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the codespace
or codespace:secrets
scope to use this endpoint.
octokit.rest.codespaces.getSecretForAuthenticatedUser({
secret_name,
});
Parameters
name | required | description |
---|---|---|
secret_name | yes |
The name of the secret. |
See also: GitHub Developer Guide documentation.
List devcontainer configurations in a repository for the authenticated user
Lists the devcontainer.json files associated with a specified repository and the authenticated user. These files specify launchpoint configurations for codespaces created within the repository.
OAuth app tokens and personal access tokens (classic) need the codespace
scope to use this endpoint.
octokit.rest.codespaces.listDevcontainersInRepositoryForAuthenticatedUser({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
List codespaces for the authenticated user
Lists the authenticated user's codespaces.
OAuth app tokens and personal access tokens (classic) need the codespace
scope to use this endpoint.
octokit.rest.codespaces.listForAuthenticatedUser();
Parameters
name | required | description |
---|---|---|
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
repository_id | no |
ID of the Repository to filter on |
See also: GitHub Developer Guide documentation.
List codespaces for the organization
Lists the codespaces associated to a specified organization.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.codespaces.listInOrganization({
org,
});
Parameters
name | required | description |
---|---|---|
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
org | yes |
The organization name. The name is not case sensitive. |
org_id | no |
The organization name. The name is not case sensitive. |
See also: GitHub Developer Guide documentation.
List codespaces in a repository for the authenticated user
Lists the codespaces associated to a specified repository and the authenticated user.
OAuth app tokens and personal access tokens (classic) need the codespace
scope to use this endpoint.
octokit.rest.codespaces.listInRepositoryForAuthenticatedUser({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
List organization secrets
Lists all Codespaces development environment secrets available at the organization-level without revealing their encrypted values.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.codespaces.listOrgSecrets({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List repository secrets
Lists all development environment secrets available in a repository without revealing their encrypted values.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.codespaces.listRepoSecrets({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List selected repositories for a user secret
List the repositories that have been granted the ability to use a user's development environment secret.
The authenticated user must have Codespaces access to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the codespace
or codespace:secrets
scope to use this endpoint.
octokit.rest.codespaces.listRepositoriesForSecretForAuthenticatedUser({
secret_name,
});
Parameters
name | required | description |
---|---|---|
secret_name | yes |
The name of the secret. |
See also: GitHub Developer Guide documentation.
List secrets for the authenticated user
Lists all development environment secrets available for a user's codespaces without revealing their encrypted values.
The authenticated user must have Codespaces access to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the codespace
or codespace:secrets
scope to use this endpoint.
octokit.rest.codespaces.listSecretsForAuthenticatedUser();
Parameters
name | required | description |
---|---|---|
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List selected repositories for an organization secret
Lists all repositories that have been selected when the visibility
for repository access to a secret is set to selected
.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.codespaces.listSelectedReposForOrgSecret({
org,
secret_name,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
secret_name | yes |
The name of the secret. |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
Get default attributes for a codespace
Gets the default attributes for codespaces created by the user with the repository.
OAuth app tokens and personal access tokens (classic) need the codespace
scope to use this endpoint.
octokit.rest.codespaces.preFlightWithRepoForAuthenticatedUser({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
ref | no |
The branch or commit to check for a default devcontainer path. If not specified, the default branch will be checked. |
client_ip | no |
An alternative IP for default location auto-detection, such as when proxying a request. |
See also: GitHub Developer Guide documentation.
Create a repository from an unpublished codespace
Publishes an unpublished codespace, creating a new repository and assigning it to the codespace.
The codespace's token is granted write permissions to the repository, allowing the user to push their changes.
This will fail for a codespace that is already published, meaning it has an associated repository.
OAuth app tokens and personal access tokens (classic) need the codespace
scope to use this endpoint.
octokit.rest.codespaces.publishForAuthenticatedUser({
codespace_name,
});
Parameters
name | required | description |
---|---|---|
codespace_name | yes |
The name of the codespace. |
name | no |
A name for the new repository. |
private | no |
Whether the new repository should be private. |
See also: GitHub Developer Guide documentation.
Remove a selected repository from a user secret
Removes a repository from the selected repositories for a user's development environment secret.
The authenticated user must have Codespaces access to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the codespace
or codespace:secrets
scope to use this endpoint.
octokit.rest.codespaces.removeRepositoryForSecretForAuthenticatedUser({
secret_name,
repository_id,
});
Parameters
name | required | description |
---|---|---|
secret_name | yes |
The name of the secret. |
repository_id | yes |
See also: GitHub Developer Guide documentation.
Remove selected repository from an organization secret
Removes a repository from an organization development environment secret when the visibility
for repository access is set to selected
. The visibility is set when you Create
or update an organization secret.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.codespaces.removeSelectedRepoFromOrgSecret({
org,
secret_name,
repository_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
secret_name | yes |
The name of the secret. |
repository_id | yes |
See also: GitHub Developer Guide documentation.
List available machine types for a repository
List the machine types available for a given repository based on its configuration.
OAuth app tokens and personal access tokens (classic) need the codespace
scope to use this endpoint.
octokit.rest.codespaces.repoMachinesForAuthenticatedUser({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
location | no |
The location to check for available machines. Assigned by IP if not provided. |
client_ip | no |
IP for location auto-detection when proxying a request |
ref | no |
The branch or commit to check for prebuild availability and devcontainer restrictions. |
See also: GitHub Developer Guide documentation.
Set selected repositories for a user secret
Select the repositories that will use a user's development environment secret.
The authenticated user must have Codespaces access to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the codespace
or codespace:secrets
scope to use this endpoint.
octokit.rest.codespaces.setRepositoriesForSecretForAuthenticatedUser({
secret_name,
selected_repository_ids,
});
Parameters
name | required | description |
---|---|---|
secret_name | yes |
The name of the secret. |
selected_repository_ids | yes |
An array of repository ids for which a codespace can access the secret. You can manage the list of selected repositories using the List selected repositories for a user secret, Add a selected repository to a user secret, and Remove a selected repository from a user secret endpoints. |
See also: GitHub Developer Guide documentation.
Set selected repositories for an organization secret
Replaces all repositories for an organization development environment secret when the visibility
for repository access is set to selected
. The visibility is set when you Create
or update an organization secret.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.codespaces.setSelectedReposForOrgSecret({
org,
secret_name,
selected_repository_ids,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
secret_name | yes |
The name of the secret. |
selected_repository_ids | yes |
An array of repository ids that can access the organization secret. You can only provide a list of repository ids when the |
See also: GitHub Developer Guide documentation.
Start a codespace for the authenticated user
Starts a user's codespace.
OAuth app tokens and personal access tokens (classic) need the codespace
scope to use this endpoint.
octokit.rest.codespaces.startForAuthenticatedUser({
codespace_name,
});
Parameters
name | required | description |
---|---|---|
codespace_name | yes |
The name of the codespace. |
See also: GitHub Developer Guide documentation.
Stop a codespace for the authenticated user
Stops a user's codespace.
OAuth app tokens and personal access tokens (classic) need the codespace
scope to use this endpoint.
octokit.rest.codespaces.stopForAuthenticatedUser({
codespace_name,
});
Parameters
name | required | description |
---|---|---|
codespace_name | yes |
The name of the codespace. |
See also: GitHub Developer Guide documentation.
Stop a codespace for an organization user
Stops a user's codespace.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.codespaces.stopInOrganization({
org,
username,
codespace_name,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
username | yes |
The handle for the GitHub user account. |
codespace_name | yes |
The name of the codespace. |
See also: GitHub Developer Guide documentation.
Update a codespace for the authenticated user
Updates a codespace owned by the authenticated user. Currently only the codespace's machine type and recent folders can be modified using this endpoint.
If you specify a new machine type it will be applied the next time your codespace is started.
OAuth app tokens and personal access tokens (classic) need the codespace
scope to use this endpoint.
octokit.rest.codespaces.updateForAuthenticatedUser({
codespace_name,
});
Parameters
name | required | description |
---|---|---|
codespace_name | yes |
The name of the codespace. |
machine | no |
A valid machine to transition this codespace to. |
display_name | no |
Display name for this codespace |
recent_folders | no |
Recently opened folders inside the codespace. It is currently used by the clients to determine the folder path to load the codespace in. |
See also: GitHub Developer Guide documentation.
Copilot
Add teams to the Copilot subscription for an organization
Note: This endpoint is in beta and is subject to change.
Purchases a GitHub Copilot seat for all users within each specified team. The organization will be billed accordingly. For more information about Copilot pricing, see "Pricing for GitHub Copilot".
Only organization owners can configure GitHub Copilot in their organization.
In order for an admin to use this endpoint, the organization must have a Copilot Business or Enterprise subscription and a configured suggestion matching policy. For more information about setting up a Copilot subscription, see "Setting up a Copilot subscription for your organization". For more information about setting a suggestion matching policy, see "Configuring suggestion matching policies for GitHub Copilot in your organization".
OAuth app tokens and personal access tokens (classic) need the manage_billing:copilot
scope to use this endpoint.
octokit.rest.copilot.addCopilotSeatsForTeams({
org,
selected_teams,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
selected_teams | yes |
List of team names within the organization to which to grant access to GitHub Copilot. |
See also: GitHub Developer Guide documentation.
Add users to the Copilot subscription for an organization
Note: This endpoint is in beta and is subject to change.
Purchases a GitHub Copilot seat for each user specified. The organization will be billed accordingly. For more information about Copilot pricing, see "Pricing for GitHub Copilot".
Only organization owners can configure GitHub Copilot in their organization.
In order for an admin to use this endpoint, the organization must have a Copilot Business or Enterprise subscription and a configured suggestion matching policy. For more information about setting up a Copilot subscription, see "Setting up a Copilot subscription for your organization". For more information about setting a suggestion matching policy, see "Configuring suggestion matching policies for GitHub Copilot in your organization".
OAuth app tokens and personal access tokens (classic) need the manage_billing:copilot
scope to use this endpoint.
octokit.rest.copilot.addCopilotSeatsForUsers({
org,
selected_usernames,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
selected_usernames | yes |
The usernames of the organization members to be granted access to GitHub Copilot. |
See also: GitHub Developer Guide documentation.
Remove teams from the Copilot subscription for an organization
Note: This endpoint is in beta and is subject to change.
Cancels the Copilot seat assignment for all members of each team specified. This will cause the members of the specified team(s) to lose access to GitHub Copilot at the end of the current billing cycle, and the organization will not be billed further for those users.
For more information about Copilot pricing, see "Pricing for GitHub Copilot".
For more information about disabling access to Copilot Business or Enterprise, see "Revoking access to GitHub Copilot for specific users in your organization".
Only organization owners can configure GitHub Copilot in their organization.
OAuth app tokens and personal access tokens (classic) need the manage_billing:copilot
scope to use this endpoint.
octokit.rest.copilot.cancelCopilotSeatAssignmentForTeams({
org,
selected_teams,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
selected_teams | yes |
The names of teams from which to revoke access to GitHub Copilot. |
See also: GitHub Developer Guide documentation.
Remove users from the Copilot subscription for an organization
Note: This endpoint is in beta and is subject to change.
Cancels the Copilot seat assignment for each user specified. This will cause the specified users to lose access to GitHub Copilot at the end of the current billing cycle, and the organization will not be billed further for those users.
For more information about Copilot pricing, see "Pricing for GitHub Copilot".
For more information about disabling access to Copilot Business or Enterprise, see "Revoking access to GitHub Copilot for specific users in your organization".
Only organization owners can configure GitHub Copilot in their organization.
OAuth app tokens and personal access tokens (classic) need the manage_billing:copilot
scope to use this endpoint.
octokit.rest.copilot.cancelCopilotSeatAssignmentForUsers({
org,
selected_usernames,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
selected_usernames | yes |
The usernames of the organization members for which to revoke access to GitHub Copilot. |
See also: GitHub Developer Guide documentation.
Get Copilot seat information and settings for an organization
Note: This endpoint is in beta and is subject to change.
Gets information about an organization's Copilot subscription, including seat breakdown and code matching policies. To configure these settings, go to your organization's settings on GitHub.com. For more information, see "Managing policies for Copilot in your organization".
Only organization owners can configure and view details about the organization's Copilot Business subscription.
OAuth app tokens and personal access tokens (classic) need the manage_billing:copilot
scope to use this endpoint.
octokit.rest.copilot.getCopilotOrganizationDetails({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
See also: GitHub Developer Guide documentation.
Get Copilot seat assignment details for a user
Note: This endpoint is in beta and is subject to change.
Gets the GitHub Copilot seat assignment details for a member of an organization who currently has access to GitHub Copilot.
Organization owners can view GitHub Copilot seat assignment details for members in their organization.
OAuth app tokens and personal access tokens (classic) need the manage_billing:copilot
scope to use this endpoint.
octokit.rest.copilot.getCopilotSeatDetailsForUser({
org,
username,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
username | yes |
The handle for the GitHub user account. |
See also: GitHub Developer Guide documentation.
List all Copilot seat assignments for an organization
Note: This endpoint is in beta and is subject to change.
Lists all Copilot seat assignments for an organization that are currently being billed (either active or pending cancellation at the start of the next billing cycle).
Only organization owners can configure and view details about the organization's Copilot Business or Enterprise subscription.
OAuth app tokens and personal access tokens (classic) need the manage_billing:copilot
scope to use this endpoint.
octokit.rest.copilot.listCopilotSeats({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
Get a summary of Copilot usage for enterprise members
Note: This endpoint is in beta and is subject to change.
You can use this endpoint to see a daily breakdown of aggregated usage metrics for Copilot completions and Copilot Chat in the IDE for all users across organizations with access to Copilot within your enterprise, with a further breakdown of suggestions, acceptances, and number of active users by editor and language for each day. See the response schema tab for detailed metrics definitions.
The response contains metrics for the prior 28 days. Usage metrics are processed once per day for the previous day, and the response will only include data up until yesterday. In order for an end user to be counted towards these metrics, they must have telemetry enabled in their IDE.
Only the owners and billing managers of enterprises with a Copilot Business or Enterprise subscription can view Copilot usage metrics for the enterprise.
OAuth app tokens and personal access tokens (classic) need the copilot
, manage_billing:copilot
, admin:enterprise
, or manage_billing:enterprise
scope to use this endpoint.
octokit.rest.copilot.usageMetricsForEnterprise({
enterprise,
});
Parameters
name | required | description |
---|---|---|
enterprise | yes |
The slug version of the enterprise name. You can also substitute this value with the enterprise id. |
since | no |
Show usage metrics since this date. This is a timestamp in ISO 8601 format ( |
until | no |
Show usage metrics until this date. This is a timestamp in ISO 8601 format ( |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
per_page | no |
The number of days of metrics to display per page (max 28). For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
Get a summary of Copilot usage for organization members
Note: This endpoint is in beta and is subject to change.
You can use this endpoint to see a daily breakdown of aggregated usage metrics for Copilot completions and Copilot Chat in the IDE across an organization, with a further breakdown of suggestions, acceptances, and number of active users by editor and language for each day. See the response schema tab for detailed metrics definitions.
The response contains metrics for the prior 28 days. Usage metrics are processed once per day for the previous day, and the response will only include data up until yesterday. In order for an end user to be counted towards these metrics, they must have telemetry enabled in their IDE.
Copilot Business or Copilot Enterprise organization owners, and owners and billing managers of their parent enterprises, can view Copilot usage metrics.
OAuth app tokens and personal access tokens (classic) need the copilot
, manage_billing:copilot
, admin:org
, admin:enterprise
, or manage_billing:enterprise
scope to use this endpoint.
octokit.rest.copilot.usageMetricsForOrg({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
since | no |
Show usage metrics since this date. This is a timestamp in ISO 8601 format ( |
until | no |
Show usage metrics until this date. This is a timestamp in ISO 8601 format ( |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
per_page | no |
The number of days of metrics to display per page (max 28). For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
Get a summary of Copilot usage for a team
Note: This endpoint is in beta and is subject to change.
You can use this endpoint to see a daily breakdown of aggregated usage metrics for Copilot completions and Copilot Chat in the IDE for users within a team, with a further breakdown of suggestions, acceptances, and number of active users by editor and language for each day. See the response schema tab for detailed metrics definitions.
The response contains metrics for the prior 28 days. Usage metrics are processed once per day for the previous day, and the response will only include data up until yesterday. In order for an end user to be counted towards these metrics, they must have telemetry enabled in their IDE.
Note: This endpoint will only return results for a given day if the team had five or more members on that day.
Copilot Business or Copilot Enterprise organization owners for the organization that contains this team, and owners and billing managers of their parent enterprises, can view Copilot usage metrics for a team.
OAuth app tokens and personal access tokens (classic) need the copilot
, manage_billing:copilot
, admin:org
, admin:enterprise
, or manage_billing:enterprise
scope to use this endpoint.
octokit.rest.copilot.usageMetricsForTeam({
org,
team_slug,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
team_slug | yes |
The slug of the team name. |
since | no |
Show usage metrics since this date. This is a timestamp in ISO 8601 format ( |
until | no |
Show usage metrics until this date. This is a timestamp in ISO 8601 format ( |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
per_page | no |
The number of days of metrics to display per page (max 28). For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
Dependabot
Add selected repository to an organization secret
Adds a repository to an organization secret when the visibility
for
repository access is set to selected
. The visibility is set when you Create or
update an organization secret.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.dependabot.addSelectedRepoToOrgSecret({
org,
secret_name,
repository_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
secret_name | yes |
The name of the secret. |
repository_id | yes |
See also: GitHub Developer Guide documentation.
Create or update an organization secret
Creates or updates an organization secret with an encrypted value. Encrypt your secret using
LibSodium. You must authenticate using an access
token with the admin:org
scope to use this endpoint. GitHub Apps must have the dependabot_secrets
organization
permission to use this endpoint.
Example encrypting a secret using Node.js
Encrypt your secret using the tweetsodium library.
const sodium = require('tweetsodium');
const key = "base64-encoded-public-key";
const value = "plain-text-secret";
// Convert the message and key to Uint8Array's (Buffer implements that interface)
const messageBytes = Buffer.from(value);
const keyBytes = Buffer.from(key, 'base64');
// Encrypt using LibSodium.
const encryptedBytes = sodium.seal(messageBytes, keyBytes);
// Base64 the encrypted secret
const encrypted = Buffer.from(encryptedBytes).toString('base64');
console.log(encrypted);
Example encrypting a secret using Python
Encrypt your secret using pynacl with Python 3.
from base64 import b64encode
from nacl import encoding, public
def encrypt(public_key: str, secret_value: str) -> str:
"""Encrypt a Unicode string using the public key."""
public_key = public.PublicKey(public_key.encode("utf-8"), encoding.Base64Encoder())
sealed_box = public.SealedBox(public_key)
encrypted = sealed_box.encrypt(secret_value.encode("utf-8"))
return b64encode(encrypted).decode("utf-8")
Example encrypting a secret using C#
Encrypt your secret using the Sodium.Core package.
var secretValue = System.Text.Encoding.UTF8.GetBytes("mySecret");
var publicKey = Convert.FromBase64String("2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvvcCU=");
var sealedPublicKeyBox = Sodium.SealedPublicKeyBox.Create(secretValue, publicKey);
Console.WriteLine(Convert.ToBase64String(sealedPublicKeyBox));
Example encrypting a secret using Ruby
Encrypt your secret using the rbnacl gem.
require "rbnacl"
require "base64"
key = Base64.decode64("+ZYvJDZMHUfBkJdyq5Zm9SKqeuBQ4sj+6sfjlH4CgG0=")
public_key = RbNaCl::PublicKey.new(key)
box = RbNaCl::Boxes::Sealed.from_public_key(public_key)
encrypted_secret = box.encrypt("my_secret")
# Print the base64 encoded secret
puts Base64.strict_encode64(encrypted_secret)
octokit.rest.dependabot.createOrUpdateOrgSecret({
org,
secret_name,
visibility,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
secret_name | yes |
The name of the secret. |
encrypted_value | no |
Value for your secret, encrypted with LibSodium using the public key retrieved from the Get an organization public key endpoint. |
key_id | no |
ID of the key you used to encrypt the secret. |
visibility | yes |
Which type of organization repositories have access to the organization secret. |
selected_repository_ids | no |
An array of repository ids that can access the organization secret. You can only provide a list of repository ids when the |
See also: GitHub Developer Guide documentation.
Create or update a repository secret
Creates or updates a repository secret with an encrypted value. Encrypt your secret using LibSodium. For more information, see "Encrypting secrets for the REST API."
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.dependabot.createOrUpdateRepoSecret({
owner,
repo,
secret_name,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
secret_name | yes |
The name of the secret. |
encrypted_value | no |
Value for your secret, encrypted with LibSodium using the public key retrieved from the Get a repository public key endpoint. |
key_id | no |
ID of the key you used to encrypt the secret. |
See also: GitHub Developer Guide documentation.
Delete an organization secret
Deletes a secret in an organization using the secret name.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.dependabot.deleteOrgSecret({
org,
secret_name,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
secret_name | yes |
The name of the secret. |
See also: GitHub Developer Guide documentation.
Delete a repository secret
Deletes a secret in a repository using the secret name.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.dependabot.deleteRepoSecret({
owner,
repo,
secret_name,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
secret_name | yes |
The name of the secret. |
See also: GitHub Developer Guide documentation.
Get a Dependabot alert
OAuth app tokens and personal access tokens (classic) need the security_events
scope to use this endpoint. If this endpoint is only used with public repositories, the token can use the public_repo
scope instead.
octokit.rest.dependabot.getAlert({
owner,
repo,
alert_number,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
alert_number | yes |
The number that identifies a Dependabot alert in its repository.
You can find this at the end of the URL for a Dependabot alert within GitHub,
or in |
See also: GitHub Developer Guide documentation.
Get an organization public key
Gets your public key, which you need to encrypt secrets. You need to encrypt a secret before you can create or update secrets.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.dependabot.getOrgPublicKey({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
See also: GitHub Developer Guide documentation.
Get an organization secret
Gets a single organization secret without revealing its encrypted value.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.dependabot.getOrgSecret({
org,
secret_name,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
secret_name | yes |
The name of the secret. |
See also: GitHub Developer Guide documentation.
Get a repository public key
Gets your public key, which you need to encrypt secrets. You need to encrypt a secret before you can create or update secrets. Anyone with read access to the repository can use this endpoint.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint if the repository is private.
octokit.rest.dependabot.getRepoPublicKey({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Get a repository secret
Gets a single repository secret without revealing its encrypted value.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.dependabot.getRepoSecret({
owner,
repo,
secret_name,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
secret_name | yes |
The name of the secret. |
See also: GitHub Developer Guide documentation.
List Dependabot alerts for an enterprise
Lists Dependabot alerts for repositories that are owned by the specified enterprise.
The authenticated user must be a member of the enterprise to use this endpoint.
Alerts are only returned for organizations in the enterprise for which you are an organization owner or a security manager. For more information about security managers, see "Managing security managers in your organization."
OAuth app tokens and personal access tokens (classic) need the repo
or security_events
scope to use this endpoint.
octokit.rest.dependabot.listAlertsForEnterprise({
enterprise,
});
Parameters
name | required | description |
---|---|---|
enterprise | yes |
The slug version of the enterprise name. You can also substitute this value with the enterprise id. |
state | no |
A comma-separated list of states. If specified, only alerts with these states will be returned. Can be: |
severity | no |
A comma-separated list of severities. If specified, only alerts with these severities will be returned. Can be: |
ecosystem | no |
A comma-separated list of ecosystems. If specified, only alerts for these ecosystems will be returned. Can be: |
package | no |
A comma-separated list of package names. If specified, only alerts for these packages will be returned. |
scope | no |
The scope of the vulnerable dependency. If specified, only alerts with this scope will be returned. |
sort | no |
The property by which to sort the results.
|
direction | no |
The direction to sort the results by. |
before | no |
A cursor, as given in the Link header. If specified, the query only searches for results before this cursor. For more information, see "Using pagination in the REST API." |
after | no |
A cursor, as given in the Link header. If specified, the query only searches for results after this cursor. For more information, see "Using pagination in the REST API." |
first | no |
Deprecated. The number of results per page (max 100), starting from the first matching result.
This parameter must not be used in combination with |
last | no |
Deprecated. The number of results per page (max 100), starting from the last matching result.
This parameter must not be used in combination with |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List Dependabot alerts for an organization
Lists Dependabot alerts for an organization.
The authenticated user must be an owner or security manager for the organization to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the security_events
scope to use this endpoint. If this endpoint is only used with public repositories, the token can use the public_repo
scope instead.
octokit.rest.dependabot.listAlertsForOrg({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
state | no |
A comma-separated list of states. If specified, only alerts with these states will be returned. Can be: |
severity | no |
A comma-separated list of severities. If specified, only alerts with these severities will be returned. Can be: |
ecosystem | no |
A comma-separated list of ecosystems. If specified, only alerts for these ecosystems will be returned. Can be: |
package | no |
A comma-separated list of package names. If specified, only alerts for these packages will be returned. |
scope | no |
The scope of the vulnerable dependency. If specified, only alerts with this scope will be returned. |
sort | no |
The property by which to sort the results.
|
direction | no |
The direction to sort the results by. |
before | no |
A cursor, as given in the Link header. If specified, the query only searches for results before this cursor. For more information, see "Using pagination in the REST API." |
after | no |
A cursor, as given in the Link header. If specified, the query only searches for results after this cursor. For more information, see "Using pagination in the REST API." |
first | no |
Deprecated. The number of results per page (max 100), starting from the first matching result.
This parameter must not be used in combination with |
last | no |
Deprecated. The number of results per page (max 100), starting from the last matching result.
This parameter must not be used in combination with |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List Dependabot alerts for a repository
OAuth app tokens and personal access tokens (classic) need the security_events
scope to use this endpoint. If this endpoint is only used with public repositories, the token can use the public_repo
scope instead.
octokit.rest.dependabot.listAlertsForRepo({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
state | no |
A comma-separated list of states. If specified, only alerts with these states will be returned. Can be: |
severity | no |
A comma-separated list of severities. If specified, only alerts with these severities will be returned. Can be: |
ecosystem | no |
A comma-separated list of ecosystems. If specified, only alerts for these ecosystems will be returned. Can be: |
package | no |
A comma-separated list of package names. If specified, only alerts for these packages will be returned. |
manifest | no |
A comma-separated list of full manifest paths. If specified, only alerts for these manifests will be returned. |
scope | no |
The scope of the vulnerable dependency. If specified, only alerts with this scope will be returned. |
sort | no |
The property by which to sort the results.
|
direction | no |
The direction to sort the results by. |
page | no |
Deprecated. Page number of the results to fetch. Use cursor-based pagination with |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
before | no |
A cursor, as given in the Link header. If specified, the query only searches for results before this cursor. For more information, see "Using pagination in the REST API." |
after | no |
A cursor, as given in the Link header. If specified, the query only searches for results after this cursor. For more information, see "Using pagination in the REST API." |
first | no |
Deprecated. The number of results per page (max 100), starting from the first matching result.
This parameter must not be used in combination with |
last | no |
Deprecated. The number of results per page (max 100), starting from the last matching result.
This parameter must not be used in combination with |
See also: GitHub Developer Guide documentation.
List organization secrets
Lists all secrets available in an organization without revealing their encrypted values.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.dependabot.listOrgSecrets({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List repository secrets
Lists all secrets available in a repository without revealing their encrypted values.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.dependabot.listRepoSecrets({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List selected repositories for an organization secret
Lists all repositories that have been selected when the visibility
for repository access to a secret is set to selected
.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.dependabot.listSelectedReposForOrgSecret({
org,
secret_name,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
secret_name | yes |
The name of the secret. |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
Remove selected repository from an organization secret
Removes a repository from an organization secret when the visibility
for repository access is set to selected
. The visibility is set when you Create
or update an organization secret.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.dependabot.removeSelectedRepoFromOrgSecret({
org,
secret_name,
repository_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
secret_name | yes |
The name of the secret. |
repository_id | yes |
See also: GitHub Developer Guide documentation.
Set selected repositories for an organization secret
Replaces all repositories for an organization secret when the visibility
for repository access is set to selected
. The visibility is set when you Create
or update an organization secret.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.dependabot.setSelectedReposForOrgSecret({
org,
secret_name,
selected_repository_ids,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
secret_name | yes |
The name of the secret. |
selected_repository_ids | yes |
An array of repository ids that can access the organization secret. You can only provide a list of repository ids when the |
See also: GitHub Developer Guide documentation.
Update a Dependabot alert
The authenticated user must have access to security alerts for the repository to use this endpoint. For more information, see "Granting access to security alerts."
OAuth app tokens and personal access tokens (classic) need the security_events
scope to use this endpoint. If this endpoint is only used with public repositories, the token can use the public_repo
scope instead.
octokit.rest.dependabot.updateAlert({
owner,
repo,
alert_number,
state,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
alert_number | yes |
The number that identifies a Dependabot alert in its repository.
You can find this at the end of the URL for a Dependabot alert within GitHub,
or in |
state | yes |
The state of the Dependabot alert.
A |
dismissed_reason | no |
Required when |
dismissed_comment | no |
An optional comment associated with dismissing the alert. |
See also: GitHub Developer Guide documentation.
Dependency-Graph
Create a snapshot of dependencies for a repository
Create a new snapshot of a repository's dependencies.
The authenticated user must have access to the repository.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.dependencyGraph.createRepositorySnapshot({
owner,
repo,
version,
job,
job.id,
job.correlator,
sha,
ref,
detector,
detector.name,
detector.version,
detector.url,
manifests.*.name,
scanned
})
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
version | yes |
The version of the repository snapshot submission. |
job | yes | |
job.id | yes |
The external ID of the job. |
job.correlator | yes |
Correlator provides a key that is used to group snapshots submitted over time. Only the "latest" submitted snapshot for a given combination of |
job.html_url | no |
The url for the job. |
sha | yes |
The commit SHA associated with this dependency snapshot. Maximum length: 40 characters. |
ref | yes |
The repository branch that triggered this snapshot. |
detector | yes |
A description of the detector used. |
detector.name | yes |
The name of the detector used. |
detector.version | yes |
The version of the detector used. |
detector.url | yes |
The url of the detector used. |
metadata | no |
User-defined metadata to store domain-specific information limited to 8 keys with scalar values. |
metadata.* | no | |
manifests | no |
A collection of package manifests, which are a collection of related dependencies declared in a file or representing a logical group of dependencies. |
manifests.* | no | |
manifests.*.name | yes |
The name of the manifest. |
manifests.*.file | no | |
manifests.*.file.source_location | no |
The path of the manifest file relative to the root of the Git repository. |
manifests.*.metadata | no |
User-defined metadata to store domain-specific information limited to 8 keys with scalar values. |
manifests.*.metadata.* | no | |
manifests.*.resolved | no |
A collection of resolved package dependencies. |
manifests.*.resolved.* | no | |
manifests.*.resolved.*.package_url | no |
Package-url (PURL) of dependency. See https://github.com/package-url/purl-spec for more details. |
manifests.*.resolved.*.metadata | no |
User-defined metadata to store domain-specific information limited to 8 keys with scalar values. |
manifests.*.resolved.*.metadata.* | no | |
manifests.*.resolved.*.relationship | no |
A notation of whether a dependency is requested directly by this manifest or is a dependency of another dependency. |
manifests.*.resolved.*.scope | no |
A notation of whether the dependency is required for the primary build artifact (runtime) or is only used for development. Future versions of this specification may allow for more granular scopes. |
manifests.*.resolved.*.dependencies | no |
Array of package-url (PURLs) of direct child dependencies. |
scanned | yes |
The time at which the snapshot was scanned. |
See also: GitHub Developer Guide documentation.
Get a diff of the dependencies between commits
Gets the diff of the dependency changes between two commits of a repository, based on the changes to the dependency manifests made in those commits.
octokit.rest.dependencyGraph.diffRange({
owner,
repo,
basehead,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
basehead | yes |
The base and head Git revisions to compare. The Git revisions will be resolved to commit SHAs. Named revisions will be resolved to their corresponding HEAD commits, and an appropriate merge base will be determined. This parameter expects the format |
name | no |
The full path, relative to the repository root, of the dependency manifest file. |
See also: GitHub Developer Guide documentation.
Export a software bill of materials (SBOM) for a repository.
Exports the software bill of materials (SBOM) for a repository in SPDX JSON format.
octokit.rest.dependencyGraph.exportSbom({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Emojis
Get emojis
Lists all the emojis available to use on GitHub.
octokit.rest.emojis.get();
Parameters
This endpoint has no parameters
See also: GitHub Developer Guide documentation.
Gists
Check if a gist is starred
octokit.rest.gists.checkIsStarred({
gist_id,
});
Parameters
name | required | description |
---|---|---|
gist_id | yes |
The unique identifier of the gist. |
See also: GitHub Developer Guide documentation.
Create a gist
Allows you to add a new gist with one or more files.
Note: Don't name your files "gistfile" with a numerical suffix. This is the format of the automatic naming scheme that Gist uses internally.
octokit.rest.gists.create({
files,
files.*.content
})
Parameters
name | required | description |
---|---|---|
description | no |
Description of the gist |
files | yes |
Names and content for the files that make up the gist |
files.* | no | |
files.*.content | yes |
Content of the file |
public | no |
See also: GitHub Developer Guide documentation.
Create a gist comment
Creates a comment on a gist.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github.raw+json
: Returns the raw markdown. This is the default if you do not pass any specific media type.application/vnd.github.base64+json
: Returns the base64-encoded contents. This can be useful if your gist contains any invalid UTF-8 sequences.
octokit.rest.gists.createComment({
gist_id,
body,
});
Parameters
name | required | description |
---|---|---|
gist_id | yes |
The unique identifier of the gist. |
body | yes |
The comment text. |
See also: GitHub Developer Guide documentation.
Delete a gist
octokit.rest.gists.delete({
gist_id,
});
Parameters
name | required | description |
---|---|---|
gist_id | yes |
The unique identifier of the gist. |
See also: GitHub Developer Guide documentation.
Delete a gist comment
octokit.rest.gists.deleteComment({
gist_id,
comment_id,
});
Parameters
name | required | description |
---|---|---|
gist_id | yes |
The unique identifier of the gist. |
comment_id | yes |
The unique identifier of the comment. |
See also: GitHub Developer Guide documentation.
Fork a gist
octokit.rest.gists.fork({
gist_id,
});
Parameters
name | required | description |
---|---|---|
gist_id | yes |
The unique identifier of the gist. |
See also: GitHub Developer Guide documentation.
Get a gist
Gets a specified gist.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github.raw+json
: Returns the raw markdown. This is the default if you do not pass any specific media type.application/vnd.github.base64+json
: Returns the base64-encoded contents. This can be useful if your gist contains any invalid UTF-8 sequences.
octokit.rest.gists.get({
gist_id,
});
Parameters
name | required | description |
---|---|---|
gist_id | yes |
The unique identifier of the gist. |
See also: GitHub Developer Guide documentation.
Get a gist comment
Gets a comment on a gist.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github.raw+json
: Returns the raw markdown. This is the default if you do not pass any specific media type.application/vnd.github.base64+json
: Returns the base64-encoded contents. This can be useful if your gist contains any invalid UTF-8 sequences.
octokit.rest.gists.getComment({
gist_id,
comment_id,
});
Parameters
name | required | description |
---|---|---|
gist_id | yes |
The unique identifier of the gist. |
comment_id | yes |
The unique identifier of the comment. |
See also: GitHub Developer Guide documentation.
Get a gist revision
Gets a specified gist revision.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github.raw+json
: Returns the raw markdown. This is the default if you do not pass any specific media type.application/vnd.github.base64+json
: Returns the base64-encoded contents. This can be useful if your gist contains any invalid UTF-8 sequences.
octokit.rest.gists.getRevision({
gist_id,
sha,
});
Parameters
name | required | description |
---|---|---|
gist_id | yes |
The unique identifier of the gist. |
sha | yes |
See also: GitHub Developer Guide documentation.
List gists for the authenticated user
Lists the authenticated user's gists or if called anonymously, this endpoint returns all public gists:
octokit.rest.gists.list();
Parameters
name | required | description |
---|---|---|
since | no |
Only show results that were last updated after the given time. This is a timestamp in ISO 8601 format: |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List gist comments
Lists the comments on a gist.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github.raw+json
: Returns the raw markdown. This is the default if you do not pass any specific media type.application/vnd.github.base64+json
: Returns the base64-encoded contents. This can be useful if your gist contains any invalid UTF-8 sequences.
octokit.rest.gists.listComments({
gist_id,
});
Parameters
name | required | description |
---|---|---|
gist_id | yes |
The unique identifier of the gist. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List gist commits
octokit.rest.gists.listCommits({
gist_id,
});
Parameters
name | required | description |
---|---|---|
gist_id | yes |
The unique identifier of the gist. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List gists for a user
Lists public gists for the specified user:
octokit.rest.gists.listForUser({
username,
});
Parameters
name | required | description |
---|---|---|
username | yes |
The handle for the GitHub user account. |
since | no |
Only show results that were last updated after the given time. This is a timestamp in ISO 8601 format: |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List gist forks
octokit.rest.gists.listForks({
gist_id,
});
Parameters
name | required | description |
---|---|---|
gist_id | yes |
The unique identifier of the gist. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List public gists
List public gists sorted by most recently updated to least recently updated.
Note: With pagination, you can fetch up to 3000 gists. For example, you can fetch 100 pages with 30 gists per page or 30 pages with 100 gists per page.
octokit.rest.gists.listPublic();
Parameters
name | required | description |
---|---|---|
since | no |
Only show results that were last updated after the given time. This is a timestamp in ISO 8601 format: |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List starred gists
List the authenticated user's starred gists:
octokit.rest.gists.listStarred();
Parameters
name | required | description |
---|---|---|
since | no |
Only show results that were last updated after the given time. This is a timestamp in ISO 8601 format: |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
Star a gist
Note that you'll need to set Content-Length
to zero when calling out to this endpoint. For more information, see "HTTP method."
octokit.rest.gists.star({
gist_id,
});
Parameters
name | required | description |
---|---|---|
gist_id | yes |
The unique identifier of the gist. |
See also: GitHub Developer Guide documentation.
Unstar a gist
octokit.rest.gists.unstar({
gist_id,
});
Parameters
name | required | description |
---|---|---|
gist_id | yes |
The unique identifier of the gist. |
See also: GitHub Developer Guide documentation.
Update a gist
Allows you to update a gist's description and to update, delete, or rename gist files. Files from the previous version of the gist that aren't explicitly changed during an edit are unchanged.
octokit.rest.gists.update({
gist_id,
});
Parameters
name | required | description |
---|---|---|
gist_id | yes |
The unique identifier of the gist. |
description | no |
The description of the gist. |
files | no |
The gist files to be updated, renamed, or deleted. Each To delete a file, set the whole file to null. For example: |
files.* | no | |
files.*.content | no |
The new content of the file. |
files.*.filename | no |
The new filename for the file. |
See also: GitHub Developer Guide documentation.
Update a gist comment
Updates a comment on a gist.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github.raw+json
: Returns the raw markdown. This is the default if you do not pass any specific media type.application/vnd.github.base64+json
: Returns the base64-encoded contents. This can be useful if your gist contains any invalid UTF-8 sequences.
octokit.rest.gists.updateComment({
gist_id,
comment_id,
body,
});
Parameters
name | required | description |
---|---|---|
gist_id | yes |
The unique identifier of the gist. |
comment_id | yes |
The unique identifier of the comment. |
body | yes |
The comment text. |
See also: GitHub Developer Guide documentation.
Git
Create a blob
octokit.rest.git.createBlob({
owner,
repo,
content,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
content | yes |
The new blob's content. |
encoding | no |
The encoding used for |
See also: GitHub Developer Guide documentation.
Create a commit
Creates a new Git commit object.
Signature verification object
The response will include a verification
object that describes the result of verifying the commit's signature. The following fields are included in the verification
object:
Name | Type | Description |
---|---|---|
verified | boolean | Indicates whether GitHub considers the signature in this commit to be verified. |
reason | string | The reason for verified value. Possible values and their meanings are enumerated in the table below. |
signature | string | The signature that was extracted from the commit. |
payload | string | The value that was signed. |
These are the possible values for reason
in the verification
object:
Value | Description |
---|---|
expired_key | The key that made the signature is expired. |
not_signing_key | The "signing" flag is not among the usage flags in the GPG key that made the signature. |
gpgverify_error | There was an error communicating with the signature verification service. |
gpgverify_unavailable | The signature verification service is currently unavailable. |
unsigned | The object does not include a signature. |
unknown_signature_type | A non-PGP signature was found in the commit. |
no_user | No user was associated with the committer email address in the commit. |
unverified_email | The committer email address in the commit was associated with a user, but the email address is not verified on their account. |
bad_email | The committer email address in the commit is not included in the identities of the PGP key that made the signature. |
unknown_key | The key that made the signature has not been registered with any user's account. |
malformed_signature | There was an error parsing the signature. |
invalid | The signature could not be cryptographically verified using the key whose key-id was found in the signature. |
valid | None of the above errors applied, so the signature is considered to be verified. |
octokit.rest.git.createCommit({
owner,
repo,
message,
tree,
author.name,
author.email
})
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
message | yes |
The commit message |
tree | yes |
The SHA of the tree object this commit points to |
parents | no |
The SHAs of the commits that were the parents of this commit. If omitted or empty, the commit will be written as a root commit. For a single parent, an array of one SHA should be provided; for a merge commit, an array of more than one should be provided. |
author | no |
Information about the author of the commit. By default, the |
author.name | yes |
The name of the author (or committer) of the commit |
author.email | yes |
The email of the author (or committer) of the commit |
author.date | no |
Indicates when this commit was authored (or committed). This is a timestamp in ISO 8601 format: |
committer | no |
Information about the person who is making the commit. By default, |
committer.name | no |
The name of the author (or committer) of the commit |
committer.email | no |
The email of the author (or committer) of the commit |
committer.date | no |
Indicates when this commit was authored (or committed). This is a timestamp in ISO 8601 format: |
signature | no |
The PGP signature of the commit. GitHub adds the signature to the |
See also: GitHub Developer Guide documentation.
Create a reference
Creates a reference for your repository. You are unable to create new references for empty repositories, even if the commit SHA-1 hash used exists. Empty repositories are repositories without branches.
octokit.rest.git.createRef({
owner,
repo,
ref,
sha,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
ref | yes |
The name of the fully qualified reference (ie: |
sha | yes |
The SHA1 value for this reference. |
See also: GitHub Developer Guide documentation.
Create a tag object
Note that creating a tag object does not create the reference that makes a tag in Git. If you want to create an annotated tag in Git, you have to do this call to create the tag object, and then create the refs/tags/[tag]
reference. If you want to create a lightweight tag, you only have to create the tag reference - this call would be unnecessary.
Signature verification object
The response will include a verification
object that describes the result of verifying the commit's signature. The following fields are included in the verification
object:
Name | Type | Description |
---|---|---|
verified | boolean | Indicates whether GitHub considers the signature in this commit to be verified. |
reason | string | The reason for verified value. Possible values and their meanings are enumerated in table below. |
signature | string | The signature that was extracted from the commit. |
payload | string | The value that was signed. |
These are the possible values for reason
in the verification
object:
Value | Description |
---|---|
expired_key | The key that made the signature is expired. |
not_signing_key | The "signing" flag is not among the usage flags in the GPG key that made the signature. |
gpgverify_error | There was an error communicating with the signature verification service. |
gpgverify_unavailable | The signature verification service is currently unavailable. |
unsigned | The object does not include a signature. |
unknown_signature_type | A non-PGP signature was found in the commit. |
no_user | No user was associated with the committer email address in the commit. |
unverified_email | The committer email address in the commit was associated with a user, but the email address is not verified on their account. |
bad_email | The committer email address in the commit is not included in the identities of the PGP key that made the signature. |
unknown_key | The key that made the signature has not been registered with any user's account. |
malformed_signature | There was an error parsing the signature. |
invalid | The signature could not be cryptographically verified using the key whose key-id was found in the signature. |
valid | None of the above errors applied, so the signature is considered to be verified. |
octokit.rest.git.createTag({
owner,
repo,
tag,
message,
object,
type,
tagger.name,
tagger.email
})
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
tag | yes |
The tag's name. This is typically a version (e.g., "v0.0.1"). |
message | yes |
The tag message. |
object | yes |
The SHA of the git object this is tagging. |
type | yes |
The type of the object we're tagging. Normally this is a |
tagger | no |
An object with information about the individual creating the tag. |
tagger.name | yes |
The name of the author of the tag |
tagger.email | yes |
The email of the author of the tag |
tagger.date | no |
When this object was tagged. This is a timestamp in ISO 8601 format: |
See also: GitHub Developer Guide documentation.
Create a tree
The tree creation API accepts nested entries. If you specify both a tree and a nested path modifying that tree, this endpoint will overwrite the contents of the tree with the new path contents, and create a new tree structure.
If you use this endpoint to add, delete, or modify the file contents in a tree, you will need to commit the tree and then update a branch to point to the commit. For more information see "Create a commit" and "Update a reference."
Returns an error if you try to delete a file that does not exist.
octokit.rest.git.createTree({
owner,
repo,
tree,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
tree | yes |
Objects (of |
tree[].path | no |
The file referenced in the tree. |
tree[].mode | no |
The file mode; one of |
tree[].type | no |
Either |
tree[].sha | no |
The SHA1 checksum ID of the object in the tree. Also called Note: Use either |
tree[].content | no |
The content you want this file to have. GitHub will write this blob out and use that SHA for this entry. Use either this, or Note: Use either |
base_tree | no |
The SHA1 of an existing Git tree object which will be used as the base for the new tree. If provided, a new Git tree object will be created from entries in the Git tree object pointed to by |
See also: GitHub Developer Guide documentation.
Delete a reference
Deletes the provided reference.
octokit.rest.git.deleteRef({
owner,
repo,
ref,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
ref | yes |
The Git reference. For more information, see "Git References" in the Git documentation. |
See also: GitHub Developer Guide documentation.
Get a blob
The content
in the response will always be Base64 encoded.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github.raw+json
: Returns the raw blob data.application/vnd.github+json
: Returns a JSON representation of the blob withcontent
as a base64 encoded string. This is the default if no media type is specified.
Note This endpoint supports blobs up to 100 megabytes in size.
octokit.rest.git.getBlob({
owner,
repo,
file_sha,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
file_sha | yes |
See also: GitHub Developer Guide documentation.
Get a commit object
Gets a Git commit object.
To get the contents of a commit, see "Get a commit."
Signature verification object
The response will include a verification
object that describes the result of verifying the commit's signature. The following fields are included in the verification
object:
Name | Type | Description |
---|---|---|
verified | boolean | Indicates whether GitHub considers the signature in this commit to be verified. |
reason | string | The reason for verified value. Possible values and their meanings are enumerated in the table below. |
signature | string | The signature that was extracted from the commit. |
payload | string | The value that was signed. |
These are the possible values for reason
in the verification
object:
Value | Description |
---|---|
expired_key | The key that made the signature is expired. |
not_signing_key | The "signing" flag is not among the usage flags in the GPG key that made the signature. |
gpgverify_error | There was an error communicating with the signature verification service. |
gpgverify_unavailable | The signature verification service is currently unavailable. |
unsigned | The object does not include a signature. |
unknown_signature_type | A non-PGP signature was found in the commit. |
no_user | No user was associated with the committer email address in the commit. |
unverified_email | The committer email address in the commit was associated with a user, but the email address is not verified on their account. |
bad_email | The committer email address in the commit is not included in the identities of the PGP key that made the signature. |
unknown_key | The key that made the signature has not been registered with any user's account. |
malformed_signature | There was an error parsing the signature. |
invalid | The signature could not be cryptographically verified using the key whose key-id was found in the signature. |
valid | None of the above errors applied, so the signature is considered to be verified. |
octokit.rest.git.getCommit({
owner,
repo,
commit_sha,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
commit_sha | yes |
The SHA of the commit. |
See also: GitHub Developer Guide documentation.
Get a reference
Returns a single reference from your Git database. The :ref
in the URL must be formatted as heads/<branch name>
for branches and tags/<tag name>
for tags. If the :ref
doesn't match an existing ref, a 404
is returned.
Note: You need to explicitly request a pull request to trigger a test merge commit, which checks the mergeability of pull requests. For more information, see "Checking mergeability of pull requests".
octokit.rest.git.getRef({
owner,
repo,
ref,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
ref | yes |
The Git reference. For more information, see "Git References" in the Git documentation. |
See also: GitHub Developer Guide documentation.
Get a tag
Signature verification object
The response will include a verification
object that describes the result of verifying the commit's signature. The following fields are included in the verification
object:
Name | Type | Description |
---|---|---|
verified | boolean | Indicates whether GitHub considers the signature in this commit to be verified. |
reason | string | The reason for verified value. Possible values and their meanings are enumerated in table below. |
signature | string | The signature that was extracted from the commit. |
payload | string | The value that was signed. |
These are the possible values for reason
in the verification
object:
Value | Description |
---|---|
expired_key | The key that made the signature is expired. |
not_signing_key | The "signing" flag is not among the usage flags in the GPG key that made the signature. |
gpgverify_error | There was an error communicating with the signature verification service. |
gpgverify_unavailable | The signature verification service is currently unavailable. |
unsigned | The object does not include a signature. |
unknown_signature_type | A non-PGP signature was found in the commit. |
no_user | No user was associated with the committer email address in the commit. |
unverified_email | The committer email address in the commit was associated with a user, but the email address is not verified on their account. |
bad_email | The committer email address in the commit is not included in the identities of the PGP key that made the signature. |
unknown_key | The key that made the signature has not been registered with any user's account. |
malformed_signature | There was an error parsing the signature. |
invalid | The signature could not be cryptographically verified using the key whose key-id was found in the signature. |
valid | None of the above errors applied, so the signature is considered to be verified. |
octokit.rest.git.getTag({
owner,
repo,
tag_sha,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
tag_sha | yes |
See also: GitHub Developer Guide documentation.
Get a tree
Returns a single tree using the SHA1 value or ref name for that tree.
If truncated
is true
in the response then the number of items in the tree
array exceeded our maximum limit. If you need to fetch more items, use the non-recursive method of fetching trees, and fetch one sub-tree at a time.
Note: The limit for the tree
array is 100,000 entries with a maximum size of 7 MB when using the recursive
parameter.
octokit.rest.git.getTree({
owner,
repo,
tree_sha,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
tree_sha | yes |
The SHA1 value or ref (branch or tag) name of the tree. |
recursive | no |
Setting this parameter to any value returns the objects or subtrees referenced by the tree specified in |
See also: GitHub Developer Guide documentation.
List matching references
Returns an array of references from your Git database that match the supplied name. The :ref
in the URL must be formatted as heads/<branch name>
for branches and tags/<tag name>
for tags. If the :ref
doesn't exist in the repository, but existing refs start with :ref
, they will be returned as an array.
When you use this endpoint without providing a :ref
, it will return an array of all the references from your Git database, including notes and stashes if they exist on the server. Anything in the namespace is returned, not just heads
and tags
.
Note: You need to explicitly request a pull request to trigger a test merge commit, which checks the mergeability of pull requests. For more information, see "Checking mergeability of pull requests".
If you request matching references for a branch named feature
but the branch feature
doesn't exist, the response can still include other matching head refs that start with the word feature
, such as featureA
and featureB
.
octokit.rest.git.listMatchingRefs({
owner,
repo,
ref,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
ref | yes |
The Git reference. For more information, see "Git References" in the Git documentation. |
See also: GitHub Developer Guide documentation.
Update a reference
Updates the provided reference to point to a new SHA. For more information, see "Git References" in the Git documentation.
octokit.rest.git.updateRef({
owner,
repo,
ref,
sha,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
ref | yes |
The Git reference. For more information, see "Git References" in the Git documentation. |
sha | yes |
The SHA1 value to set this reference to |
force | no |
Indicates whether to force the update or to make sure the update is a fast-forward update. Leaving this out or setting it to |
See also: GitHub Developer Guide documentation.
Gitignore
Get all gitignore templates
List all templates available to pass as an option when creating a repository.
octokit.rest.gitignore.getAllTemplates();
Parameters
This endpoint has no parameters
See also: GitHub Developer Guide documentation.
Get a gitignore template
Get the content of a gitignore template.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github.raw+json
: Returns the raw .gitignore contents.
octokit.rest.gitignore.getTemplate({
name,
});
Parameters
name | required | description |
---|---|---|
name | yes |
See also: GitHub Developer Guide documentation.
Interactions
Get interaction restrictions for your public repositories
Shows which type of GitHub user can interact with your public repositories and when the restriction expires.
octokit.rest.interactions.getRestrictionsForAuthenticatedUser();
Parameters
This endpoint has no parameters
See also: GitHub Developer Guide documentation.
Get interaction restrictions for an organization
Shows which type of GitHub user can interact with this organization and when the restriction expires. If there is no restrictions, you will see an empty response.
octokit.rest.interactions.getRestrictionsForOrg({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
See also: GitHub Developer Guide documentation.
Get interaction restrictions for a repository
Shows which type of GitHub user can interact with this repository and when the restriction expires. If there are no restrictions, you will see an empty response.
octokit.rest.interactions.getRestrictionsForRepo({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Get interaction restrictions for your public repositories
Deprecated: This method has been renamed to interactions.getRestrictionsForAuthenticatedUser
Shows which type of GitHub user can interact with your public repositories and when the restriction expires.
octokit.rest.interactions.getRestrictionsForYourPublicRepos();
Parameters
This endpoint has no parameters
See also: GitHub Developer Guide documentation.
Remove interaction restrictions from your public repositories
Removes any interaction restrictions from your public repositories.
octokit.rest.interactions.removeRestrictionsForAuthenticatedUser();
Parameters
This endpoint has no parameters
See also: GitHub Developer Guide documentation.
Remove interaction restrictions for an organization
Removes all interaction restrictions from public repositories in the given organization. You must be an organization owner to remove restrictions.
octokit.rest.interactions.removeRestrictionsForOrg({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
See also: GitHub Developer Guide documentation.
Remove interaction restrictions for a repository
Removes all interaction restrictions from the given repository. You must have owner or admin access to remove restrictions. If the interaction limit is set for the user or organization that owns this repository, you will receive a 409 Conflict
response and will not be able to use this endpoint to change the interaction limit for a single repository.
octokit.rest.interactions.removeRestrictionsForRepo({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Remove interaction restrictions from your public repositories
Deprecated: This method has been renamed to interactions.removeRestrictionsForAuthenticatedUser
Removes any interaction restrictions from your public repositories.
octokit.rest.interactions.removeRestrictionsForYourPublicRepos();
Parameters
This endpoint has no parameters
See also: GitHub Developer Guide documentation.
Set interaction restrictions for your public repositories
Temporarily restricts which type of GitHub user can interact with your public repositories. Setting the interaction limit at the user level will overwrite any interaction limits that are set for individual repositories owned by the user.
octokit.rest.interactions.setRestrictionsForAuthenticatedUser({
limit,
});
Parameters
name | required | description |
---|---|---|
limit | yes |
The type of GitHub user that can comment, open issues, or create pull requests while the interaction limit is in effect. |
expiry | no |
The duration of the interaction restriction. Default: |
See also: GitHub Developer Guide documentation.
Set interaction restrictions for an organization
Temporarily restricts interactions to a certain type of GitHub user in any public repository in the given organization. You must be an organization owner to set these restrictions. Setting the interaction limit at the organization level will overwrite any interaction limits that are set for individual repositories owned by the organization.
octokit.rest.interactions.setRestrictionsForOrg({
org,
limit,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
limit | yes |
The type of GitHub user that can comment, open issues, or create pull requests while the interaction limit is in effect. |
expiry | no |
The duration of the interaction restriction. Default: |
See also: GitHub Developer Guide documentation.
Set interaction restrictions for a repository
Temporarily restricts interactions to a certain type of GitHub user within the given repository. You must have owner or admin access to set these restrictions. If an interaction limit is set for the user or organization that owns this repository, you will receive a 409 Conflict
response and will not be able to use this endpoint to change the interaction limit for a single repository.
octokit.rest.interactions.setRestrictionsForRepo({
owner,
repo,
limit,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
limit | yes |
The type of GitHub user that can comment, open issues, or create pull requests while the interaction limit is in effect. |
expiry | no |
The duration of the interaction restriction. Default: |
See also: GitHub Developer Guide documentation.
Set interaction restrictions for your public repositories
Deprecated: This method has been renamed to interactions.setRestrictionsForAuthenticatedUser
Temporarily restricts which type of GitHub user can interact with your public repositories. Setting the interaction limit at the user level will overwrite any interaction limits that are set for individual repositories owned by the user.
octokit.rest.interactions.setRestrictionsForYourPublicRepos({
limit,
});
Parameters
name | required | description |
---|---|---|
limit | yes |
The type of GitHub user that can comment, open issues, or create pull requests while the interaction limit is in effect. |
expiry | no |
The duration of the interaction restriction. Default: |
See also: GitHub Developer Guide documentation.
Issues
Add assignees to an issue
Adds up to 10 assignees to an issue. Users already assigned to an issue are not replaced.
octokit.rest.issues.addAssignees({
owner,
repo,
issue_number,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
issue_number | yes |
The number that identifies the issue. |
assignees | no |
Usernames of people to assign this issue to. NOTE: Only users with push access can add assignees to an issue. Assignees are silently ignored otherwise. |
See also: GitHub Developer Guide documentation.
Add labels to an issue
Adds labels to an issue. If you provide an empty array of labels, all labels are removed from the issue.
octokit.rest.issues.addLabels({
owner,
repo,
issue_number,
labels[].name
})
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
issue_number | yes |
The number that identifies the issue. |
labels | no | |
labels[].name | yes |
See also: GitHub Developer Guide documentation.
Check if a user can be assigned
Checks if a user has permission to be assigned to an issue in this repository.
If the assignee
can be assigned to issues in the repository, a 204
header with no content is returned.
Otherwise a 404
status code is returned.
octokit.rest.issues.checkUserCanBeAssigned({
owner,
repo,
assignee,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
assignee | yes |
See also: GitHub Developer Guide documentation.
Check if a user can be assigned to a issue
Checks if a user has permission to be assigned to a specific issue.
If the assignee
can be assigned to this issue, a 204
status code with no content is returned.
Otherwise a 404
status code is returned.
octokit.rest.issues.checkUserCanBeAssignedToIssue({
owner,
repo,
issue_number,
assignee,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
issue_number | yes |
The number that identifies the issue. |
assignee | yes |
See also: GitHub Developer Guide documentation.
Create an issue
Any user with pull access to a repository can create an issue. If issues are disabled in the repository, the API returns a 410 Gone
status.
This endpoint triggers notifications. Creating content too quickly using this endpoint may result in secondary rate limiting. For more information, see "Rate limits for the API" and "Best practices for using the REST API."
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github.raw+json
: Returns the raw markdown body. Response will includebody
. This is the default if you do not pass any specific media type.application/vnd.github.text+json
: Returns a text only representation of the markdown body. Response will includebody_text
.application/vnd.github.html+json
: Returns HTML rendered from the body's markdown. Response will includebody_html
.application/vnd.github.full+json
: Returns raw, text, and HTML representations. Response will includebody
,body_text
, andbody_html
.
octokit.rest.issues.create({
owner,
repo,
title,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
title | yes |
The title of the issue. |
body | no |
The contents of the issue. |
assignee | no |
Login for the user that this issue should be assigned to. NOTE: Only users with push access can set the assignee for new issues. The assignee is silently dropped otherwise. This field is deprecated. |
milestone | no | |
labels | no |
Labels to associate with this issue. NOTE: Only users with push access can set labels for new issues. Labels are silently dropped otherwise. |
assignees | no |
Logins for Users to assign to this issue. NOTE: Only users with push access can set assignees for new issues. Assignees are silently dropped otherwise. |
See also: GitHub Developer Guide documentation.
Create an issue comment
You can use the REST API to create comments on issues and pull requests. Every pull request is an issue, but not every issue is a pull request.
This endpoint triggers notifications. Creating content too quickly using this endpoint may result in secondary rate limiting. For more information, see "Rate limits for the API" and "Best practices for using the REST API."
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github.raw+json
: Returns the raw markdown body. Response will includebody
. This is the default if you do not pass any specific media type.application/vnd.github.text+json
: Returns a text only representation of the markdown body. Response will includebody_text
.application/vnd.github.html+json
: Returns HTML rendered from the body's markdown. Response will includebody_html
.application/vnd.github.full+json
: Returns raw, text, and HTML representations. Response will includebody
,body_text
, andbody_html
.
octokit.rest.issues.createComment({
owner,
repo,
issue_number,
body,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
issue_number | yes |
The number that identifies the issue. |
body | yes |
The contents of the comment. |
See also: GitHub Developer Guide documentation.
Create a label
Creates a label for the specified repository with the given name and color. The name and color parameters are required. The color must be a valid hexadecimal color code.
octokit.rest.issues.createLabel({
owner,
repo,
name,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
name | yes |
The name of the label. Emoji can be added to label names, using either native emoji or colon-style markup. For example, typing |
color | no |
The hexadecimal color code for the label, without the leading |
description | no |
A short description of the label. Must be 100 characters or fewer. |
See also: GitHub Developer Guide documentation.
Create a milestone
Creates a milestone.
octokit.rest.issues.createMilestone({
owner,
repo,
title,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
title | yes |
The title of the milestone. |
state | no |
The state of the milestone. Either |
description | no |
A description of the milestone. |
due_on | no |
The milestone due date. This is a timestamp in ISO 8601 format: |
See also: GitHub Developer Guide documentation.
Delete an issue comment
You can use the REST API to delete comments on issues and pull requests. Every pull request is an issue, but not every issue is a pull request.
octokit.rest.issues.deleteComment({
owner,
repo,
comment_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
comment_id | yes |
The unique identifier of the comment. |
See also: GitHub Developer Guide documentation.
Delete a label
Deletes a label using the given label name.
octokit.rest.issues.deleteLabel({
owner,
repo,
name,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
name | yes |
See also: GitHub Developer Guide documentation.
Delete a milestone
Deletes a milestone using the given milestone number.
octokit.rest.issues.deleteMilestone({
owner,
repo,
milestone_number,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
milestone_number | yes |
The number that identifies the milestone. |
See also: GitHub Developer Guide documentation.
Get an issue
The API returns a 301 Moved Permanently
status if the issue was
transferred to another repository. If
the issue was transferred to or deleted from a repository where the authenticated user lacks read access, the API
returns a 404 Not Found
status. If the issue was deleted from a repository where the authenticated user has read
access, the API returns a 410 Gone
status. To receive webhook events for transferred and deleted issues, subscribe
to the issues
webhook.
Note: GitHub's REST API considers every pull request an issue, but not every issue is a pull request. For this
reason, "Issues" endpoints may return both issues and pull requests in the response. You can identify pull requests by
the pull_request
key. Be aware that the id
of a pull request returned from "Issues" endpoints will be an issue id. To find out the pull
request id, use the "List pull requests" endpoint.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github.raw+json
: Returns the raw markdown body. Response will includebody
. This is the default if you do not pass any specific media type.application/vnd.github.text+json
: Returns a text only representation of the markdown body. Response will includebody_text
.application/vnd.github.html+json
: Returns HTML rendered from the body's markdown. Response will includebody_html
.application/vnd.github.full+json
: Returns raw, text, and HTML representations. Response will includebody
,body_text
, andbody_html
.
octokit.rest.issues.get({
owner,
repo,
issue_number,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
issue_number | yes |
The number that identifies the issue. |
See also: GitHub Developer Guide documentation.
Get an issue comment
You can use the REST API to get comments on issues and pull requests. Every pull request is an issue, but not every issue is a pull request.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github.raw+json
: Returns the raw markdown body. Response will includebody
. This is the default if you do not pass any specific media type.application/vnd.github.text+json
: Returns a text only representation of the markdown body. Response will includebody_text
.application/vnd.github.html+json
: Returns HTML rendered from the body's markdown. Response will includebody_html
.application/vnd.github.full+json
: Returns raw, text, and HTML representations. Response will includebody
,body_text
, andbody_html
.
octokit.rest.issues.getComment({
owner,
repo,
comment_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
comment_id | yes |
The unique identifier of the comment. |
See also: GitHub Developer Guide documentation.
Get an issue event
Gets a single event by the event id.
octokit.rest.issues.getEvent({
owner,
repo,
event_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
event_id | yes |
See also: GitHub Developer Guide documentation.
Get a label
Gets a label using the given name.
octokit.rest.issues.getLabel({
owner,
repo,
name,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
name | yes |
See also: GitHub Developer Guide documentation.
Get a milestone
Gets a milestone using the given milestone number.
octokit.rest.issues.getMilestone({
owner,
repo,
milestone_number,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
milestone_number | yes |
The number that identifies the milestone. |
See also: GitHub Developer Guide documentation.
List issues assigned to the authenticated user
List issues assigned to the authenticated user across all visible repositories including owned repositories, member
repositories, and organization repositories. You can use the filter
query parameter to fetch issues that are not
necessarily assigned to you.
Note: GitHub's REST API considers every pull request an issue, but not every issue is a pull request. For this
reason, "Issues" endpoints may return both issues and pull requests in the response. You can identify pull requests by
the pull_request
key. Be aware that the id
of a pull request returned from "Issues" endpoints will be an issue id. To find out the pull
request id, use the "List pull requests" endpoint.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github.raw+json
: Returns the raw markdown body. Response will includebody
. This is the default if you do not pass any specific media type.application/vnd.github.text+json
: Returns a text only representation of the markdown body. Response will includebody_text
.application/vnd.github.html+json
: Returns HTML rendered from the body's markdown. Response will includebody_html
.application/vnd.github.full+json
: Returns raw, text, and HTML representations. Response will includebody
,body_text
, andbody_html
.
octokit.rest.issues.list();
Parameters
name | required | description |
---|---|---|
filter | no |
Indicates which sorts of issues to return. |
state | no |
Indicates the state of the issues to return. |
labels | no |
A list of comma separated label names. Example: |
sort | no |
What to sort results by. |
direction | no |
The direction to sort the results by. |
since | no |
Only show results that were last updated after the given time. This is a timestamp in ISO 8601 format: |
collab | no | |
orgs | no | |
owned | no | |
pulls | no | |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List assignees
Lists the available assignees for issues in a repository.
octokit.rest.issues.listAssignees({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List issue comments
You can use the REST API to list comments on issues and pull requests. Every pull request is an issue, but not every issue is a pull request.
Issue comments are ordered by ascending ID.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github.raw+json
: Returns the raw markdown body. Response will includebody
. This is the default if you do not pass any specific media type.application/vnd.github.text+json
: Returns a text only representation of the markdown body. Response will includebody_text
.application/vnd.github.html+json
: Returns HTML rendered from the body's markdown. Response will includebody_html
.application/vnd.github.full+json
: Returns raw, text, and HTML representations. Response will includebody
,body_text
, andbody_html
.
octokit.rest.issues.listComments({
owner,
repo,
issue_number,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
issue_number | yes |
The number that identifies the issue. |
since | no |
Only show results that were last updated after the given time. This is a timestamp in ISO 8601 format: |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List issue comments for a repository
You can use the REST API to list comments on issues and pull requests for a repository. Every pull request is an issue, but not every issue is a pull request.
By default, issue comments are ordered by ascending ID.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github.raw+json
: Returns the raw markdown body. Response will includebody
. This is the default if you do not pass any specific media type.application/vnd.github.text+json
: Returns a text only representation of the markdown body. Response will includebody_text
.application/vnd.github.html+json
: Returns HTML rendered from the body's markdown. Response will includebody_html
.application/vnd.github.full+json
: Returns raw, text, and HTML representations. Response will includebody
,body_text
, andbody_html
.
octokit.rest.issues.listCommentsForRepo({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
sort | no |
The property to sort the results by. |
direction | no |
Either |
since | no |
Only show results that were last updated after the given time. This is a timestamp in ISO 8601 format: |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List issue events
Lists all events for an issue.
octokit.rest.issues.listEvents({
owner,
repo,
issue_number,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
issue_number | yes |
The number that identifies the issue. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List issue events for a repository
Lists events for a repository.
octokit.rest.issues.listEventsForRepo({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List timeline events for an issue
List all timeline events for an issue.
octokit.rest.issues.listEventsForTimeline({
owner,
repo,
issue_number,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
issue_number | yes |
The number that identifies the issue. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List user account issues assigned to the authenticated user
List issues across owned and member repositories assigned to the authenticated user.
Note: GitHub's REST API considers every pull request an issue, but not every issue is a pull request. For this
reason, "Issues" endpoints may return both issues and pull requests in the response. You can identify pull requests by
the pull_request
key. Be aware that the id
of a pull request returned from "Issues" endpoints will be an issue id. To find out the pull
request id, use the "List pull requests" endpoint.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github.raw+json
: Returns the raw markdown body. Response will includebody
. This is the default if you do not pass any specific media type.application/vnd.github.text+json
: Returns a text only representation of the markdown body. Response will includebody_text
.application/vnd.github.html+json
: Returns HTML rendered from the body's markdown. Response will includebody_html
.application/vnd.github.full+json
: Returns raw, text, and HTML representations. Response will includebody
,body_text
, andbody_html
.
octokit.rest.issues.listForAuthenticatedUser();
Parameters
name | required | description |
---|---|---|
filter | no |
Indicates which sorts of issues to return. |
state | no |
Indicates the state of the issues to return. |
labels | no |
A list of comma separated label names. Example: |
sort | no |
What to sort results by. |
direction | no |
The direction to sort the results by. |
since | no |
Only show results that were last updated after the given time. This is a timestamp in ISO 8601 format: |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List organization issues assigned to the authenticated user
List issues in an organization assigned to the authenticated user.
Note: GitHub's REST API considers every pull request an issue, but not every issue is a pull request. For this
reason, "Issues" endpoints may return both issues and pull requests in the response. You can identify pull requests by
the pull_request
key. Be aware that the id
of a pull request returned from "Issues" endpoints will be an issue id. To find out the pull
request id, use the "List pull requests" endpoint.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github.raw+json
: Returns the raw markdown body. Response will includebody
. This is the default if you do not pass any specific media type.application/vnd.github.text+json
: Returns a text only representation of the markdown body. Response will includebody_text
.application/vnd.github.html+json
: Returns HTML rendered from the body's markdown. Response will includebody_html
.application/vnd.github.full+json
: Returns raw, text, and HTML representations. Response will includebody
,body_text
, andbody_html
.
octokit.rest.issues.listForOrg({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
filter | no |
Indicates which sorts of issues to return. |
state | no |
Indicates the state of the issues to return. |
labels | no |
A list of comma separated label names. Example: |
sort | no |
What to sort results by. |
direction | no |
The direction to sort the results by. |
since | no |
Only show results that were last updated after the given time. This is a timestamp in ISO 8601 format: |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List repository issues
List issues in a repository. Only open issues will be listed.
Note: GitHub's REST API considers every pull request an issue, but not every issue is a pull request. For this
reason, "Issues" endpoints may return both issues and pull requests in the response. You can identify pull requests by
the pull_request
key. Be aware that the id
of a pull request returned from "Issues" endpoints will be an issue id. To find out the pull
request id, use the "List pull requests" endpoint.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github.raw+json
: Returns the raw markdown body. Response will includebody
. This is the default if you do not pass any specific media type.application/vnd.github.text+json
: Returns a text only representation of the markdown body. Response will includebody_text
.application/vnd.github.html+json
: Returns HTML rendered from the body's markdown. Response will includebody_html
.application/vnd.github.full+json
: Returns raw, text, and HTML representations. Response will includebody
,body_text
, andbody_html
.
octokit.rest.issues.listForRepo({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
milestone | no |
If an |
state | no |
Indicates the state of the issues to return. |
assignee | no |
Can be the name of a user. Pass in |
creator | no |
The user that created the issue. |
mentioned | no |
A user that's mentioned in the issue. |
labels | no |
A list of comma separated label names. Example: |
sort | no |
What to sort results by. |
direction | no |
The direction to sort the results by. |
since | no |
Only show results that were last updated after the given time. This is a timestamp in ISO 8601 format: |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List labels for issues in a milestone
Lists labels for issues in a milestone.
octokit.rest.issues.listLabelsForMilestone({
owner,
repo,
milestone_number,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
milestone_number | yes |
The number that identifies the milestone. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List labels for a repository
Lists all labels for a repository.
octokit.rest.issues.listLabelsForRepo({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List labels for an issue
Lists all labels for an issue.
octokit.rest.issues.listLabelsOnIssue({
owner,
repo,
issue_number,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
issue_number | yes |
The number that identifies the issue. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List milestones
Lists milestones for a repository.
octokit.rest.issues.listMilestones({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
state | no |
The state of the milestone. Either |
sort | no |
What to sort results by. Either |
direction | no |
The direction of the sort. Either |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
Lock an issue
Users with push access can lock an issue or pull request's conversation.
Note that, if you choose not to pass any parameters, you'll need to set Content-Length
to zero when calling out to this endpoint. For more information, see "HTTP method."
octokit.rest.issues.lock({
owner,
repo,
issue_number,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
issue_number | yes |
The number that identifies the issue. |
lock_reason | no |
The reason for locking the issue or pull request conversation. Lock will fail if you don't use one of these reasons:
|
See also: GitHub Developer Guide documentation.
Remove all labels from an issue
Removes all labels from an issue.
octokit.rest.issues.removeAllLabels({
owner,
repo,
issue_number,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
issue_number | yes |
The number that identifies the issue. |
See also: GitHub Developer Guide documentation.
Remove assignees from an issue
Removes one or more assignees from an issue.
octokit.rest.issues.removeAssignees({
owner,
repo,
issue_number,
assignees,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository. The name is not case sensitive. |
issue_number | yes |
The number that identifies the issue. |
assignees | yes |
Usernames of assignees to remove from an issue. NOTE: Only users with push access can remove assignees from an issue. Assignees are silently ignored otherwise. |
See also: GitHub Developer Guide documentation.
Remove a label from an issue
Removes the specified label from the issue, and returns the remaining labels on the issue. This endpoint returns a 404 Not Found
status if the label does not exist.
octokit.rest.issues.removeLabel({
owner,
repo,
issue_number,
name,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
issue_number | yes |
The number that identifies the issue. |
name | yes |
See also: GitHub Developer Guide documentation.
Set labels for an issue
Removes any previous labels and sets the new labels for an issue.
octokit.rest.issues.setLabels({
owner,
repo,
issue_number,
labels[].name
})
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
issue_number | yes |
The number that identifies the issue. |
labels | no | |
labels[].name | yes |
See also: GitHub Developer Guide documentation.
Unlock an issue
Users with push access can unlock an issue's conversation.
octokit.rest.issues.unlock({
owner,
repo,
issue_number,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
issue_number | yes |
The number that identifies the issue. |
See also: GitHub Developer Guide documentation.
Update an issue
Issue owners and users with push access can edit an issue.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github.raw+json
: Returns the raw markdown body. Response will includebody
. This is the default if you do not pass any specific media type.application/vnd.github.text+json
: Returns a text only representation of the markdown body. Response will includebody_text
.application/vnd.github.html+json
: Returns HTML rendered from the body's markdown. Response will includebody_html
.application/vnd.github.full+json
: Returns raw, text, and HTML representations. Response will includebody
,body_text
, andbody_html
.
octokit.rest.issues.update({
owner,
repo,
issue_number,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
issue_number | yes |
The number that identifies the issue. |
title | no |
The title of the issue. |
body | no |
The contents of the issue. |
assignee | no |
Username to assign to this issue. This field is deprecated. |
state | no |
The open or closed state of the issue. |
state_reason | no |
The reason for the state change. Ignored unless |
milestone | no | |
labels | no |
Labels to associate with this issue. Pass one or more labels to replace the set of labels on this issue. Send an empty array ( |
assignees | no |
Usernames to assign to this issue. Pass one or more user logins to replace the set of assignees on this issue. Send an empty array ( |
See also: GitHub Developer Guide documentation.
Update an issue comment
You can use the REST API to update comments on issues and pull requests. Every pull request is an issue, but not every issue is a pull request.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github.raw+json
: Returns the raw markdown body. Response will includebody
. This is the default if you do not pass any specific media type.application/vnd.github.text+json
: Returns a text only representation of the markdown body. Response will includebody_text
.application/vnd.github.html+json
: Returns HTML rendered from the body's markdown. Response will includebody_html
.application/vnd.github.full+json
: Returns raw, text, and HTML representations. Response will includebody
,body_text
, andbody_html
.
octokit.rest.issues.updateComment({
owner,
repo,
comment_id,
body,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
comment_id | yes |
The unique identifier of the comment. |
body | yes |
The contents of the comment. |
See also: GitHub Developer Guide documentation.
Update a label
Updates a label using the given label name.
octokit.rest.issues.updateLabel({
owner,
repo,
name,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
name | yes | |
new_name | no |
The new name of the label. Emoji can be added to label names, using either native emoji or colon-style markup. For example, typing |
color | no |
The hexadecimal color code for the label, without the leading |
description | no |
A short description of the label. Must be 100 characters or fewer. |
See also: GitHub Developer Guide documentation.
Update a milestone
octokit.rest.issues.updateMilestone({
owner,
repo,
milestone_number,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
milestone_number | yes |
The number that identifies the milestone. |
title | no |
The title of the milestone. |
state | no |
The state of the milestone. Either |
description | no |
A description of the milestone. |
due_on | no |
The milestone due date. This is a timestamp in ISO 8601 format: |
See also: GitHub Developer Guide documentation.
Licenses
Get a license
Gets information about a specific license. For more information, see "Licensing a repository ."
octokit.rest.licenses.get({
license,
});
Parameters
name | required | description |
---|---|---|
license | yes |
See also: GitHub Developer Guide documentation.
Get all commonly used licenses
Lists the most commonly used licenses on GitHub. For more information, see "Licensing a repository ."
octokit.rest.licenses.getAllCommonlyUsed();
Parameters
name | required | description |
---|---|---|
featured | no | |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
Get the license for a repository
This method returns the contents of the repository's license file, if one is detected.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github.raw+json
: Returns the raw contents of the license.application/vnd.github.html+json
: Returns the license contents in HTML. Markup languages are rendered to HTML using GitHub's open-source Markup library.
octokit.rest.licenses.getForRepo({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
ref | no |
The Git reference for the results you want to list. The |
See also: GitHub Developer Guide documentation.
Markdown
Render a Markdown document
octokit.rest.markdown.render({
text,
});
Parameters
name | required | description |
---|---|---|
text | yes |
The Markdown text to render in HTML. |
mode | no |
The rendering mode. |
context | no |
The repository context to use when creating references in |
See also: GitHub Developer Guide documentation.
Render a Markdown document in raw mode
You must send Markdown as plain text (using a Content-Type
header of text/plain
or text/x-markdown
) to this endpoint, rather than using JSON format. In raw mode, GitHub Flavored Markdown is not supported and Markdown will be rendered in plain format like a README.md file. Markdown content must be 400 KB or less.
octokit.rest.markdown.renderRaw({
data,
});
Parameters
name | required | description |
---|---|---|
data | yes |
raw markdown text |
See also: GitHub Developer Guide documentation.
Meta
Get GitHub meta information
Returns meta information about GitHub, including a list of GitHub's IP addresses. For more information, see "About GitHub's IP addresses."
The API's response also includes a list of GitHub's domain names.
The values shown in the documentation's response are example values. You must always query the API directly to get the latest values.
Note: This endpoint returns both IPv4 and IPv6 addresses. However, not all features support IPv6. You should refer to the specific documentation for each feature to determine if IPv6 is supported.
octokit.rest.meta.get();
Parameters
This endpoint has no parameters
See also: GitHub Developer Guide documentation.
Get all API versions
Get all supported GitHub API versions.
octokit.rest.meta.getAllVersions();
Parameters
This endpoint has no parameters
See also: GitHub Developer Guide documentation.
Get Octocat
Get the octocat as ASCII art
octokit.rest.meta.getOctocat();
Parameters
name | required | description |
---|---|---|
s | no |
The words to show in Octocat's speech bubble |
See also: GitHub Developer Guide documentation.
Get the Zen of GitHub
Get a random sentence from the Zen of GitHub
octokit.rest.meta.getZen();
Parameters
This endpoint has no parameters
See also: GitHub Developer Guide documentation.
GitHub API Root
Get Hypermedia links to resources accessible in GitHub's REST API
octokit.rest.meta.root();
Parameters
This endpoint has no parameters
See also: GitHub Developer Guide documentation.
Migrations
Delete a user migration archive
Deletes a previous migration archive. Downloadable migration archives are automatically deleted after seven days. Migration metadata, which is returned in the List user migrations and Get a user migration status endpoints, will continue to be available even after an archive is deleted.
octokit.rest.migrations.deleteArchiveForAuthenticatedUser({
migration_id,
});
Parameters
name | required | description |
---|---|---|
migration_id | yes |
The unique identifier of the migration. |
See also: GitHub Developer Guide documentation.
Delete an organization migration archive
Deletes a previous migration archive. Migration archives are automatically deleted after seven days.
octokit.rest.migrations.deleteArchiveForOrg({
org,
migration_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
migration_id | yes |
The unique identifier of the migration. |
See also: GitHub Developer Guide documentation.
Download an organization migration archive
Fetches the URL to a migration archive.
octokit.rest.migrations.downloadArchiveForOrg({
org,
migration_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
migration_id | yes |
The unique identifier of the migration. |
See also: GitHub Developer Guide documentation.
Download a user migration archive
Fetches the URL to download the migration archive as a tar.gz
file. Depending on the resources your repository uses, the migration archive can contain JSON files with data for these objects:
- attachments
- bases
- commit_comments
- issue_comments
- issue_events
- issues
- milestones
- organizations
- projects
- protected_branches
- pull_request_reviews
- pull_requests
- releases
- repositories
- review_comments
- schema
- users
The archive will also contain an attachments
directory that includes all attachment files uploaded to GitHub.com and a repositories
directory that contains the repository's Git data.
octokit.rest.migrations.getArchiveForAuthenticatedUser({
migration_id,
});
Parameters
name | required | description |
---|---|---|
migration_id | yes |
The unique identifier of the migration. |
See also: GitHub Developer Guide documentation.
Get a user migration status
Fetches a single user migration. The response includes the state
of the migration, which can be one of the following values:
pending
- the migration hasn't started yet.exporting
- the migration is in progress.exported
- the migration finished successfully.failed
- the migration failed.
Once the migration has been exported
you can download the migration archive.
octokit.rest.migrations.getStatusForAuthenticatedUser({
migration_id,
});
Parameters
name | required | description |
---|---|---|
migration_id | yes |
The unique identifier of the migration. |
exclude | no |
See also: GitHub Developer Guide documentation.
Get an organization migration status
Fetches the status of a migration.
The state
of a migration can be one of the following values:
pending
, which means the migration hasn't started yet.exporting
, which means the migration is in progress.exported
, which means the migration finished successfully.failed
, which means the migration failed.
octokit.rest.migrations.getStatusForOrg({
org,
migration_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
migration_id | yes |
The unique identifier of the migration. |
exclude | no |
Exclude attributes from the API response to improve performance |
See also: GitHub Developer Guide documentation.
List user migrations
Lists all migrations a user has started.
octokit.rest.migrations.listForAuthenticatedUser();
Parameters
name | required | description |
---|---|---|
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List organization migrations
Lists the most recent migrations, including both exports (which can be started through the REST API) and imports (which cannot be started using the REST API).
A list of repositories
is only returned for export migrations.
octokit.rest.migrations.listForOrg({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
exclude | no |
Exclude attributes from the API response to improve performance |
See also: GitHub Developer Guide documentation.
List repositories for a user migration
Lists all the repositories for this user migration.
octokit.rest.migrations.listReposForAuthenticatedUser({
migration_id,
});
Parameters
name | required | description |
---|---|---|
migration_id | yes |
The unique identifier of the migration. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List repositories in an organization migration
List all the repositories for this organization migration.
octokit.rest.migrations.listReposForOrg({
org,
migration_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
migration_id | yes |
The unique identifier of the migration. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List repositories for a user migration
Deprecated: This method has been renamed to migrations.listReposForAuthenticatedUser
Lists all the repositories for this user migration.
octokit.rest.migrations.listReposForUser({
migration_id,
});
Parameters
name | required | description |
---|---|---|
migration_id | yes |
The unique identifier of the migration. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
Start a user migration
Initiates the generation of a user migration archive.
octokit.rest.migrations.startForAuthenticatedUser({
repositories,
});
Parameters
name | required | description |
---|---|---|
lock_repositories | no |
Lock the repositories being migrated at the start of the migration |
exclude_metadata | no |
Indicates whether metadata should be excluded and only git source should be included for the migration. |
exclude_git_data | no |
Indicates whether the repository git data should be excluded from the migration. |
exclude_attachments | no |
Do not include attachments in the migration |
exclude_releases | no |
Do not include releases in the migration |
exclude_owner_projects | no |
Indicates whether projects owned by the organization or users should be excluded. |
org_metadata_only | no |
Indicates whether this should only include organization metadata (repositories array should be empty and will ignore other flags). |
exclude | no |
Exclude attributes from the API response to improve performance |
repositories | yes |
See also: GitHub Developer Guide documentation.
Start an organization migration
Initiates the generation of a migration archive.
octokit.rest.migrations.startForOrg({
org,
repositories,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
repositories | yes |
A list of arrays indicating which repositories should be migrated. |
lock_repositories | no |
Indicates whether repositories should be locked (to prevent manipulation) while migrating data. |
exclude_metadata | no |
Indicates whether metadata should be excluded and only git source should be included for the migration. |
exclude_git_data | no |
Indicates whether the repository git data should be excluded from the migration. |
exclude_attachments | no |
Indicates whether attachments should be excluded from the migration (to reduce migration archive file size). |
exclude_releases | no |
Indicates whether releases should be excluded from the migration (to reduce migration archive file size). |
exclude_owner_projects | no |
Indicates whether projects owned by the organization or users should be excluded. from the migration. |
org_metadata_only | no |
Indicates whether this should only include organization metadata (repositories array should be empty and will ignore other flags). |
exclude | no |
Exclude related items from being returned in the response in order to improve performance of the request. |
See also: GitHub Developer Guide documentation.
Unlock a user repository
Unlocks a repository. You can lock repositories when you start a user migration. Once the migration is complete you can unlock each repository to begin using it again or delete the repository if you no longer need the source data. Returns a status of 404 Not Found
if the repository is not locked.
octokit.rest.migrations.unlockRepoForAuthenticatedUser({
migration_id,
repo_name,
});
Parameters
name | required | description |
---|---|---|
migration_id | yes |
The unique identifier of the migration. |
repo_name | yes |
repo_name parameter |
See also: GitHub Developer Guide documentation.
Unlock an organization repository
Unlocks a repository that was locked for migration. You should unlock each migrated repository and delete them when the migration is complete and you no longer need the source data.
octokit.rest.migrations.unlockRepoForOrg({
org,
migration_id,
repo_name,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
migration_id | yes |
The unique identifier of the migration. |
repo_name | yes |
repo_name parameter |
See also: GitHub Developer Guide documentation.
Oidc
Get the customization template for an OIDC subject claim for an organization
Gets the customization template for an OpenID Connect (OIDC) subject claim.
OAuth app tokens and personal access tokens (classic) need the read:org
scope to use this endpoint.
octokit.rest.oidc.getOidcCustomSubTemplateForOrg({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
See also: GitHub Developer Guide documentation.
Set the customization template for an OIDC subject claim for an organization
Creates or updates the customization template for an OpenID Connect (OIDC) subject claim.
OAuth app tokens and personal access tokens (classic) need the write:org
scope to use this endpoint.
octokit.rest.oidc.updateOidcCustomSubTemplateForOrg({
org,
include_claim_keys,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
include_claim_keys | yes |
Array of unique strings. Each claim key can only contain alphanumeric characters and underscores. |
See also: GitHub Developer Guide documentation.
Orgs
Add a security manager team
Adds a team as a security manager for an organization. For more information, see "Managing security for an organization for an organization."
The authenticated user must be an administrator for the organization to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the write:org
scope to use this endpoint.
octokit.rest.orgs.addSecurityManagerTeam({
org,
team_slug,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
team_slug | yes |
The slug of the team name. |
See also: GitHub Developer Guide documentation.
Assign an organization role to a team
Assigns an organization role to a team in an organization. For more information on organization roles, see "Managing people's access to your organization with roles."
The authenticated user must be an administrator for the organization to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.orgs.assignTeamToOrgRole({
org,
team_slug,
role_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
team_slug | yes |
The slug of the team name. |
role_id | yes |
The unique identifier of the role. |
See also: GitHub Developer Guide documentation.
Assign an organization role to a user
Assigns an organization role to a member of an organization. For more information on organization roles, see "Managing people's access to your organization with roles."
The authenticated user must be an administrator for the organization to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.orgs.assignUserToOrgRole({
org,
username,
role_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
username | yes |
The handle for the GitHub user account. |
role_id | yes |
The unique identifier of the role. |
See also: GitHub Developer Guide documentation.
Block a user from an organization
Blocks the given user on behalf of the specified organization and returns a 204. If the organization cannot block the given user a 422 is returned.
octokit.rest.orgs.blockUser({
org,
username,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
username | yes |
The handle for the GitHub user account. |
See also: GitHub Developer Guide documentation.
Cancel an organization invitation
Cancel an organization invitation. In order to cancel an organization invitation, the authenticated user must be an organization owner.
This endpoint triggers notifications.
octokit.rest.orgs.cancelInvitation({
org,
invitation_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
invitation_id | yes |
The unique identifier of the invitation. |
See also: GitHub Developer Guide documentation.
Check if a user is blocked by an organization
Returns a 204 if the given user is blocked by the given organization. Returns a 404 if the organization is not blocking the user, or if the user account has been identified as spam by GitHub.
octokit.rest.orgs.checkBlockedUser({
org,
username,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
username | yes |
The handle for the GitHub user account. |
See also: GitHub Developer Guide documentation.
Check organization membership for a user
Check if a user is, publicly or privately, a member of the organization.
octokit.rest.orgs.checkMembershipForUser({
org,
username,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
username | yes |
The handle for the GitHub user account. |
See also: GitHub Developer Guide documentation.
Check public organization membership for a user
Check if the provided user is a public member of the organization.
octokit.rest.orgs.checkPublicMembershipForUser({
org,
username,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
username | yes |
The handle for the GitHub user account. |
See also: GitHub Developer Guide documentation.
Convert an organization member to outside collaborator
When an organization member is converted to an outside collaborator, they'll only have access to the repositories that their current team membership allows. The user will no longer be a member of the organization. For more information, see "Converting an organization member to an outside collaborator". Converting an organization member to an outside collaborator may be restricted by enterprise administrators. For more information, see "Enforcing repository management policies in your enterprise."
octokit.rest.orgs.convertMemberToOutsideCollaborator({
org,
username,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
username | yes |
The handle for the GitHub user account. |
async | no |
When set to |
See also: GitHub Developer Guide documentation.
Create a custom organization role
Creates a custom organization role that can be assigned to users and teams, granting them specific permissions over the organization. For more information on custom organization roles, see "Managing people's access to your organization with roles."
To use this endpoint, the authenticated user must be one of:
- An administrator for the organization.
- A user, or a user on a team, with the fine-grained permissions of
write_organization_custom_org_role
in the organization.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.orgs.createCustomOrganizationRole({
org,
name,
permissions,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
name | yes |
The name of the custom role. |
description | no |
A short description about the intended usage of this role or what permissions it grants. |
permissions | yes |
A list of additional permissions included in this role. |
See also: GitHub Developer Guide documentation.
Create an organization invitation
Invite people to an organization by using their GitHub user ID or their email address. In order to create invitations in an organization, the authenticated user must be an organization owner.
This endpoint triggers notifications. Creating content too quickly using this endpoint may result in secondary rate limiting. For more information, see "Rate limits for the API" and "Best practices for using the REST API."
octokit.rest.orgs.createInvitation({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
invitee_id | no |
Required unless you provide |
no |
Required unless you provide | |
role | no |
The role for the new member.
|
team_ids | no |
Specify IDs for the teams you want to invite new members to. |
See also: GitHub Developer Guide documentation.
Create or update custom properties for an organization
Creates new or updates existing custom properties defined for an organization in a batch.
To use this endpoint, the authenticated user must be one of:
- An administrator for the organization.
- A user, or a user on a team, with the fine-grained permission of
custom_properties_org_definitions_manager
in the organization.
octokit.rest.orgs.createOrUpdateCustomProperties({
org,
properties,
properties[].property_name,
properties[].value_type
})
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
properties | yes |
The array of custom properties to create or update. |
properties[].property_name | yes |
The name of the property |
properties[].value_type | yes |
The type of the value for the property |
properties[].required | no |
Whether the property is required. |
properties[].default_value | no |
Default value of the property |
properties[].description | no |
Short description of the property |
properties[].allowed_values | no |
An ordered list of the allowed values of the property. The property can have up to 200 allowed values. |
properties[].values_editable_by | no |
Who can edit the values of the property |
See also: GitHub Developer Guide documentation.
Create or update custom property values for organization repositories
Create new or update existing custom property values for repositories in a batch that belong to an organization. Each target repository will have its custom property values updated to match the values provided in the request.
A maximum of 30 repositories can be updated in a single request.
Using a value of null
for a custom property will remove or 'unset' the property value from the repository.
To use this endpoint, the authenticated user must be one of:
- An administrator for the organization.
- A user, or a user on a team, with the fine-grained permission of
custom_properties_org_values_editor
in the organization.
octokit.rest.orgs.createOrUpdateCustomPropertiesValuesForRepos({
org,
repository_names,
properties,
properties[].property_name,
properties[].value
})
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
repository_names | yes |
The names of repositories that the custom property values will be applied to. |
properties | yes |
List of custom property names and associated values to apply to the repositories. |
properties[].property_name | yes |
The name of the property |
properties[].value | yes |
The value assigned to the property |
See also: GitHub Developer Guide documentation.
Create or update a custom property for an organization
Creates a new or updates an existing custom property that is defined for an organization.
To use this endpoint, the authenticated user must be one of:
- An administrator for the organization.
- A user, or a user on a team, with the fine-grained permission of
custom_properties_org_definitions_manager
in the organization.
octokit.rest.orgs.createOrUpdateCustomProperty({
org,
custom_property_name,
value_type,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
custom_property_name | yes |
The custom property name. The name is case sensitive. |
value_type | yes |
The type of the value for the property |
required | no |
Whether the property is required. |
default_value | no |
Default value of the property |
description | no |
Short description of the property |
allowed_values | no |
An ordered list of the allowed values of the property. The property can have up to 200 allowed values. |
See also: GitHub Developer Guide documentation.
Create an organization webhook
Create a hook that posts payloads in JSON format.
You must be an organization owner to use this endpoint.
OAuth app tokens and personal access tokens (classic) need admin:org_hook
scope. OAuth apps cannot list, view, or
edit webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.
octokit.rest.orgs.createWebhook({
org,
name,
config,
config.url
})
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
name | yes |
Must be passed as "web". |
config | yes |
Key/value pairs to provide settings for this webhook. |
config.url | yes |
The URL to which the payloads will be delivered. |
config.content_type | no |
The media type used to serialize the payloads. Supported values include |
config.secret | no |
If provided, the |
config.insecure_ssl | no | |
config.username | no | |
config.password | no | |
events | no |
Determines what events the hook is triggered for. Set to |
active | no |
Determines if notifications are sent when the webhook is triggered. Set to |
See also: GitHub Developer Guide documentation.
Delete an organization
Deletes an organization and all its repositories.
The organization login will be unavailable for 90 days after deletion.
Please review the Terms of Service regarding account deletion before using this endpoint:
https://docs.github.com/site-policy/github-terms/github-terms-of-service
octokit.rest.orgs.delete({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
See also: GitHub Developer Guide documentation.
Delete a custom organization role.
Deletes a custom organization role. For more information on custom organization roles, see "Managing people's access to your organization with roles."
To use this endpoint, the authenticated user must be one of:
- An administrator for the organization.
- A user, or a user on a team, with the fine-grained permissions of
write_organization_custom_org_role
in the organization.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.orgs.deleteCustomOrganizationRole({
org,
role_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
role_id | yes |
The unique identifier of the role. |
See also: GitHub Developer Guide documentation.
Delete an organization webhook
You must be an organization owner to use this endpoint.
OAuth app tokens and personal access tokens (classic) need admin:org_hook
scope. OAuth apps cannot list, view, or edit
webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.
octokit.rest.orgs.deleteWebhook({
org,
hook_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
hook_id | yes |
The unique identifier of the hook. You can find this value in the |
See also: GitHub Developer Guide documentation.
Enable or disable a security feature for an organization
Enables or disables the specified security feature for all eligible repositories in an organization. For more information, see "Managing security managers in your organization."
The authenticated user must be an organization owner or be member of a team with the security manager role to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the write:org
scope to use this endpoint.
octokit.rest.orgs.enableOrDisableSecurityProductOnAllOrgRepos({
org,
security_product,
enablement,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
security_product | yes |
The security feature to enable or disable. |
enablement | yes |
The action to take.
|
query_suite | no |
CodeQL query suite to be used. If you specify the |
See also: GitHub Developer Guide documentation.
Get an organization
Gets information about an organization.
When the value of two_factor_requirement_enabled
is true
, the organization requires all members, billing managers, and outside collaborators to enable two-factor authentication.
To see the full details about an organization, the authenticated user must be an organization owner.
The values returned by this endpoint are set by the "Update an organization" endpoint. If your organization set a default security configuration (beta), the following values retrieved from the "Update an organization" endpoint have been overwritten by that configuration:
- advanced_security_enabled_for_new_repositories
- dependabot_alerts_enabled_for_new_repositories
- dependabot_security_updates_enabled_for_new_repositories
- dependency_graph_enabled_for_new_repositories
- secret_scanning_enabled_for_new_repositories
- secret_scanning_push_protection_enabled_for_new_repositories
For more information on security configurations, see "Enabling security features at scale."
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to see the full details about an organization.
To see information about an organization's GitHub plan, GitHub Apps need the Organization plan
permission.
octokit.rest.orgs.get({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
See also: GitHub Developer Guide documentation.
Get all custom properties for an organization
Gets all custom properties defined for an organization. Organization members can read these properties.
octokit.rest.orgs.getAllCustomProperties({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
See also: GitHub Developer Guide documentation.
Get a custom property for an organization
Gets a custom property that is defined for an organization. Organization members can read these properties.
octokit.rest.orgs.getCustomProperty({
org,
custom_property_name,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
custom_property_name | yes |
The custom property name. The name is case sensitive. |
See also: GitHub Developer Guide documentation.
Get an organization membership for the authenticated user
If the authenticated user is an active or pending member of the organization, this endpoint will return the user's membership. If the authenticated user is not affiliated with the organization, a 404
is returned. This endpoint will return a 403
if the request is made by a GitHub App that is blocked by the organization.
octokit.rest.orgs.getMembershipForAuthenticatedUser({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
See also: GitHub Developer Guide documentation.
Get organization membership for a user
In order to get a user's membership with an organization, the authenticated user must be an organization member. The state
parameter in the response can be used to identify the user's membership status.
octokit.rest.orgs.getMembershipForUser({
org,
username,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
username | yes |
The handle for the GitHub user account. |
See also: GitHub Developer Guide documentation.
Get an organization role
Gets an organization role that is available to this organization. For more information on organization roles, see "Managing people's access to your organization with roles."
To use this endpoint, the authenticated user must be one of:
- An administrator for the organization.
- A user, or a user on a team, with the fine-grained permissions of
read_organization_custom_org_role
in the organization.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.orgs.getOrgRole({
org,
role_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
role_id | yes |
The unique identifier of the role. |
See also: GitHub Developer Guide documentation.
Get an organization webhook
Returns a webhook configured in an organization. To get only the webhook
config
properties, see "Get a webhook configuration for an organization.
You must be an organization owner to use this endpoint.
OAuth app tokens and personal access tokens (classic) need admin:org_hook
scope. OAuth apps cannot list, view, or edit
webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.
octokit.rest.orgs.getWebhook({
org,
hook_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
hook_id | yes |
The unique identifier of the hook. You can find this value in the |
See also: GitHub Developer Guide documentation.
Get a webhook configuration for an organization
Returns the webhook configuration for an organization. To get more information about the webhook, including the active
state and events
, use "Get an organization webhook ."
You must be an organization owner to use this endpoint.
OAuth app tokens and personal access tokens (classic) need admin:org_hook
scope. OAuth apps cannot list, view, or edit
webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.
octokit.rest.orgs.getWebhookConfigForOrg({
org,
hook_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
hook_id | yes |
The unique identifier of the hook. You can find this value in the |
See also: GitHub Developer Guide documentation.
Get a webhook delivery for an organization webhook
Returns a delivery for a webhook configured in an organization.
You must be an organization owner to use this endpoint.
OAuth app tokens and personal access tokens (classic) need admin:org_hook
scope. OAuth apps cannot list, view, or edit
webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.
octokit.rest.orgs.getWebhookDelivery({
org,
hook_id,
delivery_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
hook_id | yes |
The unique identifier of the hook. You can find this value in the |
delivery_id | yes |
See also: GitHub Developer Guide documentation.
List organizations
Lists all organizations, in the order that they were created.
Note: Pagination is powered exclusively by the since
parameter. Use the Link header to get the URL for the next page of organizations.
octokit.rest.orgs.list();
Parameters
name | required | description |
---|---|---|
since | no |
An organization ID. Only return organizations with an ID greater than this ID. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List app installations for an organization
Lists all GitHub Apps in an organization. The installation count includes all GitHub Apps installed on repositories in the organization.
The authenticated user must be an organization owner to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the admin:read
scope to use this endpoint.
octokit.rest.orgs.listAppInstallations({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List users blocked by an organization
List the users blocked by an organization.
octokit.rest.orgs.listBlockedUsers({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List custom property values for organization repositories
Lists organization repositories with all of their custom property values. Organization members can read these properties.
octokit.rest.orgs.listCustomPropertiesValuesForRepos({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
repository_query | no |
Finds repositories in the organization with a query containing one or more search keywords and qualifiers. Qualifiers allow you to limit your search to specific areas of GitHub. The REST API supports the same qualifiers as the web interface for GitHub. To learn more about the format of the query, see Constructing a search query. See "Searching for repositories" for a detailed list of qualifiers. |
See also: GitHub Developer Guide documentation.
List failed organization invitations
The return hash contains failed_at
and failed_reason
fields which represent the time at which the invitation failed and the reason for the failure.
octokit.rest.orgs.listFailedInvitations({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List organizations for the authenticated user
List organizations for the authenticated user.
For OAuth app tokens and personal access tokens (classic), this endpoint only lists organizations that your authorization allows you to operate on in some way (e.g., you can list teams with read:org
scope, you can publicize your organization membership with user
scope, etc.). Therefore, this API requires at least user
or read:org
scope for OAuth app tokens and personal access tokens (classic). Requests with insufficient scope will receive a 403 Forbidden
response.
octokit.rest.orgs.listForAuthenticatedUser();
Parameters
name | required | description |
---|---|---|
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List organizations for a user
List public organization memberships for the specified user.
This method only lists public memberships, regardless of authentication. If you need to fetch all of the organization memberships (public and private) for the authenticated user, use the List organizations for the authenticated user API instead.
octokit.rest.orgs.listForUser({
username,
});
Parameters
name | required | description |
---|---|---|
username | yes |
The handle for the GitHub user account. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List organization invitation teams
List all teams associated with an invitation. In order to see invitations in an organization, the authenticated user must be an organization owner.
octokit.rest.orgs.listInvitationTeams({
org,
invitation_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
invitation_id | yes |
The unique identifier of the invitation. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List organization members
List all users who are members of an organization. If the authenticated user is also a member of this organization then both concealed and public members will be returned.
octokit.rest.orgs.listMembers({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
filter | no |
Filter members returned in the list. |
role | no |
Filter members returned by their role. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List organization memberships for the authenticated user
Lists all of the authenticated user's organization memberships.
octokit.rest.orgs.listMembershipsForAuthenticatedUser();
Parameters
name | required | description |
---|---|---|
state | no |
Indicates the state of the memberships to return. If not specified, the API returns both active and pending memberships. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List teams that are assigned to an organization role
Lists the teams that are assigned to an organization role. For more information on organization roles, see "Managing people's access to your organization with roles."
To use this endpoint, you must be an administrator for the organization.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.orgs.listOrgRoleTeams({
org,
role_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
role_id | yes |
The unique identifier of the role. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List users that are assigned to an organization role
Lists organization members that are assigned to an organization role. For more information on organization roles, see "Managing people's access to your organization with roles."
To use this endpoint, you must be an administrator for the organization.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.orgs.listOrgRoleUsers({
org,
role_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
role_id | yes |
The unique identifier of the role. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
Get all organization roles for an organization
Lists the organization roles available in this organization. For more information on organization roles, see "Managing people's access to your organization with roles."
To use this endpoint, the authenticated user must be one of:
- An administrator for the organization.
- A user, or a user on a team, with the fine-grained permissions of
read_organization_custom_org_role
in the organization.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.orgs.listOrgRoles({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
See also: GitHub Developer Guide documentation.
List organization fine-grained permissions for an organization
Lists the fine-grained permissions that can be used in custom organization roles for an organization. For more information, see "Managing people's access to your organization with roles."
To list the fine-grained permissions that can be used in custom repository roles for an organization, see "List repository fine-grained permissions for an organization."
To use this endpoint, the authenticated user must be one of:
- An administrator for the organization.
- A user, or a user on a team, with the fine-grained permissions of
read_organization_custom_org_role
in the organization.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.orgs.listOrganizationFineGrainedPermissions({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
See also: GitHub Developer Guide documentation.
List outside collaborators for an organization
List all users who are outside collaborators of an organization.
octokit.rest.orgs.listOutsideCollaborators({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
filter | no |
Filter the list of outside collaborators. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List repositories a fine-grained personal access token has access to
Lists the repositories a fine-grained personal access token has access to.
Only GitHub Apps can use this endpoint.
octokit.rest.orgs.listPatGrantRepositories({
org,
pat_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
pat_id | yes |
Unique identifier of the fine-grained personal access token. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List repositories requested to be accessed by a fine-grained personal access token
Lists the repositories a fine-grained personal access token request is requesting access to.
Only GitHub Apps can use this endpoint.
octokit.rest.orgs.listPatGrantRequestRepositories({
org,
pat_request_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
pat_request_id | yes |
Unique identifier of the request for access via fine-grained personal access token. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List requests to access organization resources with fine-grained personal access tokens
Lists requests from organization members to access organization resources with a fine-grained personal access token.
Only GitHub Apps can use this endpoint.
octokit.rest.orgs.listPatGrantRequests({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
sort | no |
The property by which to sort the results. |
direction | no |
The direction to sort the results by. |
owner | no |
A list of owner usernames to use to filter the results. |
repository | no |
The name of the repository to use to filter the results. |
permission | no |
The permission to use to filter the results. |
last_used_before | no |
Only show fine-grained personal access tokens used before the given time. This is a timestamp in ISO 8601 format: |
last_used_after | no |
Only show fine-grained personal access tokens used after the given time. This is a timestamp in ISO 8601 format: |
See also: GitHub Developer Guide documentation.
List fine-grained personal access tokens with access to organization resources
Lists approved fine-grained personal access tokens owned by organization members that can access organization resources.
Only GitHub Apps can use this endpoint.
octokit.rest.orgs.listPatGrants({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
sort | no |
The property by which to sort the results. |
direction | no |
The direction to sort the results by. |
owner | no |
A list of owner usernames to use to filter the results. |
repository | no |
The name of the repository to use to filter the results. |
permission | no |
The permission to use to filter the results. |
last_used_before | no |
Only show fine-grained personal access tokens used before the given time. This is a timestamp in ISO 8601 format: |
last_used_after | no |
Only show fine-grained personal access tokens used after the given time. This is a timestamp in ISO 8601 format: |
See also: GitHub Developer Guide documentation.
List pending organization invitations
The return hash contains a role
field which refers to the Organization Invitation role and will be one of the following values: direct_member
, admin
, billing_manager
, or hiring_manager
. If the invitee is not a GitHub member, the login
field in the return hash will be null
.
octokit.rest.orgs.listPendingInvitations({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
role | no |
Filter invitations by their member role. |
invitation_source | no |
Filter invitations by their invitation source. |
See also: GitHub Developer Guide documentation.
List public organization members
Members of an organization can choose to have their membership publicized or not.
octokit.rest.orgs.listPublicMembers({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List security manager teams
Lists teams that are security managers for an organization. For more information, see "Managing security managers in your organization."
The authenticated user must be an administrator or security manager for the organization to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the read:org
scope to use this endpoint.
octokit.rest.orgs.listSecurityManagerTeams({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
See also: GitHub Developer Guide documentation.
List deliveries for an organization webhook
Returns a list of webhook deliveries for a webhook configured in an organization.
You must be an organization owner to use this endpoint.
OAuth app tokens and personal access tokens (classic) need admin:org_hook
scope. OAuth apps cannot list, view, or edit
webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.
octokit.rest.orgs.listWebhookDeliveries({
org,
hook_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
hook_id | yes |
The unique identifier of the hook. You can find this value in the |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
cursor | no |
Used for pagination: the starting delivery from which the page of deliveries is fetched. Refer to the |
redelivery | no |
See also: GitHub Developer Guide documentation.
List organization webhooks
You must be an organization owner to use this endpoint.
OAuth app tokens and personal access tokens (classic) need admin:org_hook
scope. OAuth apps cannot list, view, or edit
webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.
octokit.rest.orgs.listWebhooks({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
Update a custom organization role
Updates an existing custom organization role. Permission changes will apply to all assignees. For more information on custom organization roles, see "Managing people's access to your organization with roles."
To use this endpoint, the authenticated user must be one of:
- An administrator for the organization.
- A user, or a user on a team, with the fine-grained permissions of
write_organization_custom_org_role
in the organization.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.orgs.patchCustomOrganizationRole({
org,
role_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
role_id | yes |
The unique identifier of the role. |
name | no |
The name of the custom role. |
description | no |
A short description about the intended usage of this role or what permissions it grants. |
permissions | no |
A list of additional permissions included in this role. |
See also: GitHub Developer Guide documentation.
Ping an organization webhook
This will trigger a ping event to be sent to the hook.
You must be an organization owner to use this endpoint.
OAuth app tokens and personal access tokens (classic) need admin:org_hook
scope. OAuth apps cannot list, view, or edit
webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.
octokit.rest.orgs.pingWebhook({
org,
hook_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
hook_id | yes |
The unique identifier of the hook. You can find this value in the |
See also: GitHub Developer Guide documentation.
Redeliver a delivery for an organization webhook
Redeliver a delivery for a webhook configured in an organization.
You must be an organization owner to use this endpoint.
OAuth app tokens and personal access tokens (classic) need admin:org_hook
scope. OAuth apps cannot list, view, or edit
webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.
octokit.rest.orgs.redeliverWebhookDelivery({
org,
hook_id,
delivery_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
hook_id | yes |
The unique identifier of the hook. You can find this value in the |
delivery_id | yes |
See also: GitHub Developer Guide documentation.
Remove a custom property for an organization
Removes a custom property that is defined for an organization.
To use this endpoint, the authenticated user must be one of:
- An administrator for the organization.
- A user, or a user on a team, with the fine-grained permission of
custom_properties_org_definitions_manager
in the organization.
octokit.rest.orgs.removeCustomProperty({
org,
custom_property_name,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
custom_property_name | yes |
The custom property name. The name is case sensitive. |
See also: GitHub Developer Guide documentation.
Remove an organization member
Removing a user from this list will remove them from all teams and they will no longer have any access to the organization's repositories.
octokit.rest.orgs.removeMember({
org,
username,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
username | yes |
The handle for the GitHub user account. |
See also: GitHub Developer Guide documentation.
Remove organization membership for a user
In order to remove a user's membership with an organization, the authenticated user must be an organization owner.
If the specified user is an active member of the organization, this will remove them from the organization. If the specified user has been invited to the organization, this will cancel their invitation. The specified user will receive an email notification in both cases.
octokit.rest.orgs.removeMembershipForUser({
org,
username,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
username | yes |
The handle for the GitHub user account. |
See also: GitHub Developer Guide documentation.
Remove outside collaborator from an organization
Removing a user from this list will remove them from all the organization's repositories.
octokit.rest.orgs.removeOutsideCollaborator({
org,
username,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
username | yes |
The handle for the GitHub user account. |
See also: GitHub Developer Guide documentation.
Remove public organization membership for the authenticated user
Removes the public membership for the authenticated user from the specified organization, unless public visibility is enforced by default.
octokit.rest.orgs.removePublicMembershipForAuthenticatedUser({
org,
username,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
username | yes |
The handle for the GitHub user account. |
See also: GitHub Developer Guide documentation.
Remove a security manager team
Removes the security manager role from a team for an organization. For more information, see "Managing security managers in your organization team from an organization."
The authenticated user must be an administrator for the organization to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.orgs.removeSecurityManagerTeam({
org,
team_slug,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
team_slug | yes |
The slug of the team name. |
See also: GitHub Developer Guide documentation.
Review a request to access organization resources with a fine-grained personal access token
Approves or denies a pending request to access organization resources via a fine-grained personal access token.
Only GitHub Apps can use this endpoint.
octokit.rest.orgs.reviewPatGrantRequest({
org,
pat_request_id,
action,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
pat_request_id | yes |
Unique identifier of the request for access via fine-grained personal access token. |
action | yes |
Action to apply to the request. |
reason | no |
Reason for approving or denying the request. Max 1024 characters. |
See also: GitHub Developer Guide documentation.
Review requests to access organization resources with fine-grained personal access tokens
Approves or denies multiple pending requests to access organization resources via a fine-grained personal access token.
Only GitHub Apps can use this endpoint.
octokit.rest.orgs.reviewPatGrantRequestsInBulk({
org,
action,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
pat_request_ids | no |
Unique identifiers of the requests for access via fine-grained personal access token. Must be formed of between 1 and 100 |
action | yes |
Action to apply to the requests. |
reason | no |
Reason for approving or denying the requests. Max 1024 characters. |
See also: GitHub Developer Guide documentation.
Remove all organization roles for a team
Removes all assigned organization roles from a team. For more information on organization roles, see "Managing people's access to your organization with roles."
The authenticated user must be an administrator for the organization to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.orgs.revokeAllOrgRolesTeam({
org,
team_slug,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
team_slug | yes |
The slug of the team name. |
See also: GitHub Developer Guide documentation.
Remove all organization roles for a user
Revokes all assigned organization roles from a user. For more information on organization roles, see "Managing people's access to your organization with roles."
The authenticated user must be an administrator for the organization to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.orgs.revokeAllOrgRolesUser({
org,
username,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
username | yes |
The handle for the GitHub user account. |
See also: GitHub Developer Guide documentation.
Remove an organization role from a team
Removes an organization role from a team. For more information on organization roles, see "Managing people's access to your organization with roles."
The authenticated user must be an administrator for the organization to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.orgs.revokeOrgRoleTeam({
org,
team_slug,
role_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
team_slug | yes |
The slug of the team name. |
role_id | yes |
The unique identifier of the role. |
See also: GitHub Developer Guide documentation.
Remove an organization role from a user
Remove an organization role from a user. For more information on organization roles, see "Managing people's access to your organization with roles."
The authenticated user must be an administrator for the organization to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the admin:org
scope to use this endpoint.
octokit.rest.orgs.revokeOrgRoleUser({
org,
username,
role_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
username | yes |
The handle for the GitHub user account. |
role_id | yes |
The unique identifier of the role. |
See also: GitHub Developer Guide documentation.
Set organization membership for a user
Only authenticated organization owners can add a member to the organization or update the member's role.
- If the authenticated user is adding a member to the organization, the invited user will receive an email inviting them to the organization. The user's membership status will be
pending
until they accept the invitation. - Authenticated users can update a user's membership by passing the
role
parameter. If the authenticated user changes a member's role toadmin
, the affected user will receive an email notifying them that they've been made an organization owner. If the authenticated user changes an owner's role tomember
, no email will be sent.
Rate limits
To prevent abuse, the authenticated user is limited to 50 organization invitations per 24 hour period. If the organization is more than one month old or on a paid plan, the limit is 500 invitations per 24 hour period.
octokit.rest.orgs.setMembershipForUser({
org,
username,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
username | yes |
The handle for the GitHub user account. |
role | no |
The role to give the user in the organization. Can be one of:
|
See also: GitHub Developer Guide documentation.
Set public organization membership for the authenticated user
The user can publicize their own membership. (A user cannot publicize the membership for another user.)
Note that you'll need to set Content-Length
to zero when calling out to this endpoint. For more information, see "HTTP method."
octokit.rest.orgs.setPublicMembershipForAuthenticatedUser({
org,
username,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
username | yes |
The handle for the GitHub user account. |
See also: GitHub Developer Guide documentation.
Unblock a user from an organization
Unblocks the given user on behalf of the specified organization.
octokit.rest.orgs.unblockUser({
org,
username,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
username | yes |
The handle for the GitHub user account. |
See also: GitHub Developer Guide documentation.
Update an organization
Parameter Deprecation Notice: GitHub will replace and discontinue members_allowed_repository_creation_type
in favor of more granular permissions. The new input parameters are members_can_create_public_repositories
, members_can_create_private_repositories
for all organizations and members_can_create_internal_repositories
for organizations associated with an enterprise account using GitHub Enterprise Cloud or GitHub Enterprise Server 2.20+. For more information, see the blog post.
Updates the organization's profile and member privileges.
With security configurations (beta), your organization can choose a default security configuration which will automatically apply a set of security enablement settings to new repositories in your organization based on their visibility. For targeted repositories, the following attributes will be overridden by the default security configuration:
- advanced_security_enabled_for_new_repositories
- dependabot_alerts_enabled_for_new_repositories
- dependabot_security_updates_enabled_for_new_repositories
- dependency_graph_enabled_for_new_repositories
- secret_scanning_enabled_for_new_repositories
- secret_scanning_push_protection_enabled_for_new_repositories
For more information on setting a default security configuration, see "Enabling security features at scale."
The authenticated user must be an organization owner to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the admin:org
or repo
scope to use this endpoint.
octokit.rest.orgs.update({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
billing_email | no |
Billing email address. This address is not publicized. |
company | no |
The company name. |
no |
The publicly visible email address. | |
twitter_username | no |
The Twitter username of the company. |
location | no |
The location. |
name | no |
The shorthand name of the company. |
description | no |
The description of the company. The maximum size is 160 characters. |
has_organization_projects | no |
Whether an organization can use organization projects. |
has_repository_projects | no |
Whether repositories that belong to the organization can use repository projects. |
default_repository_permission | no |
Default permission level members have for organization repositories. |
members_can_create_repositories | no |
Whether of non-admin organization members can create repositories. Note: A parameter can override this parameter. See |
members_can_create_internal_repositories | no |
Whether organization members can create internal repositories, which are visible to all enterprise members. You can only allow members to create internal repositories if your organization is associated with an enterprise account using GitHub Enterprise Cloud or GitHub Enterprise Server 2.20+. For more information, see "Restricting repository creation in your organization" in the GitHub Help documentation. |
members_can_create_private_repositories | no |
Whether organization members can create private repositories, which are visible to organization members with permission. For more information, see "Restricting repository creation in your organization" in the GitHub Help documentation. |
members_can_create_public_repositories | no |
Whether organization members can create public repositories, which are visible to anyone. For more information, see "Restricting repository creation in your organization" in the GitHub Help documentation. |
members_allowed_repository_creation_type | no |
Specifies which types of repositories non-admin organization members can create. |
members_can_create_pages | no |
Whether organization members can create GitHub Pages sites. Existing published sites will not be impacted. |
members_can_create_public_pages | no |
Whether organization members can create public GitHub Pages sites. Existing published sites will not be impacted. |
members_can_create_private_pages | no |
Whether organization members can create private GitHub Pages sites. Existing published sites will not be impacted. |
members_can_fork_private_repositories | no |
Whether organization members can fork private organization repositories. |
web_commit_signoff_required | no |
Whether contributors to organization repositories are required to sign off on commits they make through GitHub's web interface. |
blog | no | |
advanced_security_enabled_for_new_repositories | no |
Whether GitHub Advanced Security is automatically enabled for new repositories. To use this parameter, you must have admin permissions for the repository or be an owner or security manager for the organization that owns the repository. For more information, see "Managing security managers in your organization." You can check which security and analysis features are currently enabled by using a |
dependabot_alerts_enabled_for_new_repositories | no |
Whether Dependabot alerts is automatically enabled for new repositories. To use this parameter, you must have admin permissions for the repository or be an owner or security manager for the organization that owns the repository. For more information, see "Managing security managers in your organization." You can check which security and analysis features are currently enabled by using a |
dependabot_security_updates_enabled_for_new_repositories | no |
Whether Dependabot security updates is automatically enabled for new repositories. To use this parameter, you must have admin permissions for the repository or be an owner or security manager for the organization that owns the repository. For more information, see "Managing security managers in your organization." You can check which security and analysis features are currently enabled by using a |
dependency_graph_enabled_for_new_repositories | no |
Whether dependency graph is automatically enabled for new repositories. To use this parameter, you must have admin permissions for the repository or be an owner or security manager for the organization that owns the repository. For more information, see "Managing security managers in your organization." You can check which security and analysis features are currently enabled by using a |
secret_scanning_enabled_for_new_repositories | no |
Whether secret scanning is automatically enabled for new repositories. To use this parameter, you must have admin permissions for the repository or be an owner or security manager for the organization that owns the repository. For more information, see "Managing security managers in your organization." You can check which security and analysis features are currently enabled by using a |
secret_scanning_push_protection_enabled_for_new_repositories | no |
Whether secret scanning push protection is automatically enabled for new repositories. To use this parameter, you must have admin permissions for the repository or be an owner or security manager for the organization that owns the repository. For more information, see "Managing security managers in your organization." You can check which security and analysis features are currently enabled by using a |
secret_scanning_push_protection_custom_link_enabled | no |
Whether a custom link is shown to contributors who are blocked from pushing a secret by push protection. |
secret_scanning_push_protection_custom_link | no |
If |
See also: GitHub Developer Guide documentation.
Update an organization membership for the authenticated user
Converts the authenticated user to an active member of the organization, if that user has a pending invitation from the organization.
octokit.rest.orgs.updateMembershipForAuthenticatedUser({
org,
state,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
state | yes |
The state that the membership should be in. Only |
See also: GitHub Developer Guide documentation.
Update the access a fine-grained personal access token has to organization resources
Updates the access an organization member has to organization resources via a fine-grained personal access token. Limited to revoking the token's existing access. Limited to revoking a token's existing access.
Only GitHub Apps can use this endpoint.
octokit.rest.orgs.updatePatAccess({
org,
pat_id,
action,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
pat_id | yes |
The unique identifier of the fine-grained personal access token. |
action | yes |
Action to apply to the fine-grained personal access token. |
See also: GitHub Developer Guide documentation.
Update the access to organization resources via fine-grained personal access tokens
Updates the access organization members have to organization resources via fine-grained personal access tokens. Limited to revoking a token's existing access.
Only GitHub Apps can use this endpoint.
octokit.rest.orgs.updatePatAccesses({
org,
action,
pat_ids,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
action | yes |
Action to apply to the fine-grained personal access token. |
pat_ids | yes |
The IDs of the fine-grained personal access tokens. |
See also: GitHub Developer Guide documentation.
Update an organization webhook
Updates a webhook configured in an organization. When you update a webhook,
the secret
will be overwritten. If you previously had a secret
set, you must
provide the same secret
or set a new secret
or the secret will be removed. If
you are only updating individual webhook config
properties, use "Update a webhook
configuration for an organization".
You must be an organization owner to use this endpoint.
OAuth app tokens and personal access tokens (classic) need admin:org_hook
scope. OAuth apps cannot list, view, or edit
webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.
octokit.rest.orgs.updateWebhook({
org,
hook_id,
config.url
})
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
hook_id | yes |
The unique identifier of the hook. You can find this value in the |
config | no |
Key/value pairs to provide settings for this webhook. |
config.url | yes |
The URL to which the payloads will be delivered. |
config.content_type | no |
The media type used to serialize the payloads. Supported values include |
config.secret | no |
If provided, the |
config.insecure_ssl | no | |
events | no |
Determines what events the hook is triggered for. |
active | no |
Determines if notifications are sent when the webhook is triggered. Set to |
name | no |
See also: GitHub Developer Guide documentation.
Update a webhook configuration for an organization
Updates the webhook configuration for an organization. To update more information about the webhook, including the active
state and events
, use "Update an organization webhook ."
You must be an organization owner to use this endpoint.
OAuth app tokens and personal access tokens (classic) need admin:org_hook
scope. OAuth apps cannot list, view, or edit
webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.
octokit.rest.orgs.updateWebhookConfigForOrg({
org,
hook_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
hook_id | yes |
The unique identifier of the hook. You can find this value in the |
url | no |
The URL to which the payloads will be delivered. |
content_type | no |
The media type used to serialize the payloads. Supported values include |
secret | no |
If provided, the |
insecure_ssl | no |
See also: GitHub Developer Guide documentation.
Packages
Delete a package for the authenticated user
Deletes a package owned by the authenticated user. You cannot delete a public package if any version of the package has more than 5,000 downloads. In this scenario, contact GitHub support for further assistance.
OAuth app tokens and personal access tokens (classic) need the read:packages
and delete:packages
scopes to use this endpoint. If the package_type
belongs to a GitHub Packages registry that only supports repository-scoped permissions, repo
scope is also required. For the list these registries, see "About permissions for GitHub Packages."
octokit.rest.packages.deletePackageForAuthenticatedUser({
package_type,
package_name,
});
Parameters
name | required | description |
---|---|---|
package_type | yes |
The type of supported package. Packages in GitHub's Gradle registry have the type |
package_name | yes |
The name of the package. |
See also: GitHub Developer Guide documentation.
Delete a package for an organization
Deletes an entire package in an organization. You cannot delete a public package if any version of the package has more than 5,000 downloads. In this scenario, contact GitHub support for further assistance.
The authenticated user must have admin permissions in the organization to use this endpoint. If the package_type
belongs to a GitHub Packages registry that supports granular permissions, the authenticated user must also have admin permissions to the package. For the list of these registries, see "About permissions for GitHub Packages."
OAuth app tokens and personal access tokens (classic) need the read:packages
and delete:packages
scopes to use this endpoint. If the package_type
belongs to a GitHub Packages registry that only supports repository-scoped permissions, the repo
scope is also required. For the list of these registries, see "About permissions for GitHub Packages."
octokit.rest.packages.deletePackageForOrg({
package_type,
package_name,
org,
});
Parameters
name | required | description |
---|---|---|
package_type | yes |
The type of supported package. Packages in GitHub's Gradle registry have the type |
package_name | yes |
The name of the package. |
org | yes |
The organization name. The name is not case sensitive. |
See also: GitHub Developer Guide documentation.
Delete a package for a user
Deletes an entire package for a user. You cannot delete a public package if any version of the package has more than 5,000 downloads. In this scenario, contact GitHub support for further assistance.
If the package_type
belongs to a GitHub Packages registry that supports granular permissions, the authenticated user must have admin permissions to the package. For the list of these registries, see "About permissions for GitHub Packages."
OAuth app tokens and personal access tokens (classic) need the read:packages
and delete:packages
scopes to use this endpoint. If the package_type
belongs to a GitHub Packages registry that only supports repository-scoped permissions, the repo
scope is also required. For the list of these registries, see "About permissions for GitHub Packages."
octokit.rest.packages.deletePackageForUser({
package_type,
package_name,
username,
});
Parameters
name | required | description |
---|---|---|
package_type | yes |
The type of supported package. Packages in GitHub's Gradle registry have the type |
package_name | yes |
The name of the package. |
username | yes |
The handle for the GitHub user account. |
See also: GitHub Developer Guide documentation.
Delete a package version for the authenticated user
Deletes a specific package version for a package owned by the authenticated user. If the package is public and the package version has more than 5,000 downloads, you cannot delete the package version. In this scenario, contact GitHub support for further assistance.
The authenticated user must have admin permissions in the organization to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the read:packages
and delete:packages
scopes to use this endpoint. If the package_type
belongs to a GitHub Packages registry that only supports repository-scoped permissions, the repo
scope is also required. For the list of these registries, see "About permissions for GitHub Packages."
octokit.rest.packages.deletePackageVersionForAuthenticatedUser({
package_type,
package_name,
package_version_id,
});
Parameters
name | required | description |
---|---|---|
package_type | yes |
The type of supported package. Packages in GitHub's Gradle registry have the type |
package_name | yes |
The name of the package. |
package_version_id | yes |
Unique identifier of the package version. |
See also: GitHub Developer Guide documentation.
Delete package version for an organization
Deletes a specific package version in an organization. If the package is public and the package version has more than 5,000 downloads, you cannot delete the package version. In this scenario, contact GitHub support for further assistance.
The authenticated user must have admin permissions in the organization to use this endpoint. If the package_type
belongs to a GitHub Packages registry that supports granular permissions, the authenticated user must also have admin permissions to the package. For the list of these registries, see "About permissions for GitHub Packages."
OAuth app tokens and personal access tokens (classic) need the read:packages
and delete:packages
scopes to use this endpoint. If the package_type
belongs to a GitHub Packages registry that only supports repository-scoped permissions, the repo
scope is also required. For the list of these registries, see "About permissions for GitHub Packages."
octokit.rest.packages.deletePackageVersionForOrg({
package_type,
package_name,
org,
package_version_id,
});
Parameters
name | required | description |
---|---|---|
package_type | yes |
The type of supported package. Packages in GitHub's Gradle registry have the type |
package_name | yes |
The name of the package. |
org | yes |
The organization name. The name is not case sensitive. |
package_version_id | yes |
Unique identifier of the package version. |
See also: GitHub Developer Guide documentation.
Delete package version for a user
Deletes a specific package version for a user. If the package is public and the package version has more than 5,000 downloads, you cannot delete the package version. In this scenario, contact GitHub support for further assistance.
If the package_type
belongs to a GitHub Packages registry that supports granular permissions, the authenticated user must have admin permissions to the package. For the list of these registries, see "About permissions for GitHub Packages."
OAuth app tokens and personal access tokens (classic) need the read:packages
and delete:packages
scopes to use this endpoint. If the package_type
belongs to a GitHub Packages registry that only supports repository-scoped permissions, the repo
scope is also required. For the list of these registries, see "About permissions for GitHub Packages."
octokit.rest.packages.deletePackageVersionForUser({
package_type,
package_name,
username,
package_version_id,
});
Parameters
name | required | description |
---|---|---|
package_type | yes |
The type of supported package. Packages in GitHub's Gradle registry have the type |
package_name | yes |
The name of the package. |
username | yes |
The handle for the GitHub user account. |
package_version_id | yes |
Unique identifier of the package version. |
See also: GitHub Developer Guide documentation.
List package versions for a package owned by an organization
Deprecated: This method has been renamed to packages.getAllPackageVersionsForPackageOwnedByOrg
Lists package versions for a package owned by an organization.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint if the package_type
belongs to a GitHub Packages registry that only supports repository-scoped permissions. For the list of these registries, see "About permissions for GitHub Packages."
octokit.rest.packages.getAllPackageVersionsForAPackageOwnedByAnOrg({
package_type,
package_name,
org,
});
Parameters
name | required | description |
---|---|---|
package_type | yes |
The type of supported package. Packages in GitHub's Gradle registry have the type |
package_name | yes |
The name of the package. |
org | yes |
The organization name. The name is not case sensitive. |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
state | no |
The state of the package, either active or deleted. |
See also: GitHub Developer Guide documentation.
List package versions for a package owned by the authenticated user
Deprecated: This method has been renamed to packages.getAllPackageVersionsForPackageOwnedByAuthenticatedUser
Lists package versions for a package owned by the authenticated user.
OAuth app tokens and personal access tokens (classic) need the read:packages
scope to use this endpoint. If the package_type
belongs to a GitHub Packages registry that only supports repository-scoped permissions, the repo
scope is also required. For the list of these registries, see "About permissions for GitHub Packages."
octokit.rest.packages.getAllPackageVersionsForAPackageOwnedByTheAuthenticatedUser(
{
package_type,
package_name,
},
);
Parameters
name | required | description |
---|---|---|
package_type | yes |
The type of supported package. Packages in GitHub's Gradle registry have the type |
package_name | yes |
The name of the package. |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
state | no |
The state of the package, either active or deleted. |
See also: GitHub Developer Guide documentation.
List package versions for a package owned by the authenticated user
Lists package versions for a package owned by the authenticated user.
OAuth app tokens and personal access tokens (classic) need the read:packages
scope to use this endpoint. If the package_type
belongs to a GitHub Packages registry that only supports repository-scoped permissions, the repo
scope is also required. For the list of these registries, see "About permissions for GitHub Packages."
octokit.rest.packages.getAllPackageVersionsForPackageOwnedByAuthenticatedUser({
package_type,
package_name,
});
Parameters
name | required | description |
---|---|---|
package_type | yes |
The type of supported package. Packages in GitHub's Gradle registry have the type |
package_name | yes |
The name of the package. |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
state | no |
The state of the package, either active or deleted. |
See also: GitHub Developer Guide documentation.
List package versions for a package owned by an organization
Lists package versions for a package owned by an organization.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint if the package_type
belongs to a GitHub Packages registry that only supports repository-scoped permissions. For the list of these registries, see "About permissions for GitHub Packages."
octokit.rest.packages.getAllPackageVersionsForPackageOwnedByOrg({
package_type,
package_name,
org,
});
Parameters
name | required | description |
---|---|---|
package_type | yes |
The type of supported package. Packages in GitHub's Gradle registry have the type |
package_name | yes |
The name of the package. |
org | yes |
The organization name. The name is not case sensitive. |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
state | no |
The state of the package, either active or deleted. |
See also: GitHub Developer Guide documentation.
List package versions for a package owned by a user
Lists package versions for a public package owned by a specified user.
OAuth app tokens and personal access tokens (classic) need the read:packages
scope to use this endpoint. If the package_type
belongs to a GitHub Packages registry that only supports repository-scoped permissions, the repo
scope is also required. For the list of these registries, see "About permissions for GitHub Packages."
octokit.rest.packages.getAllPackageVersionsForPackageOwnedByUser({
package_type,
package_name,
username,
});
Parameters
name | required | description |
---|---|---|
package_type | yes |
The type of supported package. Packages in GitHub's Gradle registry have the type |
package_name | yes |
The name of the package. |
username | yes |
The handle for the GitHub user account. |
See also: GitHub Developer Guide documentation.
Get a package for the authenticated user
Gets a specific package for a package owned by the authenticated user.
OAuth app tokens and personal access tokens (classic) need the read:packages
scope to use this endpoint. If the package_type
belongs to a GitHub Packages registry that only supports repository-scoped permissions, the repo
scope is also required. For the list of these registries, see "About permissions for GitHub Packages."
octokit.rest.packages.getPackageForAuthenticatedUser({
package_type,
package_name,
});
Parameters
name | required | description |
---|---|---|
package_type | yes |
The type of supported package. Packages in GitHub's Gradle registry have the type |
package_name | yes |
The name of the package. |
See also: GitHub Developer Guide documentation.
Get a package for an organization
Gets a specific package in an organization.
OAuth app tokens and personal access tokens (classic) need the read:packages
scope to use this endpoint. If the package_type
belongs to a GitHub Packages registry that only supports repository-scoped permissions, the repo
scope is also required. For the list of these registries, see "About permissions for GitHub Packages."
octokit.rest.packages.getPackageForOrganization({
package_type,
package_name,
org,
});
Parameters
name | required | description |
---|---|---|
package_type | yes |
The type of supported package. Packages in GitHub's Gradle registry have the type |
package_name | yes |
The name of the package. |
org | yes |
The organization name. The name is not case sensitive. |
See also: GitHub Developer Guide documentation.
Get a package for a user
Gets a specific package metadata for a public package owned by a user.
OAuth app tokens and personal access tokens (classic) need the read:packages
scope to use this endpoint. If the package_type
belongs to a GitHub Packages registry that only supports repository-scoped permissions, the repo
scope is also required. For the list of these registries, see "About permissions for GitHub Packages."
octokit.rest.packages.getPackageForUser({
package_type,
package_name,
username,
});
Parameters
name | required | description |
---|---|---|
package_type | yes |
The type of supported package. Packages in GitHub's Gradle registry have the type |
package_name | yes |
The name of the package. |
username | yes |
The handle for the GitHub user account. |
See also: GitHub Developer Guide documentation.
Get a package version for the authenticated user
Gets a specific package version for a package owned by the authenticated user.
OAuth app tokens and personal access tokens (classic) need the read:packages
scope to use this endpoint. If the package_type
belongs to a GitHub Packages registry that only supports repository-scoped permissions, the repo
scope is also required. For the list of these registries, see "About permissions for GitHub Packages."
octokit.rest.packages.getPackageVersionForAuthenticatedUser({
package_type,
package_name,
package_version_id,
});
Parameters
name | required | description |
---|---|---|
package_type | yes |
The type of supported package. Packages in GitHub's Gradle registry have the type |
package_name | yes |
The name of the package. |
package_version_id | yes |
Unique identifier of the package version. |
See also: GitHub Developer Guide documentation.
Get a package version for an organization
Gets a specific package version in an organization.
OAuth app tokens and personal access tokens (classic) need the read:packages
scope to use this endpoint. If the package_type
belongs to a GitHub Packages registry that only supports repository-scoped permissions, the repo
scope is also required. For the list of these registries, see "About permissions for GitHub Packages."
octokit.rest.packages.getPackageVersionForOrganization({
package_type,
package_name,
org,
package_version_id,
});
Parameters
name | required | description |
---|---|---|
package_type | yes |
The type of supported package. Packages in GitHub's Gradle registry have the type |
package_name | yes |
The name of the package. |
org | yes |
The organization name. The name is not case sensitive. |
package_version_id | yes |
Unique identifier of the package version. |
See also: GitHub Developer Guide documentation.
Get a package version for a user
Gets a specific package version for a public package owned by a specified user.
OAuth app tokens and personal access tokens (classic) need the read:packages
scope to use this endpoint. If the package_type
belongs to a GitHub Packages registry that only supports repository-scoped permissions, the repo
scope is also required. For the list of these registries, see "About permissions for GitHub Packages."
octokit.rest.packages.getPackageVersionForUser({
package_type,
package_name,
package_version_id,
username,
});
Parameters
name | required | description |
---|---|---|
package_type | yes |
The type of supported package. Packages in GitHub's Gradle registry have the type |
package_name | yes |
The name of the package. |
package_version_id | yes |
Unique identifier of the package version. |
username | yes |
The handle for the GitHub user account. |
See also: GitHub Developer Guide documentation.
Get list of conflicting packages during Docker migration for authenticated-user
Lists all packages that are owned by the authenticated user within the user's namespace, and that encountered a conflict during a Docker migration.
OAuth app tokens and personal access tokens (classic) need the read:packages
scope to use this endpoint.
octokit.rest.packages.listDockerMigrationConflictingPackagesForAuthenticatedUser();
Parameters
This endpoint has no parameters
See also: GitHub Developer Guide documentation.
Get list of conflicting packages during Docker migration for organization
Lists all packages that are in a specific organization, are readable by the requesting user, and that encountered a conflict during a Docker migration.
OAuth app tokens and personal access tokens (classic) need the read:packages
scope to use this endpoint.
octokit.rest.packages.listDockerMigrationConflictingPackagesForOrganization({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
See also: GitHub Developer Guide documentation.
Get list of conflicting packages during Docker migration for user
Lists all packages that are in a specific user's namespace, that the requesting user has access to, and that encountered a conflict during Docker migration.
OAuth app tokens and personal access tokens (classic) need the read:packages
scope to use this endpoint.
octokit.rest.packages.listDockerMigrationConflictingPackagesForUser({
username,
});
Parameters
name | required | description |
---|---|---|
username | yes |
The handle for the GitHub user account. |
See also: GitHub Developer Guide documentation.
List packages for the authenticated user's namespace
Lists packages owned by the authenticated user within the user's namespace.
OAuth app tokens and personal access tokens (classic) need the read:packages
scope to use this endpoint. If the package_type
belongs to a GitHub Packages registry that only supports repository-scoped permissions, the repo
scope is also required. For the list of these registries, see "About permissions for GitHub Packages."
octokit.rest.packages.listPackagesForAuthenticatedUser({
package_type,
});
Parameters
name | required | description |
---|---|---|
package_type | yes |
The type of supported package. Packages in GitHub's Gradle registry have the type |
visibility | no |
The selected visibility of the packages. This parameter is optional and only filters an existing result set. The |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List packages for an organization
Lists packages in an organization readable by the user.
OAuth app tokens and personal access tokens (classic) need the read:packages
scope to use this endpoint. If the package_type
belongs to a GitHub Packages registry that only supports repository-scoped permissions, the repo
scope is also required. For the list of these registries, see "About permissions for GitHub Packages."
octokit.rest.packages.listPackagesForOrganization({
package_type,
org,
});
Parameters
name | required | description |
---|---|---|
package_type | yes |
The type of supported package. Packages in GitHub's Gradle registry have the type |
org | yes |
The organization name. The name is not case sensitive. |
visibility | no |
The selected visibility of the packages. This parameter is optional and only filters an existing result set. The |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List packages for a user
Lists all packages in a user's namespace for which the requesting user has access.
OAuth app tokens and personal access tokens (classic) need the read:packages
scope to use this endpoint. If the package_type
belongs to a GitHub Packages registry that only supports repository-scoped permissions, the repo
scope is also required. For the list of these registries, see "About permissions for GitHub Packages."
octokit.rest.packages.listPackagesForUser({
package_type,
username,
});
Parameters
name | required | description |
---|---|---|
package_type | yes |
The type of supported package. Packages in GitHub's Gradle registry have the type |
visibility | no |
The selected visibility of the packages. This parameter is optional and only filters an existing result set. The |
username | yes |
The handle for the GitHub user account. |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
Restore a package for the authenticated user
Restores a package owned by the authenticated user.
You can restore a deleted package under the following conditions:
- The package was deleted within the last 30 days.
- The same package namespace and version is still available and not reused for a new package. If the same package namespace is not available, you will not be able to restore your package. In this scenario, to restore the deleted package, you must delete the new package that uses the deleted package's namespace first.
OAuth app tokens and personal access tokens (classic) need the read:packages
and write:packages
scopes to use this endpoint. If the package_type
belongs to a GitHub Packages registry that only supports repository-scoped permissions, the repo
scope is also required. For the list of these registries, see "About permissions for GitHub Packages."
octokit.rest.packages.restorePackageForAuthenticatedUser({
package_type,
package_name,
});
Parameters
name | required | description |
---|---|---|
package_type | yes |
The type of supported package. Packages in GitHub's Gradle registry have the type |
package_name | yes |
The name of the package. |
token | no |
package token |
See also: GitHub Developer Guide documentation.
Restore a package for an organization
Restores an entire package in an organization.
You can restore a deleted package under the following conditions:
- The package was deleted within the last 30 days.
- The same package namespace and version is still available and not reused for a new package. If the same package namespace is not available, you will not be able to restore your package. In this scenario, to restore the deleted package, you must delete the new package that uses the deleted package's namespace first.
The authenticated user must have admin permissions in the organization to use this endpoint. If the package_type
belongs to a GitHub Packages registry that supports granular permissions, the authenticated user must also have admin permissions to the package. For the list of these registries, see "About permissions for GitHub Packages."
OAuth app tokens and personal access tokens (classic) need the read:packages
and write:packages
scopes to use this endpoint. If the package_type
belongs to a GitHub Packages registry that only supports repository-scoped permissions, the repo
scope is also required. For the list of these registries, see "About permissions for GitHub Packages."
octokit.rest.packages.restorePackageForOrg({
package_type,
package_name,
org,
});
Parameters
name | required | description |
---|---|---|
package_type | yes |
The type of supported package. Packages in GitHub's Gradle registry have the type |
package_name | yes |
The name of the package. |
org | yes |
The organization name. The name is not case sensitive. |
token | no |
package token |
See also: GitHub Developer Guide documentation.
Restore a package for a user
Restores an entire package for a user.
You can restore a deleted package under the following conditions:
- The package was deleted within the last 30 days.
- The same package namespace and version is still available and not reused for a new package. If the same package namespace is not available, you will not be able to restore your package. In this scenario, to restore the deleted package, you must delete the new package that uses the deleted package's namespace first.
If the package_type
belongs to a GitHub Packages registry that supports granular permissions, the authenticated user must have admin permissions to the package. For the list of these registries, see "About permissions for GitHub Packages."
OAuth app tokens and personal access tokens (classic) need the read:packages
and write:packages
scopes to use this endpoint. If the package_type
belongs to a GitHub Packages registry that only supports repository-scoped permissions, the repo
scope is also required. For the list of these registries, see "About permissions for GitHub Packages."
octokit.rest.packages.restorePackageForUser({
package_type,
package_name,
username,
});
Parameters
name | required | description |
---|---|---|
package_type | yes |
The type of supported package. Packages in GitHub's Gradle registry have the type |
package_name | yes |
The name of the package. |
username | yes |
The handle for the GitHub user account. |
token | no |
package token |
See also: GitHub Developer Guide documentation.
Restore a package version for the authenticated user
Restores a package version owned by the authenticated user.
You can restore a deleted package version under the following conditions:
- The package was deleted within the last 30 days.
- The same package namespace and version is still available and not reused for a new package. If the same package namespace is not available, you will not be able to restore your package. In this scenario, to restore the deleted package, you must delete the new package that uses the deleted package's namespace first.
OAuth app tokens and personal access tokens (classic) need the read:packages
and write:packages
scopes to use this endpoint. If the package_type
belongs to a GitHub Packages registry that only supports repository-scoped permissions, the repo
scope is also required. For the list of these registries, see "About permissions for GitHub Packages."
octokit.rest.packages.restorePackageVersionForAuthenticatedUser({
package_type,
package_name,
package_version_id,
});
Parameters
name | required | description |
---|---|---|
package_type | yes |
The type of supported package. Packages in GitHub's Gradle registry have the type |
package_name | yes |
The name of the package. |
package_version_id | yes |
Unique identifier of the package version. |
See also: GitHub Developer Guide documentation.
Restore package version for an organization
Restores a specific package version in an organization.
You can restore a deleted package under the following conditions:
- The package was deleted within the last 30 days.
- The same package namespace and version is still available and not reused for a new package. If the same package namespace is not available, you will not be able to restore your package. In this scenario, to restore the deleted package, you must delete the new package that uses the deleted package's namespace first.
The authenticated user must have admin permissions in the organization to use this endpoint. If the package_type
belongs to a GitHub Packages registry that supports granular permissions, the authenticated user must also have admin permissions to the package. For the list of these registries, see "About permissions for GitHub Packages."
OAuth app tokens and personal access tokens (classic) need the read:packages
and write:packages
scopes to use this endpoint. If the package_type
belongs to a GitHub Packages registry that only supports repository-scoped permissions, the repo
scope is also required. For the list of these registries, see "About permissions for GitHub Packages."
octokit.rest.packages.restorePackageVersionForOrg({
package_type,
package_name,
org,
package_version_id,
});
Parameters
name | required | description |
---|---|---|
package_type | yes |
The type of supported package. Packages in GitHub's Gradle registry have the type |
package_name | yes |
The name of the package. |
org | yes |
The organization name. The name is not case sensitive. |
package_version_id | yes |
Unique identifier of the package version. |
See also: GitHub Developer Guide documentation.
Restore package version for a user
Restores a specific package version for a user.
You can restore a deleted package under the following conditions:
- The package was deleted within the last 30 days.
- The same package namespace and version is still available and not reused for a new package. If the same package namespace is not available, you will not be able to restore your package. In this scenario, to restore the deleted package, you must delete the new package that uses the deleted package's namespace first.
If the package_type
belongs to a GitHub Packages registry that supports granular permissions, the authenticated user must have admin permissions to the package. For the list of these registries, see "About permissions for GitHub Packages."
OAuth app tokens and personal access tokens (classic) need the read:packages
and write:packages
scopes to use this endpoint. If the package_type
belongs to a GitHub Packages registry that only supports repository-scoped permissions, the repo
scope is also required. For the list of these registries, see "About permissions for GitHub Packages."
octokit.rest.packages.restorePackageVersionForUser({
package_type,
package_name,
username,
package_version_id,
});
Parameters
name | required | description |
---|---|---|
package_type | yes |
The type of supported package. Packages in GitHub's Gradle registry have the type |
package_name | yes |
The name of the package. |
username | yes |
The handle for the GitHub user account. |
package_version_id | yes |
Unique identifier of the package version. |
See also: GitHub Developer Guide documentation.
Projects
Add project collaborator
Adds a collaborator to an organization project and sets their permission level. You must be an organization owner or a project admin
to add a collaborator.
octokit.rest.projects.addCollaborator({
project_id,
username,
});
Parameters
name | required | description |
---|---|---|
project_id | yes |
The unique identifier of the project. |
username | yes |
The handle for the GitHub user account. |
permission | no |
The permission to grant the collaborator. |
See also: GitHub Developer Guide documentation.
Create a project card
octokit.rest.projects.createCard({
column_id,
note,
content_id,
content_type,
});
Parameters
name | required | description |
---|---|---|
column_id | yes |
The unique identifier of the column. |
note | yes |
The project card's note |
content_id | yes |
The unique identifier of the content associated with the card |
content_type | yes |
The piece of content associated with the card |
See also: GitHub Developer Guide documentation.
Create a project column
Creates a new project column.
octokit.rest.projects.createColumn({
project_id,
name,
});
Parameters
name | required | description |
---|---|---|
project_id | yes |
The unique identifier of the project. |
name | yes |
Name of the project column |
See also: GitHub Developer Guide documentation.
Create a user project
Creates a user project board. Returns a 410 Gone
status if the user does not have existing classic projects. If you do not have sufficient privileges to perform this action, a 401 Unauthorized
or 410 Gone
status is returned.
octokit.rest.projects.createForAuthenticatedUser({
name,
});
Parameters
name | required | description |
---|---|---|
name | yes |
Name of the project |
body | no |
Body of the project |
See also: GitHub Developer Guide documentation.
Create an organization project
Creates an organization project board. Returns a 410 Gone
status if projects are disabled in the organization or if the organization does not have existing classic projects. If you do not have sufficient privileges to perform this action, a 401 Unauthorized
or 410 Gone
status is returned.
octokit.rest.projects.createForOrg({
org,
name,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
name | yes |
The name of the project. |
body | no |
The description of the project. |
See also: GitHub Developer Guide documentation.
Create a repository project
Creates a repository project board. Returns a 410 Gone
status if projects are disabled in the repository or if the repository does not have existing classic projects. If you do not have sufficient privileges to perform this action, a 401 Unauthorized
or 410 Gone
status is returned.
octokit.rest.projects.createForRepo({
owner,
repo,
name,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
name | yes |
The name of the project. |
body | no |
The description of the project. |
See also: GitHub Developer Guide documentation.
Delete a project
Deletes a project board. Returns a 404 Not Found
status if projects are disabled.
octokit.rest.projects.delete({
project_id,
});
Parameters
name | required | description |
---|---|---|
project_id | yes |
The unique identifier of the project. |
See also: GitHub Developer Guide documentation.
Delete a project card
Deletes a project card
octokit.rest.projects.deleteCard({
card_id,
});
Parameters
name | required | description |
---|---|---|
card_id | yes |
The unique identifier of the card. |
See also: GitHub Developer Guide documentation.
Delete a project column
Deletes a project column.
octokit.rest.projects.deleteColumn({
column_id,
});
Parameters
name | required | description |
---|---|---|
column_id | yes |
The unique identifier of the column. |
See also: GitHub Developer Guide documentation.
Get a project
Gets a project by its id
. Returns a 404 Not Found
status if projects are disabled. If you do not have sufficient privileges to perform this action, a 401 Unauthorized
or 410 Gone
status is returned.
octokit.rest.projects.get({
project_id,
});
Parameters
name | required | description |
---|---|---|
project_id | yes |
The unique identifier of the project. |
See also: GitHub Developer Guide documentation.
Get a project card
Gets information about a project card.
octokit.rest.projects.getCard({
card_id,
});
Parameters
name | required | description |
---|---|---|
card_id | yes |
The unique identifier of the card. |
See also: GitHub Developer Guide documentation.
Get a project column
Gets information about a project column.
octokit.rest.projects.getColumn({
column_id,
});
Parameters
name | required | description |
---|---|---|
column_id | yes |
The unique identifier of the column. |
See also: GitHub Developer Guide documentation.
Get project permission for a user
Returns the collaborator's permission level for an organization project. Possible values for the permission
key: admin
, write
, read
, none
. You must be an organization owner or a project admin
to review a user's permission level.
octokit.rest.projects.getPermissionForUser({
project_id,
username,
});
Parameters
name | required | description |
---|---|---|
project_id | yes |
The unique identifier of the project. |
username | yes |
The handle for the GitHub user account. |
See also: GitHub Developer Guide documentation.
List project cards
Lists the project cards in a project.
octokit.rest.projects.listCards({
column_id,
});
Parameters
name | required | description |
---|---|---|
column_id | yes |
The unique identifier of the column. |
archived_state | no |
Filters the project cards that are returned by the card's state. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List project collaborators
Lists the collaborators for an organization project. For a project, the list of collaborators includes outside collaborators, organization members that are direct collaborators, organization members with access through team memberships, organization members with access through default organization permissions, and organization owners. You must be an organization owner or a project admin
to list collaborators.
octokit.rest.projects.listCollaborators({
project_id,
});
Parameters
name | required | description |
---|---|---|
project_id | yes |
The unique identifier of the project. |
affiliation | no |
Filters the collaborators by their affiliation. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List project columns
Lists the project columns in a project.
octokit.rest.projects.listColumns({
project_id,
});
Parameters
name | required | description |
---|---|---|
project_id | yes |
The unique identifier of the project. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List organization projects
Lists the projects in an organization. Returns a 404 Not Found
status if projects are disabled in the organization. If you do not have sufficient privileges to perform this action, a 401 Unauthorized
or 410 Gone
status is returned.
octokit.rest.projects.listForOrg({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
state | no |
Indicates the state of the projects to return. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List repository projects
Lists the projects in a repository. Returns a 404 Not Found
status if projects are disabled in the repository. If you do not have sufficient privileges to perform this action, a 401 Unauthorized
or 410 Gone
status is returned.
octokit.rest.projects.listForRepo({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
state | no |
Indicates the state of the projects to return. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List user projects
Lists projects for a user.
octokit.rest.projects.listForUser({
username,
});
Parameters
name | required | description |
---|---|---|
username | yes |
The handle for the GitHub user account. |
state | no |
Indicates the state of the projects to return. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
Move a project card
octokit.rest.projects.moveCard({
card_id,
position,
});
Parameters
name | required | description |
---|---|---|
card_id | yes |
The unique identifier of the card. |
position | yes |
The position of the card in a column. Can be one of: |
column_id | no |
The unique identifier of the column the card should be moved to |
See also: GitHub Developer Guide documentation.
Move a project column
octokit.rest.projects.moveColumn({
column_id,
position,
});
Parameters
name | required | description |
---|---|---|
column_id | yes |
The unique identifier of the column. |
position | yes |
The position of the column in a project. Can be one of: |
See also: GitHub Developer Guide documentation.
Remove user as a collaborator
Removes a collaborator from an organization project. You must be an organization owner or a project admin
to remove a collaborator.
octokit.rest.projects.removeCollaborator({
project_id,
username,
});
Parameters
name | required | description |
---|---|---|
project_id | yes |
The unique identifier of the project. |
username | yes |
The handle for the GitHub user account. |
See also: GitHub Developer Guide documentation.
Update a project
Updates a project board's information. Returns a 404 Not Found
status if projects are disabled. If you do not have sufficient privileges to perform this action, a 401 Unauthorized
or 410 Gone
status is returned.
octokit.rest.projects.update({
project_id,
});
Parameters
name | required | description |
---|---|---|
project_id | yes |
The unique identifier of the project. |
name | no |
Name of the project |
body | no |
Body of the project |
state | no |
State of the project; either 'open' or 'closed' |
organization_permission | no |
The baseline permission that all organization members have on this project |
private | no |
Whether or not this project can be seen by everyone. |
See also: GitHub Developer Guide documentation.
Update an existing project card
octokit.rest.projects.updateCard({
card_id,
});
Parameters
name | required | description |
---|---|---|
card_id | yes |
The unique identifier of the card. |
note | no |
The project card's note |
archived | no |
Whether or not the card is archived |
See also: GitHub Developer Guide documentation.
Update an existing project column
octokit.rest.projects.updateColumn({
column_id,
name,
});
Parameters
name | required | description |
---|---|---|
column_id | yes |
The unique identifier of the column. |
name | yes |
Name of the project column |
See also: GitHub Developer Guide documentation.
Pulls
Check if a pull request has been merged
Checks if a pull request has been merged into the base branch. The HTTP status of the response indicates whether or not the pull request has been merged; the response body is empty.
octokit.rest.pulls.checkIfMerged({
owner,
repo,
pull_number,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
pull_number | yes |
The number that identifies the pull request. |
See also: GitHub Developer Guide documentation.
Create a pull request
Draft pull requests are available in public repositories with GitHub Free and GitHub Free for organizations, GitHub Pro, and legacy per-repository billing plans, and in public and private repositories with GitHub Team and GitHub Enterprise Cloud. For more information, see GitHub's products in the GitHub Help documentation.
To open or update a pull request in a public repository, you must have write access to the head or the source branch. For organization-owned repositories, you must be a member of the organization that owns the repository to open or update a pull request.
This endpoint triggers notifications. Creating content too quickly using this endpoint may result in secondary rate limiting. For more information, see "Rate limits for the API" and "Best practices for using the REST API."
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github.raw+json
: Returns the raw markdown body. Response will includebody
. This is the default if you do not pass any specific media type.application/vnd.github.text+json
: Returns a text only representation of the markdown body. Response will includebody_text
.application/vnd.github.html+json
: Returns HTML rendered from the body's markdown. Response will includebody_html
.application/vnd.github.full+json
: Returns raw, text, and HTML representations. Response will includebody
,body_text
, andbody_html
.
octokit.rest.pulls.create({
owner,
repo,
head,
base,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
title | no |
The title of the new pull request. Required unless |
head | yes |
The name of the branch where your changes are implemented. For cross-repository pull requests in the same network, namespace |
head_repo | no |
The name of the repository where the changes in the pull request were made. This field is required for cross-repository pull requests if both repositories are owned by the same organization. |
base | yes |
The name of the branch you want the changes pulled into. This should be an existing branch on the current repository. You cannot submit a pull request to one repository that requests a merge to a base of another repository. |
body | no |
The contents of the pull request. |
maintainer_can_modify | no |
Indicates whether maintainers can modify the pull request. |
draft | no |
Indicates whether the pull request is a draft. See "Draft Pull Requests" in the GitHub Help documentation to learn more. |
issue | no |
An issue in the repository to convert to a pull request. The issue title, body, and comments will become the title, body, and comments on the new pull request. Required unless |
See also: GitHub Developer Guide documentation.
Create a reply for a review comment
Creates a reply to a review comment for a pull request. For the comment_id
, provide the ID of the review comment you are replying to. This must be the ID of a top-level review comment, not a reply to that comment. Replies to replies are not supported.
This endpoint triggers notifications. Creating content too quickly using this endpoint may result in secondary rate limiting. For more information, see "Rate limits for the API" and "Best practices for using the REST API."
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github-commitcomment.raw+json
: Returns the raw markdown body. Response will includebody
. This is the default if you do not pass any specific media type.application/vnd.github-commitcomment.text+json
: Returns a text only representation of the markdown body. Response will includebody_text
.application/vnd.github-commitcomment.html+json
: Returns HTML rendered from the body's markdown. Response will includebody_html
.application/vnd.github-commitcomment.full+json
: Returns raw, text, and HTML representations. Response will includebody
,body_text
, andbody_html
.
octokit.rest.pulls.createReplyForReviewComment({
owner,
repo,
pull_number,
comment_id,
body,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
pull_number | yes |
The number that identifies the pull request. |
comment_id | yes |
The unique identifier of the comment. |
body | yes |
The text of the review comment. |
See also: GitHub Developer Guide documentation.
Create a review for a pull request
Creates a review on a specified pull request.
This endpoint triggers notifications. Creating content too quickly using this endpoint may result in secondary rate limiting. For more information, see "Rate limits for the API" and "Best practices for using the REST API."
Pull request reviews created in the PENDING
state are not submitted and therefore do not include the submitted_at
property in the response. To create a pending review for a pull request, leave the event
parameter blank. For more information about submitting a PENDING
review, see "Submit a review for a pull request."
Note: To comment on a specific line in a file, you need to first determine the position of that line in the diff. To see a pull request diff, add the application/vnd.github.v3.diff
media type to the Accept
header of a call to the Get a pull request endpoint.
The position
value equals the number of lines down from the first "@@" hunk header in the file you want to add a comment. The line just below the "@@" line is position 1, the next line is position 2, and so on. The position in the diff continues to increase through lines of whitespace and additional hunks until the beginning of a new file.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github-commitcomment.raw+json
: Returns the raw markdown body. Response will includebody
. This is the default if you do not pass any specific media type.application/vnd.github-commitcomment.text+json
: Returns a text only representation of the markdown body. Response will includebody_text
.application/vnd.github-commitcomment.html+json
: Returns HTML rendered from the body's markdown. Response will includebody_html
.application/vnd.github-commitcomment.full+json
: Returns raw, text, and HTML representations. Response will includebody
,body_text
, andbody_html
.
octokit.rest.pulls.createReview({
owner,
repo,
pull_number,
comments[].path,
comments[].body
})
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
pull_number | yes |
The number that identifies the pull request. |
commit_id | no |
The SHA of the commit that needs a review. Not using the latest commit SHA may render your review comment outdated if a subsequent commit modifies the line you specify as the |
body | no |
Required when using |
event | no |
The review action you want to perform. The review actions include: |
comments | no |
Use the following table to specify the location, destination, and contents of the draft review comment. |
comments[].path | yes |
The relative path to the file that necessitates a review comment. |
comments[].position | no |
The position in the diff where you want to add a review comment. Note this value is not the same as the line number in the file. The |
comments[].body | yes |
Text of the review comment. |
comments[].line | no | |
comments[].side | no | |
comments[].start_line | no | |
comments[].start_side | no |
See also: GitHub Developer Guide documentation.
Create a review comment for a pull request
Creates a review comment on the diff of a specified pull request. To add a regular comment to a pull request timeline, see "Create an issue comment."
If your comment applies to more than one line in the pull request diff, you should use the parameters line
, side
, and optionally start_line
and start_side
in your request.
The position
parameter is deprecated. If you use position
, the line
, side
, start_line
, and start_side
parameters are not required.
This endpoint triggers notifications. Creating content too quickly using this endpoint may result in secondary rate limiting. For more information, see "Rate limits for the API" and "Best practices for using the REST API."
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github-commitcomment.raw+json
: Returns the raw markdown body. Response will includebody
. This is the default if you do not pass any specific media type.application/vnd.github-commitcomment.text+json
: Returns a text only representation of the markdown body. Response will includebody_text
.application/vnd.github-commitcomment.html+json
: Returns HTML rendered from the body's markdown. Response will includebody_html
.application/vnd.github-commitcomment.full+json
: Returns raw, text, and HTML representations. Response will includebody
,body_text
, andbody_html
.
octokit.rest.pulls.createReviewComment({
owner,
repo,
pull_number,
body,
commit_id,
path,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
pull_number | yes |
The number that identifies the pull request. |
body | yes |
The text of the review comment. |
commit_id | yes |
The SHA of the commit needing a comment. Not using the latest commit SHA may render your comment outdated if a subsequent commit modifies the line you specify as the |
path | yes |
The relative path to the file that necessitates a comment. |
position | no |
This parameter is deprecated. Use |
side | no |
In a split diff view, the side of the diff that the pull request's changes appear on. Can be |
line | no |
Required unless using |
start_line | no |
Required when using multi-line comments unless using |
start_side | no |
Required when using multi-line comments unless using |
in_reply_to | no |
The ID of the review comment to reply to. To find the ID of a review comment with "List review comments on a pull request". When specified, all parameters other than |
subject_type | no |
The level at which the comment is targeted. |
See also: GitHub Developer Guide documentation.
Delete a pending review for a pull request
Deletes a pull request review that has not been submitted. Submitted reviews cannot be deleted.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github-commitcomment.raw+json
: Returns the raw markdown body. Response will includebody
. This is the default if you do not pass any specific media type.application/vnd.github-commitcomment.text+json
: Returns a text only representation of the markdown body. Response will includebody_text
.application/vnd.github-commitcomment.html+json
: Returns HTML rendered from the body's markdown. Response will includebody_html
.application/vnd.github-commitcomment.full+json
: Returns raw, text, and HTML representations. Response will includebody
,body_text
, andbody_html
.
octokit.rest.pulls.deletePendingReview({
owner,
repo,
pull_number,
review_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
pull_number | yes |
The number that identifies the pull request. |
review_id | yes |
The unique identifier of the review. |
See also: GitHub Developer Guide documentation.
Delete a review comment for a pull request
Deletes a review comment.
octokit.rest.pulls.deleteReviewComment({
owner,
repo,
comment_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
comment_id | yes |
The unique identifier of the comment. |
See also: GitHub Developer Guide documentation.
Dismiss a review for a pull request
Dismisses a specified review on a pull request.
Note: To dismiss a pull request review on a protected branch, you must be a repository administrator or be included in the list of people or teams who can dismiss pull request reviews.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github-commitcomment.raw+json
: Returns the raw markdown body. Response will includebody
. This is the default if you do not pass any specific media type.application/vnd.github-commitcomment.text+json
: Returns a text only representation of the markdown body. Response will includebody_text
.application/vnd.github-commitcomment.html+json
: Returns HTML rendered from the body's markdown. Response will includebody_html
.application/vnd.github-commitcomment.full+json
: Returns raw, text, and HTML representations. Response will includebody
,body_text
, andbody_html
.
octokit.rest.pulls.dismissReview({
owner,
repo,
pull_number,
review_id,
message,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
pull_number | yes |
The number that identifies the pull request. |
review_id | yes |
The unique identifier of the review. |
message | yes |
The message for the pull request review dismissal |
event | no |
See also: GitHub Developer Guide documentation.
Get a pull request
Draft pull requests are available in public repositories with GitHub Free and GitHub Free for organizations, GitHub Pro, and legacy per-repository billing plans, and in public and private repositories with GitHub Team and GitHub Enterprise Cloud. For more information, see GitHub's products in the GitHub Help documentation.
Lists details of a pull request by providing its number.
When you get, create, or edit a pull request, GitHub creates a merge commit to test whether the pull request can be automatically merged into the base branch. This test commit is not added to the base branch or the head branch. You can review the status of the test commit using the mergeable
key. For more information, see "Checking mergeability of pull requests".
The value of the mergeable
attribute can be true
, false
, or null
. If the value is null
, then GitHub has started a background job to compute the mergeability. After giving the job time to complete, resubmit the request. When the job finishes, you will see a non-null
value for the mergeable
attribute in the response. If mergeable
is true
, then merge_commit_sha
will be the SHA of the test merge commit.
The value of the merge_commit_sha
attribute changes depending on the state of the pull request. Before merging a pull request, the merge_commit_sha
attribute holds the SHA of the test merge commit. After merging a pull request, the merge_commit_sha
attribute changes depending on how you merged the pull request:
- If merged as a merge commit,
merge_commit_sha
represents the SHA of the merge commit. - If merged via a squash,
merge_commit_sha
represents the SHA of the squashed commit on the base branch. - If rebased,
merge_commit_sha
represents the commit that the base branch was updated to.
Pass the appropriate media type to fetch diff and patch formats.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github.raw+json
: Returns the raw markdown body. Response will includebody
. This is the default if you do not pass any specific media type.application/vnd.github.text+json
: Returns a text only representation of the markdown body. Response will includebody_text
.application/vnd.github.html+json
: Returns HTML rendered from the body's markdown. Response will includebody_html
.application/vnd.github.full+json
: Returns raw, text, and HTML representations. Response will includebody
,body_text
, andbody_html
.application/vnd.github.diff
: For more information, see "git-diff" in the Git documentation. If a diff is corrupt, contact us through the GitHub Support portal. Include the repository name and pull request ID in your message.
octokit.rest.pulls.get({
owner,
repo,
pull_number,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
pull_number | yes |
The number that identifies the pull request. |
See also: GitHub Developer Guide documentation.
Get a review for a pull request
Retrieves a pull request review by its ID.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github-commitcomment.raw+json
: Returns the raw markdown body. Response will includebody
. This is the default if you do not pass any specific media type.application/vnd.github-commitcomment.text+json
: Returns a text only representation of the markdown body. Response will includebody_text
.application/vnd.github-commitcomment.html+json
: Returns HTML rendered from the body's markdown. Response will includebody_html
.application/vnd.github-commitcomment.full+json
: Returns raw, text, and HTML representations. Response will includebody
,body_text
, andbody_html
.
octokit.rest.pulls.getReview({
owner,
repo,
pull_number,
review_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
pull_number | yes |
The number that identifies the pull request. |
review_id | yes |
The unique identifier of the review. |
See also: GitHub Developer Guide documentation.
Get a review comment for a pull request
Provides details for a specified review comment.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github-commitcomment.raw+json
: Returns the raw markdown body. Response will includebody
. This is the default if you do not pass any specific media type.application/vnd.github-commitcomment.text+json
: Returns a text only representation of the markdown body. Response will includebody_text
.application/vnd.github-commitcomment.html+json
: Returns HTML rendered from the body's markdown. Response will includebody_html
.application/vnd.github-commitcomment.full+json
: Returns raw, text, and HTML representations. Response will includebody
,body_text
, andbody_html
.
octokit.rest.pulls.getReviewComment({
owner,
repo,
comment_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
comment_id | yes |
The unique identifier of the comment. |
See also: GitHub Developer Guide documentation.
List pull requests
Lists pull requests in a specified repository.
Draft pull requests are available in public repositories with GitHub Free and GitHub Free for organizations, GitHub Pro, and legacy per-repository billing plans, and in public and private repositories with GitHub Team and GitHub Enterprise Cloud. For more information, see GitHub's products in the GitHub Help documentation.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github.raw+json
: Returns the raw markdown body. Response will includebody
. This is the default if you do not pass any specific media type.application/vnd.github.text+json
: Returns a text only representation of the markdown body. Response will includebody_text
.application/vnd.github.html+json
: Returns HTML rendered from the body's markdown. Response will includebody_html
.application/vnd.github.full+json
: Returns raw, text, and HTML representations. Response will includebody
,body_text
, andbody_html
.
octokit.rest.pulls.list({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
state | no |
Either |
head | no |
Filter pulls by head user or head organization and branch name in the format of |
base | no |
Filter pulls by base branch name. Example: |
sort | no |
What to sort results by. |
direction | no |
The direction of the sort. Default: |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List comments for a pull request review
Lists comments for a specific pull request review.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github-commitcomment.raw+json
: Returns the raw markdown body. Response will includebody
. This is the default if you do not pass any specific media type.application/vnd.github-commitcomment.text+json
: Returns a text only representation of the markdown body. Response will includebody_text
.application/vnd.github-commitcomment.html+json
: Returns HTML rendered from the body's markdown. Response will includebody_html
.application/vnd.github-commitcomment.full+json
: Returns raw, text, and HTML representations. Response will includebody
,body_text
, andbody_html
.
octokit.rest.pulls.listCommentsForReview({
owner,
repo,
pull_number,
review_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
pull_number | yes |
The number that identifies the pull request. |
review_id | yes |
The unique identifier of the review. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List commits on a pull request
Lists a maximum of 250 commits for a pull request. To receive a complete commit list for pull requests with more than 250 commits, use the List commits endpoint.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github.raw+json
: Returns the raw markdown body. Response will includebody
. This is the default if you do not pass any specific media type.application/vnd.github.text+json
: Returns a text only representation of the markdown body. Response will includebody_text
.application/vnd.github.html+json
: Returns HTML rendered from the body's markdown. Response will includebody_html
.application/vnd.github.full+json
: Returns raw, text, and HTML representations. Response will includebody
,body_text
, andbody_html
.
octokit.rest.pulls.listCommits({
owner,
repo,
pull_number,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
pull_number | yes |
The number that identifies the pull request. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List pull requests files
Lists the files in a specified pull request.
Note: Responses include a maximum of 3000 files. The paginated response returns 30 files per page by default.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github.raw+json
: Returns the raw markdown body. Response will includebody
. This is the default if you do not pass any specific media type.application/vnd.github.text+json
: Returns a text only representation of the markdown body. Response will includebody_text
.application/vnd.github.html+json
: Returns HTML rendered from the body's markdown. Response will includebody_html
.application/vnd.github.full+json
: Returns raw, text, and HTML representations. Response will includebody
,body_text
, andbody_html
.
octokit.rest.pulls.listFiles({
owner,
repo,
pull_number,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
pull_number | yes |
The number that identifies the pull request. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
Get all requested reviewers for a pull request
Gets the users or teams whose review is requested for a pull request. Once a requested reviewer submits a review, they are no longer considered a requested reviewer. Their review will instead be returned by the List reviews for a pull request operation.
octokit.rest.pulls.listRequestedReviewers({
owner,
repo,
pull_number,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
pull_number | yes |
The number that identifies the pull request. |
See also: GitHub Developer Guide documentation.
List review comments on a pull request
Lists all review comments for a specified pull request. By default, review comments are in ascending order by ID.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github-commitcomment.raw+json
: Returns the raw markdown body. Response will includebody
. This is the default if you do not pass any specific media type.application/vnd.github-commitcomment.text+json
: Returns a text only representation of the markdown body. Response will includebody_text
.application/vnd.github-commitcomment.html+json
: Returns HTML rendered from the body's markdown. Response will includebody_html
.application/vnd.github-commitcomment.full+json
: Returns raw, text, and HTML representations. Response will includebody
,body_text
, andbody_html
.
octokit.rest.pulls.listReviewComments({
owner,
repo,
pull_number,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
pull_number | yes |
The number that identifies the pull request. |
sort | no |
The property to sort the results by. |
direction | no |
The direction to sort results. Ignored without |
since | no |
Only show results that were last updated after the given time. This is a timestamp in ISO 8601 format: |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List review comments in a repository
Lists review comments for all pull requests in a repository. By default, review comments are in ascending order by ID.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github-commitcomment.raw+json
: Returns the raw markdown body. Response will includebody
. This is the default if you do not pass any specific media type.application/vnd.github-commitcomment.text+json
: Returns a text only representation of the markdown body. Response will includebody_text
.application/vnd.github-commitcomment.html+json
: Returns HTML rendered from the body's markdown. Response will includebody_html
.application/vnd.github-commitcomment.full+json
: Returns raw, text, and HTML representations. Response will includebody
,body_text
, andbody_html
.
octokit.rest.pulls.listReviewCommentsForRepo({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
sort | no | |
direction | no |
The direction to sort results. Ignored without |
since | no |
Only show results that were last updated after the given time. This is a timestamp in ISO 8601 format: |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List reviews for a pull request
Lists all reviews for a specified pull request. The list of reviews returns in chronological order.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github-commitcomment.raw+json
: Returns the raw markdown body. Response will includebody
. This is the default if you do not pass any specific media type.application/vnd.github-commitcomment.text+json
: Returns a text only representation of the markdown body. Response will includebody_text
.application/vnd.github-commitcomment.html+json
: Returns HTML rendered from the body's markdown. Response will includebody_html
.application/vnd.github-commitcomment.full+json
: Returns raw, text, and HTML representations. Response will includebody
,body_text
, andbody_html
.
octokit.rest.pulls.listReviews({
owner,
repo,
pull_number,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
pull_number | yes |
The number that identifies the pull request. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
Merge a pull request
Merges a pull request into the base branch. This endpoint triggers notifications. Creating content too quickly using this endpoint may result in secondary rate limiting. For more information, see "Rate limits for the API" and "Best practices for using the REST API."
octokit.rest.pulls.merge({
owner,
repo,
pull_number,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
pull_number | yes |
The number that identifies the pull request. |
commit_title | no |
Title for the automatic commit message. |
commit_message | no |
Extra detail to append to automatic commit message. |
sha | no |
SHA that pull request head must match to allow merge. |
merge_method | no |
The merge method to use. |
See also: GitHub Developer Guide documentation.
Remove requested reviewers from a pull request
Removes review requests from a pull request for a given set of users and/or teams.
octokit.rest.pulls.removeRequestedReviewers({
owner,
repo,
pull_number,
reviewers,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
pull_number | yes |
The number that identifies the pull request. |
reviewers | yes |
An array of user |
team_reviewers | no |
An array of team |
See also: GitHub Developer Guide documentation.
Request reviewers for a pull request
This endpoint triggers notifications. Creating content too quickly using this endpoint may result in secondary rate limiting. See "Secondary rate limits" and "Dealing with secondary rate limits" for details.
octokit.rest.pulls.requestReviewers({
owner,
repo,
pull_number,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository. The name is not case sensitive. |
pull_number | yes |
The number that identifies the pull request. |
reviewers | no |
An array of user |
team_reviewers | no |
An array of team |
See also: GitHub Developer Guide documentation.
Submit a review for a pull request
Submits a pending review for a pull request. For more information about creating a pending review for a pull request, see "Create a review for a pull request."
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github-commitcomment.raw+json
: Returns the raw markdown body. Response will includebody
. This is the default if you do not pass any specific media type.application/vnd.github-commitcomment.text+json
: Returns a text only representation of the markdown body. Response will includebody_text
.application/vnd.github-commitcomment.html+json
: Returns HTML rendered from the body's markdown. Response will includebody_html
.application/vnd.github-commitcomment.full+json
: Returns raw, text, and HTML representations. Response will includebody
,body_text
, andbody_html
.
octokit.rest.pulls.submitReview({
owner,
repo,
pull_number,
review_id,
event,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
pull_number | yes |
The number that identifies the pull request. |
review_id | yes |
The unique identifier of the review. |
body | no |
The body text of the pull request review |
event | yes |
The review action you want to perform. The review actions include: |
See also: GitHub Developer Guide documentation.
Update a pull request
Draft pull requests are available in public repositories with GitHub Free and GitHub Free for organizations, GitHub Pro, and legacy per-repository billing plans, and in public and private repositories with GitHub Team and GitHub Enterprise Cloud. For more information, see GitHub's products in the GitHub Help documentation.
To open or update a pull request in a public repository, you must have write access to the head or the source branch. For organization-owned repositories, you must be a member of the organization that owns the repository to open or update a pull request.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github.raw+json
: Returns the raw markdown body. Response will includebody
. This is the default if you do not pass any specific media type.application/vnd.github.text+json
: Returns a text only representation of the markdown body. Response will includebody_text
.application/vnd.github.html+json
: Returns HTML rendered from the body's markdown. Response will includebody_html
.application/vnd.github.full+json
: Returns raw, text, and HTML representations. Response will includebody
,body_text
, andbody_html
.
octokit.rest.pulls.update({
owner,
repo,
pull_number,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
pull_number | yes |
The number that identifies the pull request. |
title | no |
The title of the pull request. |
body | no |
The contents of the pull request. |
state | no |
State of this Pull Request. Either |
base | no |
The name of the branch you want your changes pulled into. This should be an existing branch on the current repository. You cannot update the base branch on a pull request to point to another repository. |
maintainer_can_modify | no |
Indicates whether maintainers can modify the pull request. |
See also: GitHub Developer Guide documentation.
Update a pull request branch
Updates the pull request branch with the latest upstream changes by merging HEAD from the base branch into the pull request branch.
octokit.rest.pulls.updateBranch({
owner,
repo,
pull_number,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
pull_number | yes |
The number that identifies the pull request. |
expected_head_sha | no |
The expected SHA of the pull request's HEAD ref. This is the most recent commit on the pull request's branch. If the expected SHA does not match the pull request's HEAD, you will receive a |
See also: GitHub Developer Guide documentation.
Update a review for a pull request
Updates the contents of a specified review summary comment.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github-commitcomment.raw+json
: Returns the raw markdown body. Response will includebody
. This is the default if you do not pass any specific media type.application/vnd.github-commitcomment.text+json
: Returns a text only representation of the markdown body. Response will includebody_text
.application/vnd.github-commitcomment.html+json
: Returns HTML rendered from the body's markdown. Response will includebody_html
.application/vnd.github-commitcomment.full+json
: Returns raw, text, and HTML representations. Response will includebody
,body_text
, andbody_html
.
octokit.rest.pulls.updateReview({
owner,
repo,
pull_number,
review_id,
body,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
pull_number | yes |
The number that identifies the pull request. |
review_id | yes |
The unique identifier of the review. |
body | yes |
The body text of the pull request review. |
See also: GitHub Developer Guide documentation.
Update a review comment for a pull request
Edits the content of a specified review comment.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github-commitcomment.raw+json
: Returns the raw markdown body. Response will includebody
. This is the default if you do not pass any specific media type.application/vnd.github-commitcomment.text+json
: Returns a text only representation of the markdown body. Response will includebody_text
.application/vnd.github-commitcomment.html+json
: Returns HTML rendered from the body's markdown. Response will includebody_html
.application/vnd.github-commitcomment.full+json
: Returns raw, text, and HTML representations. Response will includebody
,body_text
, andbody_html
.
octokit.rest.pulls.updateReviewComment({
owner,
repo,
comment_id,
body,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
comment_id | yes |
The unique identifier of the comment. |
body | yes |
The text of the reply to the review comment. |
See also: GitHub Developer Guide documentation.
Rate-Limit
Get rate limit status for the authenticated user
Note: Accessing this endpoint does not count against your REST API rate limit.
Some categories of endpoints have custom rate limits that are separate from the rate limit governing the other REST API endpoints. For this reason, the API response categorizes your rate limit. Under resources
, you'll see objects relating to different categories:
- The
core
object provides your rate limit status for all non-search-related resources in the REST API. - The
search
object provides your rate limit status for the REST API for searching (excluding code searches). For more information, see "Search." - The
code_search
object provides your rate limit status for the REST API for searching code. For more information, see "Search code." - The
graphql
object provides your rate limit status for the GraphQL API. For more information, see "Resource limitations." - The
integration_manifest
object provides your rate limit status for thePOST /app-manifests/{code}/conversions
operation. For more information, see "Creating a GitHub App from a manifest." - The
dependency_snapshots
object provides your rate limit status for submitting snapshots to the dependency graph. For more information, see "Dependency graph." - The
code_scanning_upload
object provides your rate limit status for uploading SARIF results to code scanning. For more information, see "Uploading a SARIF file to GitHub." - The
actions_runner_registration
object provides your rate limit status for registering self-hosted runners in GitHub Actions. For more information, see "Self-hosted runners." - The
source_import
object is no longer in use for any API endpoints, and it will be removed in the next API version. For more information about API versions, see "API Versions."
Note: The rate
object is deprecated. If you're writing new API client code or updating existing code, you should use the core
object instead of the rate
object. The core
object contains the same information that is present in the rate
object.
octokit.rest.rateLimit.get();
Parameters
This endpoint has no parameters
See also: GitHub Developer Guide documentation.
Reactions
Create reaction for a commit comment
Create a reaction to a commit comment. A response with an HTTP 200
status means that you already added the reaction type to this commit comment.
octokit.rest.reactions.createForCommitComment({
owner,
repo,
comment_id,
content,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
comment_id | yes |
The unique identifier of the comment. |
content | yes |
The reaction type to add to the commit comment. |
See also: GitHub Developer Guide documentation.
Create reaction for an issue
Create a reaction to an issue. A response with an HTTP 200
status means that you already added the reaction type to this issue.
octokit.rest.reactions.createForIssue({
owner,
repo,
issue_number,
content,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
issue_number | yes |
The number that identifies the issue. |
content | yes |
The reaction type to add to the issue. |
See also: GitHub Developer Guide documentation.
Create reaction for an issue comment
Create a reaction to an issue comment. A response with an HTTP 200
status means that you already added the reaction type to this issue comment.
octokit.rest.reactions.createForIssueComment({
owner,
repo,
comment_id,
content,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
comment_id | yes |
The unique identifier of the comment. |
content | yes |
The reaction type to add to the issue comment. |
See also: GitHub Developer Guide documentation.
Create reaction for a pull request review comment
Create a reaction to a pull request review comment. A response with an HTTP 200
status means that you already added the reaction type to this pull request review comment.
octokit.rest.reactions.createForPullRequestReviewComment({
owner,
repo,
comment_id,
content,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
comment_id | yes |
The unique identifier of the comment. |
content | yes |
The reaction type to add to the pull request review comment. |
See also: GitHub Developer Guide documentation.
Create reaction for a release
Create a reaction to a release. A response with a Status: 200 OK
means that you already added the reaction type to this release.
octokit.rest.reactions.createForRelease({
owner,
repo,
release_id,
content,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
release_id | yes |
The unique identifier of the release. |
content | yes |
The reaction type to add to the release. |
See also: GitHub Developer Guide documentation.
Create reaction for a team discussion comment
Create a reaction to a team discussion comment.
A response with an HTTP 200
status means that you already added the reaction type to this team discussion comment.
Note: You can also specify a team by org_id
and team_id
using the route POST /organizations/:org_id/team/:team_id/discussions/:discussion_number/comments/:comment_number/reactions
.
OAuth app tokens and personal access tokens (classic) need the write:discussion
scope to use this endpoint.
octokit.rest.reactions.createForTeamDiscussionCommentInOrg({
org,
team_slug,
discussion_number,
comment_number,
content,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
team_slug | yes |
The slug of the team name. |
discussion_number | yes |
The number that identifies the discussion. |
comment_number | yes |
The number that identifies the comment. |
content | yes |
The reaction type to add to the team discussion comment. |
See also: GitHub Developer Guide documentation.
Create reaction for a team discussion
Create a reaction to a team discussion.
A response with an HTTP 200
status means that you already added the reaction type to this team discussion.
Note: You can also specify a team by org_id
and team_id
using the route POST /organizations/:org_id/team/:team_id/discussions/:discussion_number/reactions
.
OAuth app tokens and personal access tokens (classic) need the write:discussion
scope to use this endpoint.
octokit.rest.reactions.createForTeamDiscussionInOrg({
org,
team_slug,
discussion_number,
content,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
team_slug | yes |
The slug of the team name. |
discussion_number | yes |
The number that identifies the discussion. |
content | yes |
The reaction type to add to the team discussion. |
See also: GitHub Developer Guide documentation.
Delete a commit comment reaction
Note: You can also specify a repository by repository_id
using the route DELETE /repositories/:repository_id/comments/:comment_id/reactions/:reaction_id
.
Delete a reaction to a commit comment.
octokit.rest.reactions.deleteForCommitComment({
owner,
repo,
comment_id,
reaction_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
comment_id | yes |
The unique identifier of the comment. |
reaction_id | yes |
The unique identifier of the reaction. |
See also: GitHub Developer Guide documentation.
Delete an issue reaction
Note: You can also specify a repository by repository_id
using the route DELETE /repositories/:repository_id/issues/:issue_number/reactions/:reaction_id
.
Delete a reaction to an issue.
octokit.rest.reactions.deleteForIssue({
owner,
repo,
issue_number,
reaction_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
issue_number | yes |
The number that identifies the issue. |
reaction_id | yes |
The unique identifier of the reaction. |
See also: GitHub Developer Guide documentation.
Delete an issue comment reaction
Note: You can also specify a repository by repository_id
using the route DELETE delete /repositories/:repository_id/issues/comments/:comment_id/reactions/:reaction_id
.
Delete a reaction to an issue comment.
octokit.rest.reactions.deleteForIssueComment({
owner,
repo,
comment_id,
reaction_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
comment_id | yes |
The unique identifier of the comment. |
reaction_id | yes |
The unique identifier of the reaction. |
See also: GitHub Developer Guide documentation.
Delete a pull request comment reaction
Note: You can also specify a repository by repository_id
using the route DELETE /repositories/:repository_id/pulls/comments/:comment_id/reactions/:reaction_id.
Delete a reaction to a pull request review comment.
octokit.rest.reactions.deleteForPullRequestComment({
owner,
repo,
comment_id,
reaction_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
comment_id | yes |
The unique identifier of the comment. |
reaction_id | yes |
The unique identifier of the reaction. |
See also: GitHub Developer Guide documentation.
Delete a release reaction
Note: You can also specify a repository by repository_id
using the route DELETE delete /repositories/:repository_id/releases/:release_id/reactions/:reaction_id
.
Delete a reaction to a release.
octokit.rest.reactions.deleteForRelease({
owner,
repo,
release_id,
reaction_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
release_id | yes |
The unique identifier of the release. |
reaction_id | yes |
The unique identifier of the reaction. |
See also: GitHub Developer Guide documentation.
Delete team discussion reaction
Note: You can also specify a team or organization with team_id
and org_id
using the route DELETE /organizations/:org_id/team/:team_id/discussions/:discussion_number/reactions/:reaction_id
.
Delete a reaction to a team discussion.
OAuth app tokens and personal access tokens (classic) need the write:discussion
scope to use this endpoint.
octokit.rest.reactions.deleteForTeamDiscussion({
org,
team_slug,
discussion_number,
reaction_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
team_slug | yes |
The slug of the team name. |
discussion_number | yes |
The number that identifies the discussion. |
reaction_id | yes |
The unique identifier of the reaction. |
See also: GitHub Developer Guide documentation.
Delete team discussion comment reaction
Note: You can also specify a team or organization with team_id
and org_id
using the route DELETE /organizations/:org_id/team/:team_id/discussions/:discussion_number/comments/:comment_number/reactions/:reaction_id
.
Delete a reaction to a team discussion comment.
OAuth app tokens and personal access tokens (classic) need the write:discussion
scope to use this endpoint.
octokit.rest.reactions.deleteForTeamDiscussionComment({
org,
team_slug,
discussion_number,
comment_number,
reaction_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
team_slug | yes |
The slug of the team name. |
discussion_number | yes |
The number that identifies the discussion. |
comment_number | yes |
The number that identifies the comment. |
reaction_id | yes |
The unique identifier of the reaction. |
See also: GitHub Developer Guide documentation.
List reactions for a commit comment
List the reactions to a commit comment.
octokit.rest.reactions.listForCommitComment({
owner,
repo,
comment_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
comment_id | yes |
The unique identifier of the comment. |
content | no |
Returns a single reaction type. Omit this parameter to list all reactions to a commit comment. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List reactions for an issue
List the reactions to an issue.
octokit.rest.reactions.listForIssue({
owner,
repo,
issue_number,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
issue_number | yes |
The number that identifies the issue. |
content | no |
Returns a single reaction type. Omit this parameter to list all reactions to an issue. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List reactions for an issue comment
List the reactions to an issue comment.
octokit.rest.reactions.listForIssueComment({
owner,
repo,
comment_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
comment_id | yes |
The unique identifier of the comment. |
content | no |
Returns a single reaction type. Omit this parameter to list all reactions to an issue comment. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List reactions for a pull request review comment
List the reactions to a pull request review comment.
octokit.rest.reactions.listForPullRequestReviewComment({
owner,
repo,
comment_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
comment_id | yes |
The unique identifier of the comment. |
content | no |
Returns a single reaction type. Omit this parameter to list all reactions to a pull request review comment. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List reactions for a release
List the reactions to a release.
octokit.rest.reactions.listForRelease({
owner,
repo,
release_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
release_id | yes |
The unique identifier of the release. |
content | no |
Returns a single reaction type. Omit this parameter to list all reactions to a release. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List reactions for a team discussion comment
List the reactions to a team discussion comment.
Note: You can also specify a team by org_id
and team_id
using the route GET /organizations/:org_id/team/:team_id/discussions/:discussion_number/comments/:comment_number/reactions
.
OAuth app tokens and personal access tokens (classic) need the read:discussion
scope to use this endpoint.
octokit.rest.reactions.listForTeamDiscussionCommentInOrg({
org,
team_slug,
discussion_number,
comment_number,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
team_slug | yes |
The slug of the team name. |
discussion_number | yes |
The number that identifies the discussion. |
comment_number | yes |
The number that identifies the comment. |
content | no |
Returns a single reaction type. Omit this parameter to list all reactions to a team discussion comment. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List reactions for a team discussion
List the reactions to a team discussion.
Note: You can also specify a team by org_id
and team_id
using the route GET /organizations/:org_id/team/:team_id/discussions/:discussion_number/reactions
.
OAuth app tokens and personal access tokens (classic) need the read:discussion
scope to use this endpoint.
octokit.rest.reactions.listForTeamDiscussionInOrg({
org,
team_slug,
discussion_number,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
team_slug | yes |
The slug of the team name. |
discussion_number | yes |
The number that identifies the discussion. |
content | no |
Returns a single reaction type. Omit this parameter to list all reactions to a team discussion. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
Repos
Accept a repository invitation
Deprecated: This method has been renamed to repos.acceptInvitationForAuthenticatedUser
octokit.rest.repos.acceptInvitation({
invitation_id,
});
Parameters
name | required | description |
---|---|---|
invitation_id | yes |
The unique identifier of the invitation. |
See also: GitHub Developer Guide documentation.
Accept a repository invitation
octokit.rest.repos.acceptInvitationForAuthenticatedUser({
invitation_id,
});
Parameters
name | required | description |
---|---|---|
invitation_id | yes |
The unique identifier of the invitation. |
See also: GitHub Developer Guide documentation.
Add app access restrictions
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.
Grants the specified apps push access for this branch. Only GitHub Apps that are installed on the repository and that have been granted write access to the repository contents can be added as authorized actors on a protected branch.
octokit.rest.repos.addAppAccessRestrictions({
owner,
repo,
branch,
apps,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
branch | yes |
The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API. |
apps | yes |
See also: GitHub Developer Guide documentation.
Add a repository collaborator
This endpoint triggers notifications. Creating content too quickly using this endpoint may result in secondary rate limiting. For more information, see "Rate limits for the API" and "Best practices for using the REST API."
Adding an outside collaborator may be restricted by enterprise administrators. For more information, see "Enforcing repository management policies in your enterprise."
For more information on permission levels, see "Repository permission levels for an organization". There are restrictions on which permissions can be granted to organization members when an organization base role is in place. In this case, the permission being given must be equal to or higher than the org base permission. Otherwise, the request will fail with:
Cannot assign {member} permission of {role name}
Note that, if you choose not to pass any parameters, you'll need to set Content-Length
to zero when calling out to this endpoint. For more information, see "HTTP method."
The invitee will receive a notification that they have been invited to the repository, which they must accept or decline. They may do this via the notifications page, the email they receive, or by using the API.
Updating an existing collaborator's permission level
The endpoint can also be used to change the permissions of an existing collaborator without first removing and re-adding the collaborator. To change the permissions, use the same endpoint and pass a different permission
parameter. The response will be a 204
, with no other indication that the permission level changed.
Rate limits
You are limited to sending 50 invitations to a repository per 24 hour period. Note there is no limit if you are inviting organization members to an organization repository.
octokit.rest.repos.addCollaborator({
owner,
repo,
username,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
username | yes |
The handle for the GitHub user account. |
permission | no |
The permission to grant the collaborator. Only valid on organization-owned repositories. We accept the following permissions to be set: |
See also: GitHub Developer Guide documentation.
Add status check contexts
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.
octokit.rest.repos.addStatusCheckContexts({
owner,
repo,
branch,
contexts,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
branch | yes |
The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API. |
contexts | yes |
See also: GitHub Developer Guide documentation.
Add team access restrictions
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.
Grants the specified teams push access for this branch. You can also give push access to child teams.
octokit.rest.repos.addTeamAccessRestrictions({
owner,
repo,
branch,
teams,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
branch | yes |
The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API. |
teams | yes |
See also: GitHub Developer Guide documentation.
Add user access restrictions
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.
Grants the specified people push access for this branch.
Type | Description |
---|---|
array | Usernames for people who can have push access. Note: The list of users, apps, and teams in total is limited to 100 items. |
octokit.rest.repos.addUserAccessRestrictions({
owner,
repo,
branch,
users,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
branch | yes |
The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API. |
users | yes |
See also: GitHub Developer Guide documentation.
Cancel a GitHub Pages deployment
Cancels a GitHub Pages deployment.
The authenticated user must have write permissions for the GitHub Pages site.
octokit.rest.repos.cancelPagesDeployment({
owner,
repo,
pages_deployment_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
pages_deployment_id | yes |
The ID of the Pages deployment. You can also give the commit SHA of the deployment. |
See also: GitHub Developer Guide documentation.
Check if automated security fixes are enabled for a repository
Shows whether automated security fixes are enabled, disabled or paused for a repository. The authenticated user must have admin read access to the repository. For more information, see "Configuring automated security fixes".
octokit.rest.repos.checkAutomatedSecurityFixes({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Check if a user is a repository collaborator
For organization-owned repositories, the list of collaborators includes outside collaborators, organization members that are direct collaborators, organization members with access through team memberships, organization members with access through default organization permissions, and organization owners.
Team members will include the members of child teams.
The authenticated user must have push access to the repository to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the read:org
and repo
scopes to use this endpoint.
octokit.rest.repos.checkCollaborator({
owner,
repo,
username,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
username | yes |
The handle for the GitHub user account. |
See also: GitHub Developer Guide documentation.
Check if private vulnerability reporting is enabled for a repository
Returns a boolean indicating whether or not private vulnerability reporting is enabled for the repository. For more information, see "Evaluating the security settings of a repository".
octokit.rest.repos.checkPrivateVulnerabilityReporting({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Check if vulnerability alerts are enabled for a repository
Shows whether dependency alerts are enabled or disabled for a repository. The authenticated user must have admin read access to the repository. For more information, see "About security alerts for vulnerable dependencies".
octokit.rest.repos.checkVulnerabilityAlerts({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
List CODEOWNERS errors
List any syntax errors that are detected in the CODEOWNERS file.
For more information about the correct CODEOWNERS syntax, see "About code owners."
octokit.rest.repos.codeownersErrors({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
ref | no |
A branch, tag or commit name used to determine which version of the CODEOWNERS file to use. Default: the repository's default branch (e.g. |
See also: GitHub Developer Guide documentation.
Compare two commits
Deprecated: Use repos.compareCommitsWithBasehead()
(GET /repos/{owner}/{repo}/compare/{basehead}
) instead. Both :base
and :head
must be branch names in :repo
. To compare branches across other repositories in the same network as :repo
, use the format <USERNAME>:branch
.
The response from the API is equivalent to running the git log base..head
command; however, commits are returned in chronological order. Pass the appropriate media type to fetch diff and patch formats.
The response also includes details on the files that were changed between the two commits. This includes the status of the change (for example, if a file was added, removed, modified, or renamed), and details of the change itself. For example, files with a renamed
status have a previous_filename
field showing the previous filename of the file, and files with a modified
status have a patch
field showing the changes made to the file.
Working with large comparisons
To process a response with a large number of commits, you can use (per_page
or page
) to paginate the results. When using paging, the list of changed files is only returned with page 1, but includes all changed files for the entire comparison. For more information on working with pagination, see "Traversing with pagination."
When calling this API without any paging parameters (per_page
or page
), the returned list is limited to 250 commits and the last commit in the list is the most recent of the entire comparison. When a paging parameter is specified, the first commit in the returned list of each page is the earliest.
Signature verification object
The response will include a verification
object that describes the result of verifying the commit's signature. The following fields are included in the verification
object:
Name | Type | Description |
---|---|---|
verified | boolean | Indicates whether GitHub considers the signature in this commit to be verified. |
reason | string | The reason for verified value. Possible values and their meanings are enumerated in table below. |
signature | string | The signature that was extracted from the commit. |
payload | string | The value that was signed. |
These are the possible values for reason
in the verification
object:
Value | Description |
---|---|
expired_key | The key that made the signature is expired. |
not_signing_key | The "signing" flag is not among the usage flags in the GPG key that made the signature. |
gpgverify_error | There was an error communicating with the signature verification service. |
gpgverify_unavailable | The signature verification service is currently unavailable. |
unsigned | The object does not include a signature. |
unknown_signature_type | A non-PGP signature was found in the commit. |
no_user | No user was associated with the committer email address in the commit. |
unverified_email | The committer email address in the commit was associated with a user, but the email address is not verified on her/his account. |
bad_email | The committer email address in the commit is not included in the identities of the PGP key that made the signature. |
unknown_key | The key that made the signature has not been registered with any user's account. |
malformed_signature | There was an error parsing the signature. |
invalid | The signature could not be cryptographically verified using the key whose key-id was found in the signature. |
valid | None of the above errors applied, so the signature is considered to be verified. |
octokit.rest.repos.compareCommits({
owner,
repo,
base,
head,
});
Parameters
name | required | description |
---|---|---|
owner | yes | |
repo | yes | |
base | yes | |
head | yes | |
per_page | no |
Results per page. |
page | no |
Page number of the results to fetch. |
See also: GitHub Developer Guide documentation.
Compare two commits
Compares two commits against one another. You can compare refs (branches or tags) and commit SHAs in the same repository, or you can compare refs and commit SHAs that exist in different repositories within the same repository network, including fork branches. For more information about how to view a repository's network, see "Understanding connections between repositories."
This endpoint is equivalent to running the git log BASE..HEAD
command, but it returns commits in a different order. The git log BASE..HEAD
command returns commits in reverse chronological order, whereas the API returns commits in chronological order.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github.diff
: Returns the diff of the commit.application/vnd.github.patch
: Returns the patch of the commit. Diffs with binary data will have nopatch
property.
The API response includes details about the files that were changed between the two commits. This includes the status of the change (if a file was added, removed, modified, or renamed), and details of the change itself. For example, files with a renamed
status have a previous_filename
field showing the previous filename of the file, and files with a modified
status have a patch
field showing the changes made to the file.
When calling this endpoint without any paging parameter (per_page
or page
), the returned list is limited to 250 commits, and the last commit in the list is the most recent of the entire comparison.
Working with large comparisons
To process a response with a large number of commits, use a query parameter (per_page
or page
) to paginate the results. When using pagination:
- The list of changed files is only shown on the first page of results, but it includes all changed files for the entire comparison.
- The results are returned in chronological order, but the last commit in the returned list may not be the most recent one in the entire set if there are more pages of results.
For more information on working with pagination, see "Using pagination in the REST API."
Signature verification object
The response will include a verification
object that describes the result of verifying the commit's signature. The verification
object includes the following fields:
Name | Type | Description |
---|---|---|
verified | boolean | Indicates whether GitHub considers the signature in this commit to be verified. |
reason | string | The reason for verified value. Possible values and their meanings are enumerated in table below. |
signature | string | The signature that was extracted from the commit. |
payload | string | The value that was signed. |
These are the possible values for reason
in the verification
object:
Value | Description |
---|---|
expired_key | The key that made the signature is expired. |
not_signing_key | The "signing" flag is not among the usage flags in the GPG key that made the signature. |
gpgverify_error | There was an error communicating with the signature verification service. |
gpgverify_unavailable | The signature verification service is currently unavailable. |
unsigned | The object does not include a signature. |
unknown_signature_type | A non-PGP signature was found in the commit. |
no_user | No user was associated with the committer email address in the commit. |
unverified_email | The committer email address in the commit was associated with a user, but the email address is not verified on their account. |
bad_email | The committer email address in the commit is not included in the identities of the PGP key that made the signature. |
unknown_key | The key that made the signature has not been registered with any user's account. |
malformed_signature | There was an error parsing the signature. |
invalid | The signature could not be cryptographically verified using the key whose key-id was found in the signature. |
valid | None of the above errors applied, so the signature is considered to be verified. |
octokit.rest.repos.compareCommitsWithBasehead({
owner,
repo,
basehead,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
basehead | yes |
The base branch and head branch to compare. This parameter expects the format |
See also: GitHub Developer Guide documentation.
Create an autolink reference for a repository
Users with admin access to the repository can create an autolink.
octokit.rest.repos.createAutolink({
owner,
repo,
key_prefix,
url_template,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
key_prefix | yes |
This prefix appended by certain characters will generate a link any time it is found in an issue, pull request, or commit. |
url_template | yes |
The URL must contain |
is_alphanumeric | no |
Whether this autolink reference matches alphanumeric characters. If true, the |
See also: GitHub Developer Guide documentation.
Create a commit comment
Create a comment for a commit using its :commit_sha
.
This endpoint triggers notifications. Creating content too quickly using this endpoint may result in secondary rate limiting. For more information, see "Rate limits for the API" and "Best practices for using the REST API."
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github-commitcomment.raw+json
: Returns the raw markdown body. Response will includebody
. This is the default if you do not pass any specific media type.application/vnd.github-commitcomment.text+json
: Returns a text only representation of the markdown body. Response will includebody_text
.application/vnd.github-commitcomment.html+json
: Returns HTML rendered from the body's markdown. Response will includebody_html
.application/vnd.github-commitcomment.full+json
: Returns raw, text, and HTML representations. Response will includebody
,body_text
, andbody_html
.
octokit.rest.repos.createCommitComment({
owner,
repo,
commit_sha,
body,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
commit_sha | yes |
The SHA of the commit. |
body | yes |
The contents of the comment. |
path | no |
Relative path of the file to comment on. |
position | no |
Line index in the diff to comment on. |
line | no |
Deprecated. Use position parameter instead. Line number in the file to comment on. |
See also: GitHub Developer Guide documentation.
Create commit signature protection
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.
When authenticated with admin or owner permissions to the repository, you can use this endpoint to require signed commits on a branch. You must enable branch protection to require signed commits.
octokit.rest.repos.createCommitSignatureProtection({
owner,
repo,
branch,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
branch | yes |
The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API. |
See also: GitHub Developer Guide documentation.
Create a commit status
Users with push access in a repository can create commit statuses for a given SHA.
Note: there is a limit of 1000 statuses per sha
and context
within a repository. Attempts to create more than 1000 statuses will result in a validation error.
octokit.rest.repos.createCommitStatus({
owner,
repo,
sha,
state,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
sha | yes | |
state | yes |
The state of the status. |
target_url | no |
The target URL to associate with this status. This URL will be linked from the GitHub UI to allow users to easily see the source of the status. |
description | no |
A short description of the status. |
context | no |
A string label to differentiate this status from the status of other systems. This field is case-insensitive. |
See also: GitHub Developer Guide documentation.
Create a deploy key
You can create a read-only deploy key.
octokit.rest.repos.createDeployKey({
owner,
repo,
key,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
title | no |
A name for the key. |
key | yes |
The contents of the key. |
read_only | no |
If Deploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see "Repository permission levels for an organization" and "Permission levels for a user account repository." |
See also: GitHub Developer Guide documentation.
Create a deployment
Deployments offer a few configurable parameters with certain defaults.
The ref
parameter can be any named branch, tag, or SHA. At GitHub we often deploy branches and verify them
before we merge a pull request.
The environment
parameter allows deployments to be issued to different runtime environments. Teams often have
multiple environments for verifying their applications, such as production
, staging
, and qa
. This parameter
makes it easier to track which environments have requested deployments. The default environment is production
.
The auto_merge
parameter is used to ensure that the requested ref is not behind the repository's default branch. If
the ref is behind the default branch for the repository, we will attempt to merge it for you. If the merge succeeds,
the API will return a successful merge commit. If merge conflicts prevent the merge from succeeding, the API will
return a failure response.
By default, commit statuses for every submitted context must be in a success
state. The required_contexts
parameter allows you to specify a subset of contexts that must be success
, or to
specify contexts that have not yet been submitted. You are not required to use commit statuses to deploy. If you do
not require any contexts or create any commit statuses, the deployment will always succeed.
The payload
parameter is available for any extra information that a deployment system might need. It is a JSON text
field that will be passed on when a deployment event is dispatched.
The task
parameter is used by the deployment system to allow different execution paths. In the web world this might
be deploy:migrations
to run schema changes on the system. In the compiled world this could be a flag to compile an
application with debugging enabled.
Merged branch response:
You will see this response when GitHub automatically merges the base branch into the topic branch instead of creating a deployment. This auto-merge happens when:
- Auto-merge option is enabled in the repository
- Topic branch does not include the latest changes on the base branch, which is
master
in the response example - There are no merge conflicts
If there are no new commits in the base branch, a new request to create a deployment should give a successful response.
Merge conflict response:
This error happens when the auto_merge
option is enabled and when the default branch (in this case master
), can't
be merged into the branch that's being deployed (in this case topic-branch
), due to merge conflicts.
Failed commit status checks:
This error happens when the required_contexts
parameter indicates that one or more contexts need to have a success
status for the commit to be deployed, but one or more of the required contexts do not have a state of success
.
OAuth app tokens and personal access tokens (classic) need the repo
or repo_deployment
scope to use this endpoint.
octokit.rest.repos.createDeployment({
owner,
repo,
ref,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
ref | yes |
The ref to deploy. This can be a branch, tag, or SHA. |
task | no |
Specifies a task to execute (e.g., |
auto_merge | no |
Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch. |
required_contexts | no |
The status contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts. |
payload | no | |
environment | no |
Name for the target deployment environment (e.g., |
description | no |
Short description of the deployment. |
transient_environment | no |
Specifies if the given environment is specific to the deployment and will no longer exist at some point in the future. Default: |
production_environment | no |
Specifies if the given environment is one that end-users directly interact with. Default: |
See also: GitHub Developer Guide documentation.
Create a deployment branch policy
Creates a deployment branch or tag policy for an environment.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.repos.createDeploymentBranchPolicy({
owner,
repo,
environment_name,
name,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
environment_name | yes |
The name of the environment. The name must be URL encoded. For example, any slashes in the name must be replaced with |
name | yes |
The name pattern that branches or tags must match in order to deploy to the environment. Wildcard characters will not match |
type | no |
Whether this rule targets a branch or tag |
See also: GitHub Developer Guide documentation.
Create a custom deployment protection rule on an environment
Enable a custom deployment protection rule for an environment.
The authenticated user must have admin or owner permissions to the repository to use this endpoint.
For more information about the app that is providing this custom deployment rule, see the documentation for the GET /apps/{app_slug}
endpoint.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.repos.createDeploymentProtectionRule({
environment_name,
repo,
owner,
});
Parameters
name | required | description |
---|---|---|
environment_name | yes |
The name of the environment. The name must be URL encoded. For example, any slashes in the name must be replaced with |
repo | yes |
The name of the repository without the |
owner | yes |
The account owner of the repository. The name is not case sensitive. |
integration_id | no |
The ID of the custom app that will be enabled on the environment. |
See also: GitHub Developer Guide documentation.
Create a deployment status
Users with push
access can create deployment statuses for a given deployment.
OAuth app tokens and personal access tokens (classic) need the repo_deployment
scope to use this endpoint.
octokit.rest.repos.createDeploymentStatus({
owner,
repo,
deployment_id,
state,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
deployment_id | yes |
deployment_id parameter |
state | yes |
The state of the status. When you set a transient deployment to |
target_url | no |
The target URL to associate with this status. This URL should contain output to keep the user updated while the task is running or serve as historical information for what happened in the deployment. Note: It's recommended to use the |
log_url | no |
The full URL of the deployment's output. This parameter replaces |
description | no |
A short description of the status. The maximum description length is 140 characters. |
environment | no |
Name for the target deployment environment, which can be changed when setting a deploy status. For example, |
environment_url | no |
Sets the URL for accessing your environment. Default: |
auto_inactive | no |
Adds a new |
See also: GitHub Developer Guide documentation.
Create a repository dispatch event
You can use this endpoint to trigger a webhook event called repository_dispatch
when you want activity that happens outside of GitHub to trigger a GitHub Actions workflow or GitHub App webhook. You must configure your GitHub Actions workflow or GitHub App to run when the repository_dispatch
event occurs. For an example repository_dispatch
webhook payload, see "RepositoryDispatchEvent."
The client_payload
parameter is available for any extra information that your workflow might need. This parameter is a JSON payload that will be passed on when the webhook event is dispatched. For example, the client_payload
can include a message that a user would like to send using a GitHub Actions workflow. Or the client_payload
can be used as a test to debug your workflow.
This input example shows how you can use the client_payload
as a test to debug your workflow.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.repos.createDispatchEvent({
owner,
repo,
event_type,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
event_type | yes |
A custom webhook event name. Must be 100 characters or fewer. |
client_payload | no |
JSON payload with extra information about the webhook event that your action or workflow may use. The maximum number of top-level properties is 10. |
client_payload.* | no |
See also: GitHub Developer Guide documentation.
Create a repository for the authenticated user
Creates a new repository for the authenticated user.
OAuth app tokens and personal access tokens (classic) need the public_repo
or repo
scope to create a public repository, and repo
scope to create a private repository.
octokit.rest.repos.createForAuthenticatedUser({
name,
});
Parameters
name | required | description |
---|---|---|
name | yes |
The name of the repository. |
description | no |
A short description of the repository. |
homepage | no |
A URL with more information about the repository. |
private | no |
Whether the repository is private. |
has_issues | no |
Whether issues are enabled. |
has_projects | no |
Whether projects are enabled. |
has_wiki | no |
Whether the wiki is enabled. |
has_discussions | no |
Whether discussions are enabled. |
team_id | no |
The id of the team that will be granted access to this repository. This is only valid when creating a repository in an organization. |
auto_init | no |
Whether the repository is initialized with a minimal README. |
gitignore_template | no |
The desired language or platform to apply to the .gitignore. |
license_template | no |
The license keyword of the open source license for this repository. |
allow_squash_merge | no |
Whether to allow squash merges for pull requests. |
allow_merge_commit | no |
Whether to allow merge commits for pull requests. |
allow_rebase_merge | no |
Whether to allow rebase merges for pull requests. |
allow_auto_merge | no |
Whether to allow Auto-merge to be used on pull requests. |
delete_branch_on_merge | no |
Whether to delete head branches when pull requests are merged |
squash_merge_commit_title | no |
The default value for a squash merge commit title:
|
squash_merge_commit_message | no |
The default value for a squash merge commit message:
|
merge_commit_title | no |
The default value for a merge commit title.
|
merge_commit_message | no |
The default value for a merge commit message.
|
has_downloads | no |
Whether downloads are enabled. |
is_template | no |
Whether this repository acts as a template that can be used to generate new repositories. |
See also: GitHub Developer Guide documentation.
Create a fork
Create a fork for the authenticated user.
Note: Forking a Repository happens asynchronously. You may have to wait a short period of time before you can access the git objects. If this takes longer than 5 minutes, be sure to contact GitHub Support.
Note: Although this endpoint works with GitHub Apps, the GitHub App must be installed on the destination account with access to all repositories and on the source account with access to the source repository.
octokit.rest.repos.createFork({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
organization | no |
Optional parameter to specify the organization name if forking into an organization. |
name | no |
When forking from an existing repository, a new name for the fork. |
default_branch_only | no |
When forking from an existing repository, fork with only the default branch. |
See also: GitHub Developer Guide documentation.
Create an organization repository
Creates a new repository in the specified organization. The authenticated user must be a member of the organization.
OAuth app tokens and personal access tokens (classic) need the public_repo
or repo
scope to create a public repository, and repo
scope to create a private repository.
octokit.rest.repos.createInOrg({
org,
name,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
name | yes |
The name of the repository. |
description | no |
A short description of the repository. |
homepage | no |
A URL with more information about the repository. |
private | no |
Whether the repository is private. |
visibility | no |
The visibility of the repository. |
has_issues | no |
Either |
has_projects | no |
Either |
has_wiki | no |
Either |
has_downloads | no |
Whether downloads are enabled. |
is_template | no |
Either |
team_id | no |
The id of the team that will be granted access to this repository. This is only valid when creating a repository in an organization. |
auto_init | no |
Pass |
gitignore_template | no |
Desired language or platform .gitignore template to apply. Use the name of the template without the extension. For example, "Haskell". |
license_template | no |
Choose an open source license template that best suits your needs, and then use the license keyword as the |
allow_squash_merge | no |
Either |
allow_merge_commit | no |
Either |
allow_rebase_merge | no |
Either |
allow_auto_merge | no |
Either |
delete_branch_on_merge | no |
Either |
use_squash_pr_title_as_default | no |
Either |
squash_merge_commit_title | no |
The default value for a squash merge commit title:
|
squash_merge_commit_message | no |
The default value for a squash merge commit message:
|
merge_commit_title | no |
The default value for a merge commit title.
|
merge_commit_message | no |
The default value for a merge commit message.
|
custom_properties | no |
The custom properties for the new repository. The keys are the custom property names, and the values are the corresponding custom property values. |
custom_properties.* | no |
See also: GitHub Developer Guide documentation.
Create or update custom property values for a repository
Create new or update existing custom property values for a repository.
Using a value of null
for a custom property will remove or 'unset' the property value from the repository.
Repository admins and other users with the repository-level "edit custom property values" fine-grained permission can use this endpoint.
octokit.rest.repos.createOrUpdateCustomPropertiesValues({
owner,
repo,
properties,
properties[].property_name,
properties[].value
})
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
properties | yes |
A list of custom property names and associated values to apply to the repositories. |
properties[].property_name | yes |
The name of the property |
properties[].value | yes |
The value assigned to the property |
See also: GitHub Developer Guide documentation.
Create or update an environment
Create or update an environment with protection rules, such as required reviewers. For more information about environment protection rules, see "Environments."
Note: To create or update name patterns that branches must match in order to deploy to this environment, see "Deployment branch policies."
Note: To create or update secrets for an environment, see "GitHub Actions secrets."
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.repos.createOrUpdateEnvironment({
owner,
repo,
environment_name,
deployment_branch_policy.protected_branches,
deployment_branch_policy.custom_branch_policies
})
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
environment_name | yes |
The name of the environment. The name must be URL encoded. For example, any slashes in the name must be replaced with |
wait_timer | no |
The amount of time to delay a job after the job is initially triggered. The time (in minutes) must be an integer between 0 and 43,200 (30 days). |
prevent_self_review | no |
Whether or not a user who created the job is prevented from approving their own job. |
reviewers | no |
The people or teams that may review jobs that reference the environment. You can list up to six users or teams as reviewers. The reviewers must have at least read access to the repository. Only one of the required reviewers needs to approve the job for it to proceed. |
reviewers[].type | no |
The type of reviewer. |
reviewers[].id | no |
The id of the user or team who can review the deployment |
deployment_branch_policy | no |
The type of deployment branch policy for this environment. To allow all branches to deploy, set to |
deployment_branch_policy.protected_branches | yes |
Whether only branches with branch protection rules can deploy to this environment. If |
deployment_branch_policy.custom_branch_policies | yes |
Whether only branches that match the specified name patterns can deploy to this environment. If |
See also: GitHub Developer Guide documentation.
Create or update file contents
Creates a new file or replaces an existing file in a repository.
Note: If you use this endpoint and the "Delete a file" endpoint in parallel, the concurrent requests will conflict and you will receive errors. You must use these endpoints serially instead.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint. The workflow
scope is also required in order to modify files in the .github/workflows
directory.
octokit.rest.repos.createOrUpdateFileContents({
owner,
repo,
path,
message,
content,
committer.name,
committer.email,
author.name,
author.email
})
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
path | yes |
path parameter |
message | yes |
The commit message. |
content | yes |
The new file content, using Base64 encoding. |
sha | no |
Required if you are updating a file. The blob SHA of the file being replaced. |
branch | no |
The branch name. Default: the repository’s default branch. |
committer | no |
The person that committed the file. Default: the authenticated user. |
committer.name | yes |
The name of the author or committer of the commit. You'll receive a |
committer.email | yes |
The email of the author or committer of the commit. You'll receive a |
committer.date | no | |
author | no |
The author of the file. Default: The |
author.name | yes |
The name of the author or committer of the commit. You'll receive a |
author.email | yes |
The email of the author or committer of the commit. You'll receive a |
author.date | no |
See also: GitHub Developer Guide documentation.
Create an organization repository ruleset
Create a repository ruleset for an organization.
octokit.rest.repos.createOrgRuleset({
org,
name,
enforcement,
bypass_actors[].actor_type,
bypass_actors[].bypass_mode,
rules[].type,
rules[].parameters.update_allows_fetch_and_merge,
rules[].parameters.required_deployment_environments,
rules[].parameters.dismiss_stale_reviews_on_push,
rules[].parameters.require_code_owner_review,
rules[].parameters.require_last_push_approval,
rules[].parameters.required_approving_review_count,
rules[].parameters.required_review_thread_resolution,
rules[].parameters.required_status_checks,
rules[].parameters.required_status_checks[].context,
rules[].parameters.strict_required_status_checks_policy,
rules[].parameters.operator,
rules[].parameters.pattern,
rules[].parameters.restricted_file_paths,
rules[].parameters.max_file_path_length,
rules[].parameters.restricted_file_extensions,
rules[].parameters.max_file_size,
rules[].parameters.workflows,
rules[].parameters.workflows[].path,
rules[].parameters.workflows[].repository_id
})
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
name | yes |
The name of the ruleset. |
target | no |
The target of the ruleset Note: The |
enforcement | yes |
The enforcement level of the ruleset. |
bypass_actors | no |
The actors that can bypass the rules in this ruleset |
bypass_actors[].actor_id | no |
The ID of the actor that can bypass a ruleset. If |
bypass_actors[].actor_type | yes |
The type of actor that can bypass a ruleset. |
bypass_actors[].bypass_mode | yes |
When the specified actor can bypass the ruleset. |
conditions | no |
Conditions for an organization ruleset. The conditions object should contain both |
rules | no |
An array of rules within the ruleset. |
rules[].type | yes | |
rules[].parameters | no | |
rules[].parameters.update_allows_fetch_and_merge | yes |
Branch can pull changes from its upstream repository |
rules[].parameters.required_deployment_environments | yes |
The environments that must be successfully deployed to before branches can be merged. |
rules[].parameters.dismiss_stale_reviews_on_push | yes |
New, reviewable commits pushed will dismiss previous pull request review approvals. |
rules[].parameters.require_code_owner_review | yes |
Require an approving review in pull requests that modify files that have a designated code owner. |
rules[].parameters.require_last_push_approval | yes |
Whether the most recent reviewable push must be approved by someone other than the person who pushed it. |
rules[].parameters.required_approving_review_count | yes |
The number of approving reviews that are required before a pull request can be merged. |
rules[].parameters.required_review_thread_resolution | yes |
All conversations on code must be resolved before a pull request can be merged. |
rules[].parameters.required_status_checks | yes |
Status checks that are required. |
rules[].parameters.required_status_checks[].context | yes |
The status check context name that must be present on the commit. |
rules[].parameters.required_status_checks[].integration_id | no |
The optional integration ID that this status check must originate from. |
rules[].parameters.strict_required_status_checks_policy | yes |
Whether pull requests targeting a matching branch must be tested with the latest code. This setting will not take effect unless at least one status check is enabled. |
rules[].parameters.name | no |
How this rule will appear to users. |
rules[].parameters.negate | no |
If true, the rule will fail if the pattern matches. |
rules[].parameters.operator | yes |
The operator to use for matching. |
rules[].parameters.pattern | yes |
The pattern to match with. |
rules[].parameters.restricted_file_paths | yes |
The file paths that are restricted from being pushed to the commit graph. |
rules[].parameters.max_file_path_length | yes |
The maximum amount of characters allowed in file paths |
rules[].parameters.restricted_file_extensions | yes |
The file extensions that are restricted from being pushed to the commit graph. |
rules[].parameters.max_file_size | yes |
The maximum file size allowed in megabytes. This limit does not apply to Git Large File Storage (Git LFS). |
rules[].parameters.workflows | yes |
Workflows that must pass for this rule to pass. |
rules[].parameters.workflows[].path | yes |
The path to the workflow file |
rules[].parameters.workflows[].ref | no |
The ref (branch or tag) of the workflow file to use |
rules[].parameters.workflows[].repository_id | yes |
The ID of the repository where the workflow is defined |
rules[].parameters.workflows[].sha | no |
The commit SHA of the workflow file to use |
See also: GitHub Developer Guide documentation.
Create a GitHub Pages deployment
Create a GitHub Pages deployment for a repository.
The authenticated user must have write permission to the repository.
octokit.rest.repos.createPagesDeployment({
owner,
repo,
pages_build_version,
oidc_token,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
artifact_id | no |
The ID of an artifact that contains the .zip or .tar of static assets to deploy. The artifact belongs to the repository. Either |
artifact_url | no |
The URL of an artifact that contains the .zip or .tar of static assets to deploy. The artifact belongs to the repository. Either |
environment | no |
The target environment for this GitHub Pages deployment. |
pages_build_version | yes |
A unique string that represents the version of the build for this deployment. |
oidc_token | yes |
The OIDC token issued by GitHub Actions certifying the origin of the deployment. |
See also: GitHub Developer Guide documentation.
Create a GitHub Pages site
Configures a GitHub Pages site. For more information, see "About GitHub Pages."
The authenticated user must be a repository administrator, maintainer, or have the 'manage GitHub Pages settings' permission.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.repos.createPagesSite({
owner,
repo,
source.branch
})
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
build_type | no |
The process in which the Page will be built. Possible values are |
source | no |
The source branch and directory used to publish your Pages site. |
source.branch | yes |
The repository branch used to publish your site's source files. |
source.path | no |
The repository directory that includes the source files for the Pages site. Allowed paths are |
See also: GitHub Developer Guide documentation.
Create a release
Users with push access to the repository can create a release.
This endpoint triggers notifications. Creating content too quickly using this endpoint may result in secondary rate limiting. For more information, see "Rate limits for the API" and "Best practices for using the REST API."
octokit.rest.repos.createRelease({
owner,
repo,
tag_name,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
tag_name | yes |
The name of the tag. |
target_commitish | no |
Specifies the commitish value that determines where the Git tag is created from. Can be any branch or commit SHA. Unused if the Git tag already exists. Default: the repository's default branch. |
name | no |
The name of the release. |
body | no |
Text describing the contents of the tag. |
draft | no |
|
prerelease | no |
|
discussion_category_name | no |
If specified, a discussion of the specified category is created and linked to the release. The value must be a category that already exists in the repository. For more information, see "Managing categories for discussions in your repository." |
generate_release_notes | no |
Whether to automatically generate the name and body for this release. If |
make_latest | no |
Specifies whether this release should be set as the latest release for the repository. Drafts and prereleases cannot be set as latest. Defaults to |
See also: GitHub Developer Guide documentation.
Create a repository ruleset
Create a ruleset for a repository.
octokit.rest.repos.createRepoRuleset({
owner,
repo,
name,
enforcement,
bypass_actors[].actor_type,
bypass_actors[].bypass_mode,
rules[].type,
rules[].parameters.update_allows_fetch_and_merge,
rules[].parameters.required_deployment_environments,
rules[].parameters.dismiss_stale_reviews_on_push,
rules[].parameters.require_code_owner_review,
rules[].parameters.require_last_push_approval,
rules[].parameters.required_approving_review_count,
rules[].parameters.required_review_thread_resolution,
rules[].parameters.required_status_checks,
rules[].parameters.required_status_checks[].context,
rules[].parameters.strict_required_status_checks_policy,
rules[].parameters.operator,
rules[].parameters.pattern,
rules[].parameters.restricted_file_paths,
rules[].parameters.max_file_path_length,
rules[].parameters.restricted_file_extensions,
rules[].parameters.max_file_size,
rules[].parameters.workflows,
rules[].parameters.workflows[].path,
rules[].parameters.workflows[].repository_id
})
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
name | yes |
The name of the ruleset. |
target | no |
The target of the ruleset Note: The |
enforcement | yes |
The enforcement level of the ruleset. |
bypass_actors | no |
The actors that can bypass the rules in this ruleset |
bypass_actors[].actor_id | no |
The ID of the actor that can bypass a ruleset. If |
bypass_actors[].actor_type | yes |
The type of actor that can bypass a ruleset. |
bypass_actors[].bypass_mode | yes |
When the specified actor can bypass the ruleset. |
conditions | no |
Parameters for a repository ruleset ref name condition |
conditions.ref_name | no | |
conditions.ref_name.include | no |
Array of ref names or patterns to include. One of these patterns must match for the condition to pass. Also accepts |
conditions.ref_name.exclude | no |
Array of ref names or patterns to exclude. The condition will not pass if any of these patterns match. |
rules | no |
An array of rules within the ruleset. |
rules[].type | yes | |
rules[].parameters | no | |
rules[].parameters.update_allows_fetch_and_merge | yes |
Branch can pull changes from its upstream repository |
rules[].parameters.required_deployment_environments | yes |
The environments that must be successfully deployed to before branches can be merged. |
rules[].parameters.dismiss_stale_reviews_on_push | yes |
New, reviewable commits pushed will dismiss previous pull request review approvals. |
rules[].parameters.require_code_owner_review | yes |
Require an approving review in pull requests that modify files that have a designated code owner. |
rules[].parameters.require_last_push_approval | yes |
Whether the most recent reviewable push must be approved by someone other than the person who pushed it. |
rules[].parameters.required_approving_review_count | yes |
The number of approving reviews that are required before a pull request can be merged. |
rules[].parameters.required_review_thread_resolution | yes |
All conversations on code must be resolved before a pull request can be merged. |
rules[].parameters.required_status_checks | yes |
Status checks that are required. |
rules[].parameters.required_status_checks[].context | yes |
The status check context name that must be present on the commit. |
rules[].parameters.required_status_checks[].integration_id | no |
The optional integration ID that this status check must originate from. |
rules[].parameters.strict_required_status_checks_policy | yes |
Whether pull requests targeting a matching branch must be tested with the latest code. This setting will not take effect unless at least one status check is enabled. |
rules[].parameters.name | no |
How this rule will appear to users. |
rules[].parameters.negate | no |
If true, the rule will fail if the pattern matches. |
rules[].parameters.operator | yes |
The operator to use for matching. |
rules[].parameters.pattern | yes |
The pattern to match with. |
rules[].parameters.restricted_file_paths | yes |
The file paths that are restricted from being pushed to the commit graph. |
rules[].parameters.max_file_path_length | yes |
The maximum amount of characters allowed in file paths |
rules[].parameters.restricted_file_extensions | yes |
The file extensions that are restricted from being pushed to the commit graph. |
rules[].parameters.max_file_size | yes |
The maximum file size allowed in megabytes. This limit does not apply to Git Large File Storage (Git LFS). |
rules[].parameters.workflows | yes |
Workflows that must pass for this rule to pass. |
rules[].parameters.workflows[].path | yes |
The path to the workflow file |
rules[].parameters.workflows[].ref | no |
The ref (branch or tag) of the workflow file to use |
rules[].parameters.workflows[].repository_id | yes |
The ID of the repository where the workflow is defined |
rules[].parameters.workflows[].sha | no |
The commit SHA of the workflow file to use |
See also: GitHub Developer Guide documentation.
Create a tag protection state for a repository
This creates a tag protection state for a repository. This endpoint is only available to repository administrators.
octokit.rest.repos.createTagProtection({
owner,
repo,
pattern,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
pattern | yes |
An optional glob pattern to match against when enforcing tag protection. |
See also: GitHub Developer Guide documentation.
Create a repository using a template
Creates a new repository using a repository template. Use the template_owner
and template_repo
route parameters to specify the repository to use as the template. If the repository is not public, the authenticated user must own or be a member of an organization that owns the repository. To check if a repository is available to use as a template, get the repository's information using the Get a repository endpoint and check that the is_template
key is true
.
OAuth app tokens and personal access tokens (classic) need the public_repo
or repo
scope to create a public repository, and repo
scope to create a private repository.
octokit.rest.repos.createUsingTemplate({
template_owner,
template_repo,
name,
});
Parameters
name | required | description |
---|---|---|
template_owner | yes |
The account owner of the template repository. The name is not case sensitive. |
template_repo | yes |
The name of the template repository without the |
owner | no |
The organization or person who will own the new repository. To create a new repository in an organization, the authenticated user must be a member of the specified organization. |
name | yes |
The name of the new repository. |
description | no |
A short description of the new repository. |
include_all_branches | no |
Set to |
private | no |
Either |
See also: GitHub Developer Guide documentation.
Create a repository webhook
Repositories can have multiple webhooks installed. Each webhook should have a unique config
. Multiple webhooks can
share the same config
as long as those webhooks do not have any events
that overlap.
octokit.rest.repos.createWebhook({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
name | no |
Use |
config | no |
Key/value pairs to provide settings for this webhook. |
config.url | no |
The URL to which the payloads will be delivered. |
config.content_type | no |
The media type used to serialize the payloads. Supported values include |
config.secret | no |
If provided, the |
config.insecure_ssl | no | |
events | no |
Determines what events the hook is triggered for. |
active | no |
Determines if notifications are sent when the webhook is triggered. Set to |
See also: GitHub Developer Guide documentation.
Decline a repository invitation
Deprecated: This method has been renamed to repos.declineInvitationForAuthenticatedUser
octokit.rest.repos.declineInvitation({
invitation_id,
});
Parameters
name | required | description |
---|---|---|
invitation_id | yes |
The unique identifier of the invitation. |
See also: GitHub Developer Guide documentation.
Decline a repository invitation
octokit.rest.repos.declineInvitationForAuthenticatedUser({
invitation_id,
});
Parameters
name | required | description |
---|---|---|
invitation_id | yes |
The unique identifier of the invitation. |
See also: GitHub Developer Guide documentation.
Delete a repository
Deleting a repository requires admin access.
If an organization owner has configured the organization to prevent members from deleting organization-owned
repositories, you will get a 403 Forbidden
response.
OAuth app tokens and personal access tokens (classic) need the delete_repo
scope to use this endpoint.
octokit.rest.repos.delete({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Delete access restrictions
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.
Disables the ability to restrict who can push to this branch.
octokit.rest.repos.deleteAccessRestrictions({
owner,
repo,
branch,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
branch | yes |
The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API. |
See also: GitHub Developer Guide documentation.
Delete admin branch protection
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.
Removing admin enforcement requires admin or owner permissions to the repository and branch protection to be enabled.
octokit.rest.repos.deleteAdminBranchProtection({
owner,
repo,
branch,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
branch | yes |
The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API. |
See also: GitHub Developer Guide documentation.
Delete an environment
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.repos.deleteAnEnvironment({
owner,
repo,
environment_name,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
environment_name | yes |
The name of the environment. The name must be URL encoded. For example, any slashes in the name must be replaced with |
See also: GitHub Developer Guide documentation.
Delete an autolink reference from a repository
This deletes a single autolink reference by ID that was configured for the given repository.
Information about autolinks are only available to repository administrators.
octokit.rest.repos.deleteAutolink({
owner,
repo,
autolink_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
autolink_id | yes |
The unique identifier of the autolink. |
See also: GitHub Developer Guide documentation.
Delete branch protection
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.
octokit.rest.repos.deleteBranchProtection({
owner,
repo,
branch,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
branch | yes |
The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API. |
See also: GitHub Developer Guide documentation.
Delete a commit comment
octokit.rest.repos.deleteCommitComment({
owner,
repo,
comment_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
comment_id | yes |
The unique identifier of the comment. |
See also: GitHub Developer Guide documentation.
Delete commit signature protection
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.
When authenticated with admin or owner permissions to the repository, you can use this endpoint to disable required signed commits on a branch. You must enable branch protection to require signed commits.
octokit.rest.repos.deleteCommitSignatureProtection({
owner,
repo,
branch,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
branch | yes |
The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API. |
See also: GitHub Developer Guide documentation.
Delete a deploy key
Deploy keys are immutable. If you need to update a key, remove the key and create a new one instead.
octokit.rest.repos.deleteDeployKey({
owner,
repo,
key_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
key_id | yes |
The unique identifier of the key. |
See also: GitHub Developer Guide documentation.
Delete a deployment
If the repository only has one deployment, you can delete the deployment regardless of its status. If the repository has more than one deployment, you can only delete inactive deployments. This ensures that repositories with multiple deployments will always have an active deployment.
To set a deployment as inactive, you must:
- Create a new deployment that is active so that the system has a record of the current state, then delete the previously active deployment.
- Mark the active deployment as inactive by adding any non-successful deployment status.
For more information, see "Create a deployment" and "Create a deployment status."
OAuth app tokens and personal access tokens (classic) need the repo
or repo_deployment
scope to use this endpoint.
octokit.rest.repos.deleteDeployment({
owner,
repo,
deployment_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
deployment_id | yes |
deployment_id parameter |
See also: GitHub Developer Guide documentation.
Delete a deployment branch policy
Deletes a deployment branch or tag policy for an environment.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.repos.deleteDeploymentBranchPolicy({
owner,
repo,
environment_name,
branch_policy_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
environment_name | yes |
The name of the environment. The name must be URL encoded. For example, any slashes in the name must be replaced with |
branch_policy_id | yes |
The unique identifier of the branch policy. |
See also: GitHub Developer Guide documentation.
Delete a file
Deletes a file in a repository.
You can provide an additional committer
parameter, which is an object containing information about the committer. Or, you can provide an author
parameter, which is an object containing information about the author.
The author
section is optional and is filled in with the committer
information if omitted. If the committer
information is omitted, the authenticated user's information is used.
You must provide values for both name
and email
, whether you choose to use author
or committer
. Otherwise, you'll receive a 422
status code.
Note: If you use this endpoint and the "Create or update file contents" endpoint in parallel, the concurrent requests will conflict and you will receive errors. You must use these endpoints serially instead.
octokit.rest.repos.deleteFile({
owner,
repo,
path,
message,
sha,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
path | yes |
path parameter |
message | yes |
The commit message. |
sha | yes |
The blob SHA of the file being deleted. |
branch | no |
The branch name. Default: the repository’s default branch |
committer | no |
object containing information about the committer. |
committer.name | no |
The name of the author (or committer) of the commit |
committer.email | no |
The email of the author (or committer) of the commit |
author | no |
object containing information about the author. |
author.name | no |
The name of the author (or committer) of the commit |
author.email | no |
The email of the author (or committer) of the commit |
See also: GitHub Developer Guide documentation.
Delete a repository invitation
octokit.rest.repos.deleteInvitation({
owner,
repo,
invitation_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
invitation_id | yes |
The unique identifier of the invitation. |
See also: GitHub Developer Guide documentation.
Delete an organization repository ruleset
Delete a ruleset for an organization.
octokit.rest.repos.deleteOrgRuleset({
org,
ruleset_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
ruleset_id | yes |
The ID of the ruleset. |
See also: GitHub Developer Guide documentation.
Delete a GitHub Pages site
Deletes a GitHub Pages site. For more information, see "About GitHub Pages.
The authenticated user must be a repository administrator, maintainer, or have the 'manage GitHub Pages settings' permission.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.repos.deletePagesSite({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Delete pull request review protection
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.
octokit.rest.repos.deletePullRequestReviewProtection({
owner,
repo,
branch,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
branch | yes |
The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API. |
See also: GitHub Developer Guide documentation.
Delete a release
Users with push access to the repository can delete a release.
octokit.rest.repos.deleteRelease({
owner,
repo,
release_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
release_id | yes |
The unique identifier of the release. |
See also: GitHub Developer Guide documentation.
Delete a release asset
octokit.rest.repos.deleteReleaseAsset({
owner,
repo,
asset_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
asset_id | yes |
The unique identifier of the asset. |
See also: GitHub Developer Guide documentation.
Delete a repository ruleset
Delete a ruleset for a repository.
octokit.rest.repos.deleteRepoRuleset({
owner,
repo,
ruleset_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
ruleset_id | yes |
The ID of the ruleset. |
See also: GitHub Developer Guide documentation.
Delete a tag protection state for a repository
This deletes a tag protection state for a repository. This endpoint is only available to repository administrators.
octokit.rest.repos.deleteTagProtection({
owner,
repo,
tag_protection_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
tag_protection_id | yes |
The unique identifier of the tag protection. |
See also: GitHub Developer Guide documentation.
Delete a repository webhook
octokit.rest.repos.deleteWebhook({
owner,
repo,
hook_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
hook_id | yes |
The unique identifier of the hook. You can find this value in the |
See also: GitHub Developer Guide documentation.
Disable automated security fixes
Disables automated security fixes for a repository. The authenticated user must have admin access to the repository. For more information, see "Configuring automated security fixes".
octokit.rest.repos.disableAutomatedSecurityFixes({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Disable a custom protection rule for an environment
Disables a custom deployment protection rule for an environment.
The authenticated user must have admin or owner permissions to the repository to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.repos.disableDeploymentProtectionRule({
environment_name,
repo,
owner,
protection_rule_id,
});
Parameters
name | required | description |
---|---|---|
environment_name | yes |
The name of the environment. The name must be URL encoded. For example, any slashes in the name must be replaced with |
repo | yes |
The name of the repository without the |
owner | yes |
The account owner of the repository. The name is not case sensitive. |
protection_rule_id | yes |
The unique identifier of the protection rule. |
See also: GitHub Developer Guide documentation.
Disable private vulnerability reporting for a repository
Disables private vulnerability reporting for a repository. The authenticated user must have admin access to the repository. For more information, see "Privately reporting a security vulnerability".
octokit.rest.repos.disablePrivateVulnerabilityReporting({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Disable vulnerability alerts
Disables dependency alerts and the dependency graph for a repository. The authenticated user must have admin access to the repository. For more information, see "About security alerts for vulnerable dependencies".
octokit.rest.repos.disableVulnerabilityAlerts({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Download a repository archive (zip)
Deprecated: This method has been renamed to repos.downloadZipballArchive
Gets a redirect URL to download a zip archive for a repository. If you omit :ref
, the repository’s default branch (usually
main
) will be used. Please make sure your HTTP framework is configured to follow redirects or you will need to use
the Location
header to make a second GET
request.
Note: For private repositories, these links are temporary and expire after five minutes. If the repository is empty, you will receive a 404 when you follow the redirect.
octokit.rest.repos.downloadArchive({
owner,
repo,
ref,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
ref | yes |
See also: GitHub Developer Guide documentation.
Download a repository archive (tar)
Gets a redirect URL to download a tar archive for a repository. If you omit :ref
, the repository’s default branch (usually
main
) will be used. Please make sure your HTTP framework is configured to follow redirects or you will need to use
the Location
header to make a second GET
request.
Note: For private repositories, these links are temporary and expire after five minutes.
octokit.rest.repos.downloadTarballArchive({
owner,
repo,
ref,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
ref | yes |
See also: GitHub Developer Guide documentation.
Download a repository archive (zip)
Gets a redirect URL to download a zip archive for a repository. If you omit :ref
, the repository’s default branch (usually
main
) will be used. Please make sure your HTTP framework is configured to follow redirects or you will need to use
the Location
header to make a second GET
request.
Note: For private repositories, these links are temporary and expire after five minutes. If the repository is empty, you will receive a 404 when you follow the redirect.
octokit.rest.repos.downloadZipballArchive({
owner,
repo,
ref,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
ref | yes |
See also: GitHub Developer Guide documentation.
Enable automated security fixes
Enables automated security fixes for a repository. The authenticated user must have admin access to the repository. For more information, see "Configuring automated security fixes".
octokit.rest.repos.enableAutomatedSecurityFixes({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Enable private vulnerability reporting for a repository
Enables private vulnerability reporting for a repository. The authenticated user must have admin access to the repository. For more information, see "Privately reporting a security vulnerability."
octokit.rest.repos.enablePrivateVulnerabilityReporting({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Enable vulnerability alerts
Enables dependency alerts and the dependency graph for a repository. The authenticated user must have admin access to the repository. For more information, see "About security alerts for vulnerable dependencies".
octokit.rest.repos.enableVulnerabilityAlerts({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Generate release notes content for a release
Generate a name and body describing a release. The body content will be markdown formatted and contain information like the changes since last release and users who contributed. The generated release notes are not saved anywhere. They are intended to be generated and used when creating a new release.
octokit.rest.repos.generateReleaseNotes({
owner,
repo,
tag_name,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
tag_name | yes |
The tag name for the release. This can be an existing tag or a new one. |
target_commitish | no |
Specifies the commitish value that will be the target for the release's tag. Required if the supplied tag_name does not reference an existing tag. Ignored if the tag_name already exists. |
previous_tag_name | no |
The name of the previous tag to use as the starting point for the release notes. Use to manually specify the range for the set of changes considered as part this release. |
configuration_file_path | no |
Specifies a path to a file in the repository containing configuration settings used for generating the release notes. If unspecified, the configuration file located in the repository at '.github/release.yml' or '.github/release.yaml' will be used. If that is not present, the default configuration will be used. |
See also: GitHub Developer Guide documentation.
Get a repository
The parent
and source
objects are present when the repository is a fork. parent
is the repository this repository was forked from, source
is the ultimate source for the network.
Note: In order to see the security_and_analysis
block for a repository you must have admin permissions for the repository or be an owner or security manager for the organization that owns the repository. For more information, see "Managing security managers in your organization."
octokit.rest.repos.get({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Get access restrictions
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.
Lists who has access to this protected branch.
Note: Users, apps, and teams restrictions
are only available for organization-owned repositories.
octokit.rest.repos.getAccessRestrictions({
owner,
repo,
branch,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
branch | yes |
The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API. |
See also: GitHub Developer Guide documentation.
Get admin branch protection
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.
octokit.rest.repos.getAdminBranchProtection({
owner,
repo,
branch,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
branch | yes |
The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API. |
See also: GitHub Developer Guide documentation.
Get all deployment protection rules for an environment
Gets all custom deployment protection rules that are enabled for an environment. Anyone with read access to the repository can use this endpoint. For more information about environments, see "Using environments for deployment."
For more information about the app that is providing this custom deployment rule, see the documentation for the GET /apps/{app_slug}
endpoint.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint with a private repository.
octokit.rest.repos.getAllDeploymentProtectionRules({
environment_name,
repo,
owner,
});
Parameters
name | required | description |
---|---|---|
environment_name | yes |
The name of the environment. The name must be URL encoded. For example, any slashes in the name must be replaced with |
repo | yes |
The name of the repository without the |
owner | yes |
The account owner of the repository. The name is not case sensitive. |
See also: GitHub Developer Guide documentation.
List environments
Lists the environments for a repository.
Anyone with read access to the repository can use this endpoint.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint with a private repository.
octokit.rest.repos.getAllEnvironments({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
Get all status check contexts
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.
octokit.rest.repos.getAllStatusCheckContexts({
owner,
repo,
branch,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
branch | yes |
The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API. |
See also: GitHub Developer Guide documentation.
Get all repository topics
octokit.rest.repos.getAllTopics({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
Get apps with access to the protected branch
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.
Lists the GitHub Apps that have push access to this branch. Only GitHub Apps that are installed on the repository and that have been granted write access to the repository contents can be added as authorized actors on a protected branch.
octokit.rest.repos.getAppsWithAccessToProtectedBranch({
owner,
repo,
branch,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
branch | yes |
The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API. |
See also: GitHub Developer Guide documentation.
Get an autolink reference of a repository
This returns a single autolink reference by ID that was configured for the given repository.
Information about autolinks are only available to repository administrators.
octokit.rest.repos.getAutolink({
owner,
repo,
autolink_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
autolink_id | yes |
The unique identifier of the autolink. |
See also: GitHub Developer Guide documentation.
Get a branch
octokit.rest.repos.getBranch({
owner,
repo,
branch,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
branch | yes |
The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API. |
See also: GitHub Developer Guide documentation.
Get branch protection
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.
octokit.rest.repos.getBranchProtection({
owner,
repo,
branch,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
branch | yes |
The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API. |
See also: GitHub Developer Guide documentation.
Get rules for a branch
Returns all active rules that apply to the specified branch. The branch does not need to exist; rules that would apply to a branch with that name will be returned. All active rules that apply will be returned, regardless of the level at which they are configured (e.g. repository or organization). Rules in rulesets with "evaluate" or "disabled" enforcement statuses are not returned.
octokit.rest.repos.getBranchRules({
owner,
repo,
branch,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
branch | yes |
The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
Get repository clones
Get the total number of clones and breakdown per day or week for the last 14 days. Timestamps are aligned to UTC midnight of the beginning of the day or week. Week begins on Monday.
octokit.rest.repos.getClones({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
per | no |
The time frame to display results for. |
See also: GitHub Developer Guide documentation.
Get the weekly commit activity
Returns a weekly aggregate of the number of additions and deletions pushed to a repository.
Note: This endpoint can only be used for repositories with fewer than 10,000 commits. If the repository contains 10,000 or more commits, a 422 status code will be returned.
octokit.rest.repos.getCodeFrequencyStats({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Get repository permissions for a user
Checks the repository permission of a collaborator. The possible repository
permissions are admin
, write
, read
, and none
.
Note: The permission
attribute provides the legacy base roles of admin
, write
, read
, and none
, where the
maintain
role is mapped to write
and the triage
role is mapped to read
. To determine the role assigned to the
collaborator, see the role_name
attribute, which will provide the full role name, including custom roles. The
permissions
hash can also be used to determine which base level of access the collaborator has to the repository.
octokit.rest.repos.getCollaboratorPermissionLevel({
owner,
repo,
username,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
username | yes |
The handle for the GitHub user account. |
See also: GitHub Developer Guide documentation.
Get the combined status for a specific reference
Users with pull access in a repository can access a combined view of commit statuses for a given ref. The ref can be a SHA, a branch name, or a tag name.
Additionally, a combined state
is returned. The state
is one of:
- failure if any of the contexts report as
error
orfailure
- pending if there are no statuses or a context is
pending
- success if the latest status for all contexts is
success
octokit.rest.repos.getCombinedStatusForRef({
owner,
repo,
ref,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
ref | yes |
The commit reference. Can be a commit SHA, branch name ( |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
Get a commit
Returns the contents of a single commit reference. You must have read
access for the repository to use this endpoint.
Note: If there are more than 300 files in the commit diff and the default JSON media type is requested, the response will include pagination link headers for the remaining files, up to a limit of 3000 files. Each page contains the static commit information, and the only changes are to the file listing.
This endpoint supports the following custom media types. For more information, see "Media types." Pagination query parameters are not supported for these media types.
application/vnd.github.diff
: Returns the diff of the commit. Larger diffs may time out and return a 5xx status code.application/vnd.github.patch
: Returns the patch of the commit. Diffs with binary data will have nopatch
property. Larger diffs may time out and return a 5xx status code.application/vnd.github.sha
: Returns the commit's SHA-1 hash. You can use this endpoint to check if a remote reference's SHA-1 hash is the same as your local reference's SHA-1 hash by providing the local SHA-1 reference as the ETag.
Signature verification object
The response will include a verification
object that describes the result of verifying the commit's signature. The following fields are included in the verification
object:
Name | Type | Description |
---|---|---|
verified | boolean | Indicates whether GitHub considers the signature in this commit to be verified. |
reason | string | The reason for verified value. Possible values and their meanings are enumerated in table below. |
signature | string | The signature that was extracted from the commit. |
payload | string | The value that was signed. |
These are the possible values for reason
in the verification
object:
Value | Description |
---|---|
expired_key | The key that made the signature is expired. |
not_signing_key | The "signing" flag is not among the usage flags in the GPG key that made the signature. |
gpgverify_error | There was an error communicating with the signature verification service. |
gpgverify_unavailable | The signature verification service is currently unavailable. |
unsigned | The object does not include a signature. |
unknown_signature_type | A non-PGP signature was found in the commit. |
no_user | No user was associated with the committer email address in the commit. |
unverified_email | The committer email address in the commit was associated with a user, but the email address is not verified on their account. |
bad_email | The committer email address in the commit is not included in the identities of the PGP key that made the signature. |
unknown_key | The key that made the signature has not been registered with any user's account. |
malformed_signature | There was an error parsing the signature. |
invalid | The signature could not be cryptographically verified using the key whose key-id was found in the signature. |
valid | None of the above errors applied, so the signature is considered to be verified. |
octokit.rest.repos.getCommit({
owner,
repo,
ref,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
ref | yes |
The commit reference. Can be a commit SHA, branch name ( |
See also: GitHub Developer Guide documentation.
Get the last year of commit activity
Returns the last year of commit activity grouped by week. The days
array is a group of commits per day, starting on Sunday
.
octokit.rest.repos.getCommitActivityStats({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Get a commit comment
Gets a specified commit comment.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github-commitcomment.raw+json
: Returns the raw markdown body. Response will includebody
. This is the default if you do not pass any specific media type.application/vnd.github-commitcomment.text+json
: Returns a text only representation of the markdown body. Response will includebody_text
.application/vnd.github-commitcomment.html+json
: Returns HTML rendered from the body's markdown. Response will includebody_html
.application/vnd.github-commitcomment.full+json
: Returns raw, text, and HTML representations. Response will includebody
,body_text
, andbody_html
.
octokit.rest.repos.getCommitComment({
owner,
repo,
comment_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
comment_id | yes |
The unique identifier of the comment. |
See also: GitHub Developer Guide documentation.
Get commit signature protection
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.
When authenticated with admin or owner permissions to the repository, you can use this endpoint to check whether a branch requires signed commits. An enabled status of true
indicates you must sign commits on this branch. For more information, see Signing commits with GPG in GitHub Help.
Note: You must enable branch protection to require signed commits.
octokit.rest.repos.getCommitSignatureProtection({
owner,
repo,
branch,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
branch | yes |
The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API. |
See also: GitHub Developer Guide documentation.
Get community profile metrics
Returns all community profile metrics for a repository. The repository cannot be a fork.
The returned metrics include an overall health score, the repository description, the presence of documentation, the detected code of conduct, the detected license, and the presence of ISSUE_TEMPLATE, PULL_REQUEST_TEMPLATE, README, and CONTRIBUTING files.
The health_percentage
score is defined as a percentage of how many of
the recommended community health files are present. For more information, see
"About community profiles for public repositories."
content_reports_enabled
is only returned for organization-owned repositories.
octokit.rest.repos.getCommunityProfileMetrics({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Get repository content
Gets the contents of a file or directory in a repository. Specify the file path or directory with the path
parameter. If you omit the path
parameter, you will receive the contents of the repository's root directory.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github.raw+json
: Returns the raw file contents for files and symlinks.application/vnd.github.html+json
: Returns the file contents in HTML. Markup languages are rendered to HTML using GitHub's open-source Markup library.application/vnd.github.object+json
: Returns the contents in a consistent object format regardless of the content type. For example, instead of an array of objects for a directory, the response will be an object with anentries
attribute containing the array of objects.
If the content is a directory, the response will be an array of objects, one object for each item in the directory. When listing the contents of a directory, submodules have their "type" specified as "file". Logically, the value should be "submodule". This behavior exists for backwards compatibility purposes. In the next major version of the API, the type will be returned as "submodule".
If the content is a symlink and the symlink's target is a normal file in the repository, then the API responds with the content of the file. Otherwise, the API responds with an object describing the symlink itself.
If the content is a submodule, the submodule_git_url
field identifies the location of the submodule repository, and the sha
identifies a specific commit within the submodule repository. Git uses the given URL when cloning the submodule repository, and checks out the submodule at that specific commit. If the submodule repository is not hosted on github.com, the Git URLs (git_url
and _links["git"]
) and the github.com URLs (html_url
and _links["html"]
) will have null values.
Notes:
- To get a repository's contents recursively, you can recursively get the tree.
- This API has an upper limit of 1,000 files for a directory. If you need to retrieve more files, use the Git Trees API.
- Download URLs expire and are meant to be used just once. To ensure the download URL does not expire, please use the contents API to obtain a fresh download URL for each download.
- If the requested file's size is:
- 1 MB or smaller: All features of this endpoint are supported.
- Between 1-100 MB: Only the
raw
orobject
custom media types are supported. Both will work as normal, except that when using theobject
media type, thecontent
field will be an empty string and theencoding
field will be"none"
. To get the contents of these larger files, use theraw
media type. - Greater than 100 MB: This endpoint is not supported.
octokit.rest.repos.getContent({
owner,
repo,
path,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
path | yes |
path parameter |
ref | no |
The name of the commit/branch/tag. Default: the repository’s default branch. |
See also: GitHub Developer Guide documentation.
Get all contributor commit activity
Returns the total
number of commits authored by the contributor. In addition, the response includes a Weekly Hash (weeks
array) with the following information:
w
- Start of the week, given as a Unix timestamp.a
- Number of additionsd
- Number of deletionsc
- Number of commits
Note: This endpoint will return 0
values for all addition and deletion counts in repositories with 10,000 or more commits.
octokit.rest.repos.getContributorsStats({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Get a custom deployment protection rule
Gets an enabled custom deployment protection rule for an environment. Anyone with read access to the repository can use this endpoint. For more information about environments, see "Using environments for deployment."
For more information about the app that is providing this custom deployment rule, see GET /apps/{app_slug}
.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint with a private repository.
octokit.rest.repos.getCustomDeploymentProtectionRule({
owner,
repo,
environment_name,
protection_rule_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
environment_name | yes |
The name of the environment. The name must be URL encoded. For example, any slashes in the name must be replaced with |
protection_rule_id | yes |
The unique identifier of the protection rule. |
See also: GitHub Developer Guide documentation.
Get all custom property values for a repository
Gets all custom property values that are set for a repository. Users with read access to the repository can use this endpoint.
octokit.rest.repos.getCustomPropertiesValues({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Get a deploy key
octokit.rest.repos.getDeployKey({
owner,
repo,
key_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
key_id | yes |
The unique identifier of the key. |
See also: GitHub Developer Guide documentation.
Get a deployment
octokit.rest.repos.getDeployment({
owner,
repo,
deployment_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
deployment_id | yes |
deployment_id parameter |
See also: GitHub Developer Guide documentation.
Get a deployment branch policy
Gets a deployment branch or tag policy for an environment.
Anyone with read access to the repository can use this endpoint.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint with a private repository.
octokit.rest.repos.getDeploymentBranchPolicy({
owner,
repo,
environment_name,
branch_policy_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
environment_name | yes |
The name of the environment. The name must be URL encoded. For example, any slashes in the name must be replaced with |
branch_policy_id | yes |
The unique identifier of the branch policy. |
See also: GitHub Developer Guide documentation.
Get a deployment status
Users with pull access can view a deployment status for a deployment:
octokit.rest.repos.getDeploymentStatus({
owner,
repo,
deployment_id,
status_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
deployment_id | yes |
deployment_id parameter |
status_id | yes |
See also: GitHub Developer Guide documentation.
Get an environment
Note: To get information about name patterns that branches must match in order to deploy to this environment, see "Get a deployment branch policy."
Anyone with read access to the repository can use this endpoint.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint with a private repository.
octokit.rest.repos.getEnvironment({
owner,
repo,
environment_name,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
environment_name | yes |
The name of the environment. The name must be URL encoded. For example, any slashes in the name must be replaced with |
See also: GitHub Developer Guide documentation.
Get latest Pages build
Gets information about the single most recent build of a GitHub Pages site.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.repos.getLatestPagesBuild({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Get the latest release
View the latest published full release for the repository.
The latest release is the most recent non-prerelease, non-draft release, sorted by the created_at
attribute. The created_at
attribute is the date of the commit used for the release, and not the date when the release was drafted or published.
octokit.rest.repos.getLatestRelease({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Get an organization rule suite
Gets information about a suite of rule evaluations from within an organization. For more information, see "Managing rulesets for repositories in your organization."
octokit.rest.repos.getOrgRuleSuite({
org,
rule_suite_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
rule_suite_id | yes |
The unique identifier of the rule suite result. To get this ID, you can use GET /repos/{owner}/{repo}/rulesets/rule-suites for repositories and GET /orgs/{org}/rulesets/rule-suites for organizations. |
See also: GitHub Developer Guide documentation.
List organization rule suites
Lists suites of rule evaluations at the organization level. For more information, see "Managing rulesets for repositories in your organization."
octokit.rest.repos.getOrgRuleSuites({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
repository_name | no |
The name of the repository to filter on. When specified, only rule evaluations from this repository will be returned. |
time_period | no |
The time period to filter by. For example, |
actor_name | no |
The handle for the GitHub user account to filter on. When specified, only rule evaluations triggered by this actor will be returned. |
rule_suite_result | no |
The rule results to filter on. When specified, only suites with this result will be returned. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
Get an organization repository ruleset
Get a repository ruleset for an organization.
octokit.rest.repos.getOrgRuleset({
org,
ruleset_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
ruleset_id | yes |
The ID of the ruleset. |
See also: GitHub Developer Guide documentation.
Get all organization repository rulesets
Get all the repository rulesets for an organization.
octokit.rest.repos.getOrgRulesets({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
Get a GitHub Pages site
Gets information about a GitHub Pages site.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.repos.getPages({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Get GitHub Pages build
Gets information about a GitHub Pages build.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.repos.getPagesBuild({
owner,
repo,
build_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
build_id | yes |
See also: GitHub Developer Guide documentation.
Get the status of a GitHub Pages deployment
Gets the current status of a GitHub Pages deployment.
The authenticated user must have read permission for the GitHub Pages site.
octokit.rest.repos.getPagesDeployment({
owner,
repo,
pages_deployment_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
pages_deployment_id | yes |
The ID of the Pages deployment. You can also give the commit SHA of the deployment. |
See also: GitHub Developer Guide documentation.
Get a DNS health check for GitHub Pages
Gets a health check of the DNS settings for the CNAME
record configured for a repository's GitHub Pages.
The first request to this endpoint returns a 202 Accepted
status and starts an asynchronous background task to get the results for the domain. After the background task completes, subsequent requests to this endpoint return a 200 OK
status with the health check results in the response.
The authenticated user must be a repository administrator, maintainer, or have the 'manage GitHub Pages settings' permission to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.repos.getPagesHealthCheck({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Get the weekly commit count
Returns the total commit counts for the owner
and total commit counts in all
. all
is everyone combined, including the owner
in the last 52 weeks. If you'd like to get the commit counts for non-owners, you can subtract owner
from all
.
The array order is oldest week (index 0) to most recent week.
The most recent week is seven days ago at UTC midnight to today at UTC midnight.
octokit.rest.repos.getParticipationStats({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Get pull request review protection
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.
octokit.rest.repos.getPullRequestReviewProtection({
owner,
repo,
branch,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
branch | yes |
The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API. |
See also: GitHub Developer Guide documentation.
Get the hourly commit count for each day
Each array contains the day number, hour number, and number of commits:
0-6
: Sunday - Saturday0-23
: Hour of day- Number of commits
For example, [2, 14, 25]
indicates that there were 25 total commits, during the 2:00pm hour on Tuesdays. All times are based on the time zone of individual commits.
octokit.rest.repos.getPunchCardStats({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Get a repository README
Gets the preferred README for a repository.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github.raw+json
: Returns the raw file contents. This is the default if you do not specify a media type.application/vnd.github.html+json
: Returns the README in HTML. Markup languages are rendered to HTML using GitHub's open-source Markup library.
octokit.rest.repos.getReadme({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
ref | no |
The name of the commit/branch/tag. Default: the repository’s default branch. |
See also: GitHub Developer Guide documentation.
Get a repository README for a directory
Gets the README from a repository directory.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github.raw+json
: Returns the raw file contents. This is the default if you do not specify a media type.application/vnd.github.html+json
: Returns the README in HTML. Markup languages are rendered to HTML using GitHub's open-source Markup library.
octokit.rest.repos.getReadmeInDirectory({
owner,
repo,
dir,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
dir | yes |
The alternate path to look for a README file |
ref | no |
The name of the commit/branch/tag. Default: the repository’s default branch. |
See also: GitHub Developer Guide documentation.
Get a release
Gets a public release with the specified release ID.
Note: This returns an upload_url
key corresponding to the endpoint
for uploading release assets. This key is a hypermedia resource. For more information, see
"Getting started with the REST API."
octokit.rest.repos.getRelease({
owner,
repo,
release_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
release_id | yes |
The unique identifier of the release. |
See also: GitHub Developer Guide documentation.
Get a release asset
To download the asset's binary content, set the Accept
header of the request to application/octet-stream
. The API will either redirect the client to the location, or stream it directly if possible. API clients should handle both a 200
or 302
response.
octokit.rest.repos.getReleaseAsset({
owner,
repo,
asset_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
asset_id | yes |
The unique identifier of the asset. |
See also: GitHub Developer Guide documentation.
Get a release by tag name
Get a published release with the specified tag.
octokit.rest.repos.getReleaseByTag({
owner,
repo,
tag,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
tag | yes |
tag parameter |
See also: GitHub Developer Guide documentation.
Get a repository rule suite
Gets information about a suite of rule evaluations from within a repository. For more information, see "Managing rulesets for a repository."
octokit.rest.repos.getRepoRuleSuite({
owner,
repo,
rule_suite_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
rule_suite_id | yes |
The unique identifier of the rule suite result. To get this ID, you can use GET /repos/{owner}/{repo}/rulesets/rule-suites for repositories and GET /orgs/{org}/rulesets/rule-suites for organizations. |
See also: GitHub Developer Guide documentation.
List repository rule suites
Lists suites of rule evaluations at the repository level. For more information, see "Managing rulesets for a repository."
octokit.rest.repos.getRepoRuleSuites({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
ref | no |
The name of the ref. Cannot contain wildcard characters. When specified, only rule evaluations triggered for this ref will be returned. |
time_period | no |
The time period to filter by. For example, |
actor_name | no |
The handle for the GitHub user account to filter on. When specified, only rule evaluations triggered by this actor will be returned. |
rule_suite_result | no |
The rule results to filter on. When specified, only suites with this result will be returned. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
Get a repository ruleset
Get a ruleset for a repository.
octokit.rest.repos.getRepoRuleset({
owner,
repo,
ruleset_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
ruleset_id | yes |
The ID of the ruleset. |
includes_parents | no |
Include rulesets configured at higher levels that apply to this repository |
See also: GitHub Developer Guide documentation.
Get all repository rulesets
Get all the rulesets for a repository.
octokit.rest.repos.getRepoRulesets({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
includes_parents | no |
Include rulesets configured at higher levels that apply to this repository |
See also: GitHub Developer Guide documentation.
Get status checks protection
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.
octokit.rest.repos.getStatusChecksProtection({
owner,
repo,
branch,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
branch | yes |
The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API. |
See also: GitHub Developer Guide documentation.
Get teams with access to the protected branch
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.
Lists the teams who have push access to this branch. The list includes child teams.
octokit.rest.repos.getTeamsWithAccessToProtectedBranch({
owner,
repo,
branch,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
branch | yes |
The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API. |
See also: GitHub Developer Guide documentation.
Get top referral paths
Get the top 10 popular contents over the last 14 days.
octokit.rest.repos.getTopPaths({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Get top referral sources
Get the top 10 referrers over the last 14 days.
octokit.rest.repos.getTopReferrers({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Get users with access to the protected branch
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.
Lists the people who have push access to this branch.
octokit.rest.repos.getUsersWithAccessToProtectedBranch({
owner,
repo,
branch,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
branch | yes |
The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API. |
See also: GitHub Developer Guide documentation.
Get page views
Get the total number of views and breakdown per day or week for the last 14 days. Timestamps are aligned to UTC midnight of the beginning of the day or week. Week begins on Monday.
octokit.rest.repos.getViews({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
per | no |
The time frame to display results for. |
See also: GitHub Developer Guide documentation.
Get a repository webhook
Returns a webhook configured in a repository. To get only the webhook config
properties, see "Get a webhook configuration for a repository."
octokit.rest.repos.getWebhook({
owner,
repo,
hook_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
hook_id | yes |
The unique identifier of the hook. You can find this value in the |
See also: GitHub Developer Guide documentation.
Get a webhook configuration for a repository
Returns the webhook configuration for a repository. To get more information about the webhook, including the active
state and events
, use "Get a repository webhook."
OAuth app tokens and personal access tokens (classic) need the read:repo_hook
or repo
scope to use this endpoint.
octokit.rest.repos.getWebhookConfigForRepo({
owner,
repo,
hook_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
hook_id | yes |
The unique identifier of the hook. You can find this value in the |
See also: GitHub Developer Guide documentation.
Get a delivery for a repository webhook
Returns a delivery for a webhook configured in a repository.
octokit.rest.repos.getWebhookDelivery({
owner,
repo,
hook_id,
delivery_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
hook_id | yes |
The unique identifier of the hook. You can find this value in the |
delivery_id | yes |
See also: GitHub Developer Guide documentation.
List repository activities
Lists a detailed history of changes to a repository, such as pushes, merges, force pushes, and branch changes, and associates these changes with commits and users.
For more information about viewing repository activity, see "Viewing activity and data for your repository."
octokit.rest.repos.listActivities({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
direction | no |
The direction to sort the results by. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
before | no |
A cursor, as given in the Link header. If specified, the query only searches for results before this cursor. For more information, see "Using pagination in the REST API." |
after | no |
A cursor, as given in the Link header. If specified, the query only searches for results after this cursor. For more information, see "Using pagination in the REST API." |
ref | no |
The Git reference for the activities you want to list. The |
actor | no |
The GitHub username to use to filter by the actor who performed the activity. |
time_period | no |
The time period to filter by. For example, |
activity_type | no |
The activity type to filter by. For example, you can choose to filter by "force_push", to see all force pushes to the repository. |
See also: GitHub Developer Guide documentation.
Get all autolinks of a repository
Gets all autolinks that are configured for a repository.
Information about autolinks are only available to repository administrators.
octokit.rest.repos.listAutolinks({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
List branches
octokit.rest.repos.listBranches({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
protected | no |
Setting to |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List branches for HEAD commit
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.
Returns all branches where the given commit SHA is the HEAD, or latest commit for the branch.
octokit.rest.repos.listBranchesForHeadCommit({
owner,
repo,
commit_sha,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
commit_sha | yes |
The SHA of the commit. |
See also: GitHub Developer Guide documentation.
List repository collaborators
For organization-owned repositories, the list of collaborators includes outside collaborators, organization members that are direct collaborators, organization members with access through team memberships, organization members with access through default organization permissions, and organization owners. Organization members with write, maintain, or admin privileges on the organization-owned repository can use this endpoint.
Team members will include the members of child teams.
The authenticated user must have push access to the repository to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the read:org
and repo
scopes to use this endpoint.
octokit.rest.repos.listCollaborators({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
affiliation | no |
Filter collaborators returned by their affiliation. |
permission | no |
Filter collaborators by the permissions they have on the repository. If not specified, all collaborators will be returned. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List commit comments
Lists the comments for a specified commit.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github-commitcomment.raw+json
: Returns the raw markdown body. Response will includebody
. This is the default if you do not pass any specific media type.application/vnd.github-commitcomment.text+json
: Returns a text only representation of the markdown body. Response will includebody_text
.application/vnd.github-commitcomment.html+json
: Returns HTML rendered from the body's markdown. Response will includebody_html
.application/vnd.github-commitcomment.full+json
: Returns raw, text, and HTML representations. Response will includebody
,body_text
, andbody_html
.
octokit.rest.repos.listCommentsForCommit({
owner,
repo,
commit_sha,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
commit_sha | yes |
The SHA of the commit. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List commit comments for a repository
Lists the commit comments for a specified repository. Comments are ordered by ascending ID.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github-commitcomment.raw+json
: Returns the raw markdown body. Response will includebody
. This is the default if you do not pass any specific media type.application/vnd.github-commitcomment.text+json
: Returns a text only representation of the markdown body. Response will includebody_text
.application/vnd.github-commitcomment.html+json
: Returns HTML rendered from the body's markdown. Response will includebody_html
.application/vnd.github-commitcomment.full+json
: Returns raw, text, and HTML representations. Response will includebody
,body_text
, andbody_html
.
octokit.rest.repos.listCommitCommentsForRepo({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List commit statuses for a reference
Users with pull access in a repository can view commit statuses for a given ref. The ref can be a SHA, a branch name, or a tag name. Statuses are returned in reverse chronological order. The first status in the list will be the latest one.
This resource is also available via a legacy route: GET /repos/:owner/:repo/statuses/:ref
.
octokit.rest.repos.listCommitStatusesForRef({
owner,
repo,
ref,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
ref | yes |
The commit reference. Can be a commit SHA, branch name ( |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List commits
Signature verification object
The response will include a verification
object that describes the result of verifying the commit's signature. The following fields are included in the verification
object:
Name | Type | Description |
---|---|---|
verified | boolean | Indicates whether GitHub considers the signature in this commit to be verified. |
reason | string | The reason for verified value. Possible values and their meanings are enumerated in table below. |
signature | string | The signature that was extracted from the commit. |
payload | string | The value that was signed. |
These are the possible values for reason
in the verification
object:
Value | Description |
---|---|
expired_key | The key that made the signature is expired. |
not_signing_key | The "signing" flag is not among the usage flags in the GPG key that made the signature. |
gpgverify_error | There was an error communicating with the signature verification service. |
gpgverify_unavailable | The signature verification service is currently unavailable. |
unsigned | The object does not include a signature. |
unknown_signature_type | A non-PGP signature was found in the commit. |
no_user | No user was associated with the committer email address in the commit. |
unverified_email | The committer email address in the commit was associated with a user, but the email address is not verified on their account. |
bad_email | The committer email address in the commit is not included in the identities of the PGP key that made the signature. |
unknown_key | The key that made the signature has not been registered with any user's account. |
malformed_signature | There was an error parsing the signature. |
invalid | The signature could not be cryptographically verified using the key whose key-id was found in the signature. |
valid | None of the above errors applied, so the signature is considered to be verified. |
octokit.rest.repos.listCommits({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
sha | no |
SHA or branch to start listing commits from. Default: the repository’s default branch (usually |
path | no |
Only commits containing this file path will be returned. |
author | no |
GitHub username or email address to use to filter by commit author. |
committer | no |
GitHub username or email address to use to filter by commit committer. |
since | no |
Only show results that were last updated after the given time. This is a timestamp in ISO 8601 format: |
until | no |
Only commits before this date will be returned. This is a timestamp in ISO 8601 format: |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List repository contributors
Lists contributors to the specified repository and sorts them by the number of commits per contributor in descending order. This endpoint may return information that is a few hours old because the GitHub REST API caches contributor data to improve performance.
GitHub identifies contributors by author email address. This endpoint groups contribution counts by GitHub user, which includes all associated email addresses. To improve performance, only the first 500 author email addresses in the repository link to GitHub users. The rest will appear as anonymous contributors without associated GitHub user information.
octokit.rest.repos.listContributors({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
anon | no |
Set to |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List custom deployment rule integrations available for an environment
Gets all custom deployment protection rule integrations that are available for an environment. Anyone with read access to the repository can use this endpoint.
For more information about environments, see "Using environments for deployment."
For more information about the app that is providing this custom deployment rule, see "GET an app".
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint with a private repository.
octokit.rest.repos.listCustomDeploymentRuleIntegrations({
environment_name,
repo,
owner,
});
Parameters
name | required | description |
---|---|---|
environment_name | yes |
The name of the environment. The name must be URL encoded. For example, any slashes in the name must be replaced with |
repo | yes |
The name of the repository without the |
owner | yes |
The account owner of the repository. The name is not case sensitive. |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List deploy keys
octokit.rest.repos.listDeployKeys({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List deployment branch policies
Lists the deployment branch policies for an environment.
Anyone with read access to the repository can use this endpoint.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint with a private repository.
octokit.rest.repos.listDeploymentBranchPolicies({
owner,
repo,
environment_name,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
environment_name | yes |
The name of the environment. The name must be URL encoded. For example, any slashes in the name must be replaced with |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List deployment statuses
Users with pull access can view deployment statuses for a deployment:
octokit.rest.repos.listDeploymentStatuses({
owner,
repo,
deployment_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
deployment_id | yes |
deployment_id parameter |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List deployments
Simple filtering of deployments is available via query parameters:
octokit.rest.repos.listDeployments({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
sha | no |
The SHA recorded at creation time. |
ref | no |
The name of the ref. This can be a branch, tag, or SHA. |
task | no |
The name of the task for the deployment (e.g., |
environment | no |
The name of the environment that was deployed to (e.g., |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List repositories for the authenticated user
Lists repositories that the authenticated user has explicit permission (:read
, :write
, or :admin
) to access.
The authenticated user has explicit permission to access repositories they own, repositories where they are a collaborator, and repositories that they can access through an organization membership.
octokit.rest.repos.listForAuthenticatedUser();
Parameters
name | required | description |
---|---|---|
visibility | no |
Limit results to repositories with the specified visibility. |
affiliation | no |
Comma-separated list of values. Can include:
|
type | no |
Limit results to repositories of the specified type. Will cause a |
sort | no |
The property to sort the results by. |
direction | no |
The order to sort by. Default: |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
since | no |
Only show repositories updated after the given time. This is a timestamp in ISO 8601 format: |
before | no |
Only show repositories updated before the given time. This is a timestamp in ISO 8601 format: |
See also: GitHub Developer Guide documentation.
List organization repositories
Lists repositories for the specified organization.
Note: In order to see the security_and_analysis
block for a repository you must have admin permissions for the repository or be an owner or security manager for the organization that owns the repository. For more information, see "Managing security managers in your organization."
octokit.rest.repos.listForOrg({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
type | no |
Specifies the types of repositories you want returned. |
sort | no |
The property to sort the results by. |
direction | no |
The order to sort by. Default: |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List repositories for a user
Lists public repositories for the specified user.
octokit.rest.repos.listForUser({
username,
});
Parameters
name | required | description |
---|---|---|
username | yes |
The handle for the GitHub user account. |
type | no |
Limit results to repositories of the specified type. |
sort | no |
The property to sort the results by. |
direction | no |
The order to sort by. Default: |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List forks
octokit.rest.repos.listForks({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
sort | no |
The sort order. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List repository invitations
When authenticating as a user with admin rights to a repository, this endpoint will list all currently open repository invitations.
octokit.rest.repos.listInvitations({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List repository invitations for the authenticated user
When authenticating as a user, this endpoint will list all currently open repository invitations for that user.
octokit.rest.repos.listInvitationsForAuthenticatedUser();
Parameters
name | required | description |
---|---|---|
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List repository languages
Lists languages for the specified repository. The value shown for each language is the number of bytes of code written in that language.
octokit.rest.repos.listLanguages({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
List GitHub Pages builds
Lists builts of a GitHub Pages site.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.repos.listPagesBuilds({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List public repositories
Lists all public repositories in the order that they were created.
Note:
- For GitHub Enterprise Server, this endpoint will only list repositories available to all users on the enterprise.
- Pagination is powered exclusively by the
since
parameter. Use the Link header to get the URL for the next page of repositories.
octokit.rest.repos.listPublic();
Parameters
name | required | description |
---|---|---|
since | no |
A repository ID. Only return repositories with an ID greater than this ID. |
See also: GitHub Developer Guide documentation.
List pull requests associated with a commit
Lists the merged pull request that introduced the commit to the repository. If the commit is not present in the default branch, will only return open pull requests associated with the commit.
To list the open or merged pull requests associated with a branch, you can set the commit_sha
parameter to the branch name.
octokit.rest.repos.listPullRequestsAssociatedWithCommit({
owner,
repo,
commit_sha,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
commit_sha | yes |
The SHA of the commit. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List release assets
octokit.rest.repos.listReleaseAssets({
owner,
repo,
release_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
release_id | yes |
The unique identifier of the release. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List releases
This returns a list of releases, which does not include regular Git tags that have not been associated with a release. To get a list of Git tags, use the Repository Tags API.
Information about published releases are available to everyone. Only users with push access will receive listings for draft releases.
octokit.rest.repos.listReleases({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List tag protection states for a repository
This returns the tag protection states of a repository.
This information is only available to repository administrators.
octokit.rest.repos.listTagProtection({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
List repository tags
octokit.rest.repos.listTags({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List repository teams
Lists the teams that have access to the specified repository and that are also visible to the authenticated user.
For a public repository, a team is listed only if that team added the public repository explicitly.
OAuth app tokens and personal access tokens (classic) need the public_repo
or repo
scope to use this endpoint with a public repository, and repo
scope to use this endpoint with a private repository.
octokit.rest.repos.listTeams({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List deliveries for a repository webhook
Returns a list of webhook deliveries for a webhook configured in a repository.
octokit.rest.repos.listWebhookDeliveries({
owner,
repo,
hook_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
hook_id | yes |
The unique identifier of the hook. You can find this value in the |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
cursor | no |
Used for pagination: the starting delivery from which the page of deliveries is fetched. Refer to the |
redelivery | no |
See also: GitHub Developer Guide documentation.
List repository webhooks
Lists webhooks for a repository. last response
may return null if there have not been any deliveries within 30 days.
octokit.rest.repos.listWebhooks({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
Merge a branch
octokit.rest.repos.merge({
owner,
repo,
base,
head,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
base | yes |
The name of the base branch that the head will be merged into. |
head | yes |
The head to merge. This can be a branch name or a commit SHA1. |
commit_message | no |
Commit message to use for the merge commit. If omitted, a default message will be used. |
See also: GitHub Developer Guide documentation.
Sync a fork branch with the upstream repository
Sync a branch of a forked repository to keep it up-to-date with the upstream repository.
octokit.rest.repos.mergeUpstream({
owner,
repo,
branch,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
branch | yes |
The name of the branch which should be updated to match upstream. |
See also: GitHub Developer Guide documentation.
Ping a repository webhook
This will trigger a ping event to be sent to the hook.
octokit.rest.repos.pingWebhook({
owner,
repo,
hook_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
hook_id | yes |
The unique identifier of the hook. You can find this value in the |
See also: GitHub Developer Guide documentation.
Redeliver a delivery for a repository webhook
Redeliver a webhook delivery for a webhook configured in a repository.
octokit.rest.repos.redeliverWebhookDelivery({
owner,
repo,
hook_id,
delivery_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
hook_id | yes |
The unique identifier of the hook. You can find this value in the |
delivery_id | yes |
See also: GitHub Developer Guide documentation.
Remove app access restrictions
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.
Removes the ability of an app to push to this branch. Only GitHub Apps that are installed on the repository and that have been granted write access to the repository contents can be added as authorized actors on a protected branch.
octokit.rest.repos.removeAppAccessRestrictions({
owner,
repo,
branch,
apps,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
branch | yes |
The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API. |
apps | yes |
See also: GitHub Developer Guide documentation.
Remove a repository collaborator
Removes a collaborator from a repository.
To use this endpoint, the authenticated user must either be an administrator of the repository or target themselves for removal.
This endpoint also:
- Cancels any outstanding invitations
- Unasigns the user from any issues
- Removes access to organization projects if the user is not an organization member and is not a collaborator on any other organization repositories.
- Unstars the repository
- Updates access permissions to packages
Removing a user as a collaborator has the following effects on forks:
- If the user had access to a fork through their membership to this repository, the user will also be removed from the fork.
- If the user had their own fork of the repository, the fork will be deleted.
- If the user still has read access to the repository, open pull requests by this user from a fork will be denied.
Note: A user can still have access to the repository through organization permissions like base repository permissions.
Although the API responds immediately, the additional permission updates might take some extra time to complete in the background.
For more information on fork permissions, see "About permissions and visibility of forks".
octokit.rest.repos.removeCollaborator({
owner,
repo,
username,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
username | yes |
The handle for the GitHub user account. |
See also: GitHub Developer Guide documentation.
Remove status check contexts
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.
octokit.rest.repos.removeStatusCheckContexts({
owner,
repo,
branch,
contexts,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
branch | yes |
The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API. |
contexts | yes |
See also: GitHub Developer Guide documentation.
Remove status check protection
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.
octokit.rest.repos.removeStatusCheckProtection({
owner,
repo,
branch,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
branch | yes |
The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API. |
See also: GitHub Developer Guide documentation.
Remove team access restrictions
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.
Removes the ability of a team to push to this branch. You can also remove push access for child teams.
octokit.rest.repos.removeTeamAccessRestrictions({
owner,
repo,
branch,
teams,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
branch | yes |
The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API. |
teams | yes |
See also: GitHub Developer Guide documentation.
Remove user access restrictions
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.
Removes the ability of a user to push to this branch.
Type | Description |
---|---|
array | Usernames of the people who should no longer have push access. Note: The list of users, apps, and teams in total is limited to 100 items. |
octokit.rest.repos.removeUserAccessRestrictions({
owner,
repo,
branch,
users,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
branch | yes |
The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API. |
users | yes |
See also: GitHub Developer Guide documentation.
Rename a branch
Renames a branch in a repository.
Note: Although the API responds immediately, the branch rename process might take some extra time to complete in the background. You won't be able to push to the old branch name while the rename process is in progress. For more information, see "Renaming a branch".
The authenticated user must have push access to the branch. If the branch is the default branch, the authenticated user must also have admin or owner permissions.
In order to rename the default branch, fine-grained access tokens also need the administration:write
repository permission.
octokit.rest.repos.renameBranch({
owner,
repo,
branch,
new_name,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
branch | yes |
The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API. |
new_name | yes |
The new name of the branch. |
See also: GitHub Developer Guide documentation.
Replace all repository topics
octokit.rest.repos.replaceAllTopics({
owner,
repo,
names,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
names | yes |
An array of topics to add to the repository. Pass one or more topics to replace the set of existing topics. Send an empty array ( |
See also: GitHub Developer Guide documentation.
Request a GitHub Pages build
You can request that your site be built from the latest revision on the default branch. This has the same effect as pushing a commit to your default branch, but does not require an additional commit. Manually triggering page builds can be helpful when diagnosing build warnings and failures.
Build requests are limited to one concurrent build per repository and one concurrent build per requester. If you request a build while another is still in progress, the second request will be queued until the first completes.
octokit.rest.repos.requestPagesBuild({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Set admin branch protection
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.
Adding admin enforcement requires admin or owner permissions to the repository and branch protection to be enabled.
octokit.rest.repos.setAdminBranchProtection({
owner,
repo,
branch,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
branch | yes |
The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API. |
See also: GitHub Developer Guide documentation.
Set app access restrictions
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.
Replaces the list of apps that have push access to this branch. This removes all apps that previously had push access and grants push access to the new list of apps. Only GitHub Apps that are installed on the repository and that have been granted write access to the repository contents can be added as authorized actors on a protected branch.
octokit.rest.repos.setAppAccessRestrictions({
owner,
repo,
branch,
apps,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
branch | yes |
The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API. |
apps | yes |
See also: GitHub Developer Guide documentation.
Set status check contexts
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.
octokit.rest.repos.setStatusCheckContexts({
owner,
repo,
branch,
contexts,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
branch | yes |
The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API. |
contexts | yes |
See also: GitHub Developer Guide documentation.
Set team access restrictions
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.
Replaces the list of teams that have push access to this branch. This removes all teams that previously had push access and grants push access to the new list of teams. Team restrictions include child teams.
octokit.rest.repos.setTeamAccessRestrictions({
owner,
repo,
branch,
teams,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
branch | yes |
The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API. |
teams | yes |
See also: GitHub Developer Guide documentation.
Set user access restrictions
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.
Replaces the list of people that have push access to this branch. This removes all people that previously had push access and grants push access to the new list of people.
Type | Description |
---|---|
array | Usernames for people who can have push access. Note: The list of users, apps, and teams in total is limited to 100 items. |
octokit.rest.repos.setUserAccessRestrictions({
owner,
repo,
branch,
users,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
branch | yes |
The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API. |
users | yes |
See also: GitHub Developer Guide documentation.
Test the push repository webhook
This will trigger the hook with the latest push to the current repository if the hook is subscribed to push
events. If the hook is not subscribed to push
events, the server will respond with 204 but no test POST will be generated.
Note: Previously /repos/:owner/:repo/hooks/:hook_id/test
octokit.rest.repos.testPushWebhook({
owner,
repo,
hook_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
hook_id | yes |
The unique identifier of the hook. You can find this value in the |
See also: GitHub Developer Guide documentation.
Transfer a repository
A transfer request will need to be accepted by the new owner when transferring a personal repository to another user. The response will contain the original owner
, and the transfer will continue asynchronously. For more details on the requirements to transfer personal and organization-owned repositories, see about repository transfers.
octokit.rest.repos.transfer({
owner,
repo,
new_owner,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
new_owner | yes |
The username or organization name the repository will be transferred to. |
new_name | no |
The new name to be given to the repository. |
team_ids | no |
ID of the team or teams to add to the repository. Teams can only be added to organization-owned repositories. |
See also: GitHub Developer Guide documentation.
Update a repository
Note: To edit a repository's topics, use the Replace all repository topics endpoint.
octokit.rest.repos.update({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
name | no |
The name of the repository. |
description | no |
A short description of the repository. |
homepage | no |
A URL with more information about the repository. |
private | no |
Either |
visibility | no |
The visibility of the repository. |
security_and_analysis | no |
Specify which security and analysis features to enable or disable for the repository. To use this parameter, you must have admin permissions for the repository or be an owner or security manager for the organization that owns the repository. For more information, see "Managing security managers in your organization." For example, to enable GitHub Advanced Security, use this data in the body of the You can check which security and analysis features are currently enabled by using a |
security_and_analysis.advanced_security | no |
Use the |
security_and_analysis.advanced_security.status | no |
Can be |
security_and_analysis.secret_scanning | no |
Use the |
security_and_analysis.secret_scanning.status | no |
Can be |
security_and_analysis.secret_scanning_push_protection | no |
Use the |
security_and_analysis.secret_scanning_push_protection.status | no |
Can be |
has_issues | no |
Either |
has_projects | no |
Either |
has_wiki | no |
Either |
is_template | no |
Either |
default_branch | no |
Updates the default branch for this repository. |
allow_squash_merge | no |
Either |
allow_merge_commit | no |
Either |
allow_rebase_merge | no |
Either |
allow_auto_merge | no |
Either |
delete_branch_on_merge | no |
Either |
allow_update_branch | no |
Either |
use_squash_pr_title_as_default | no |
Either |
squash_merge_commit_title | no |
The default value for a squash merge commit title:
|
squash_merge_commit_message | no |
The default value for a squash merge commit message:
|
merge_commit_title | no |
The default value for a merge commit title.
|
merge_commit_message | no |
The default value for a merge commit message.
|
archived | no |
Whether to archive this repository. |
allow_forking | no |
Either |
web_commit_signoff_required | no |
Either |
See also: GitHub Developer Guide documentation.
Update branch protection
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.
Protecting a branch requires admin or owner permissions to the repository.
Note: Passing new arrays of users
and teams
replaces their previous values.
Note: The list of users, apps, and teams in total is limited to 100 items.
octokit.rest.repos.updateBranchProtection({
owner,
repo,
branch,
required_status_checks,
required_status_checks.strict,
required_status_checks.contexts,
required_status_checks.checks[].context,
enforce_admins,
required_pull_request_reviews,
restrictions,
restrictions.users,
restrictions.teams
})
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
branch | yes |
The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API. |
required_status_checks | yes |
Require status checks to pass before merging. Set to |
required_status_checks.strict | yes |
Require branches to be up to date before merging. |
required_status_checks.contexts | yes |
Deprecated: The list of status checks to require in order to merge into this branch. If any of these checks have recently been set by a particular GitHub App, they will be required to come from that app in future for the branch to merge. Use |
required_status_checks.checks | no |
The list of status checks to require in order to merge into this branch. |
required_status_checks.checks[].context | yes |
The name of the required check |
required_status_checks.checks[].app_id | no |
The ID of the GitHub App that must provide this check. Omit this field to automatically select the GitHub App that has recently provided this check, or any app if it was not set by a GitHub App. Pass -1 to explicitly allow any app to set the status. |
enforce_admins | yes |
Enforce all configured restrictions for administrators. Set to |
required_pull_request_reviews | yes |
Require at least one approving review on a pull request, before merging. Set to |
required_pull_request_reviews.dismissal_restrictions | no |
Specify which users, teams, and apps can dismiss pull request reviews. Pass an empty |
required_pull_request_reviews.dismissal_restrictions.users | no |
The list of user |
required_pull_request_reviews.dismissal_restrictions.teams | no |
The list of team |
required_pull_request_reviews.dismissal_restrictions.apps | no |
The list of app |
required_pull_request_reviews.dismiss_stale_reviews | no |
Set to |
required_pull_request_reviews.require_code_owner_reviews | no |
Blocks merging pull requests until code owners review them. |
required_pull_request_reviews.required_approving_review_count | no |
Specify the number of reviewers required to approve pull requests. Use a number between 1 and 6 or 0 to not require reviewers. |
required_pull_request_reviews.require_last_push_approval | no |
Whether the most recent push must be approved by someone other than the person who pushed it. Default: |
required_pull_request_reviews.bypass_pull_request_allowances | no |
Allow specific users, teams, or apps to bypass pull request requirements. |
required_pull_request_reviews.bypass_pull_request_allowances.users | no |
The list of user |
required_pull_request_reviews.bypass_pull_request_allowances.teams | no |
The list of team |
required_pull_request_reviews.bypass_pull_request_allowances.apps | no |
The list of app |
restrictions | yes |
Restrict who can push to the protected branch. User, app, and team |
restrictions.users | yes |
The list of user |
restrictions.teams | yes |
The list of team |
restrictions.apps | no |
The list of app |
required_linear_history | no |
Enforces a linear commit Git history, which prevents anyone from pushing merge commits to a branch. Set to |
allow_force_pushes | no |
Permits force pushes to the protected branch by anyone with write access to the repository. Set to |
allow_deletions | no |
Allows deletion of the protected branch by anyone with write access to the repository. Set to |
block_creations | no |
If set to |
required_conversation_resolution | no |
Requires all conversations on code to be resolved before a pull request can be merged into a branch that matches this rule. Set to |
lock_branch | no |
Whether to set the branch as read-only. If this is true, users will not be able to push to the branch. Default: |
allow_fork_syncing | no |
Whether users can pull changes from upstream when the branch is locked. Set to |
See also: GitHub Developer Guide documentation.
Update a commit comment
Updates the contents of a specified commit comment.
This endpoint supports the following custom media types. For more information, see "Media types."
application/vnd.github-commitcomment.raw+json
: Returns the raw markdown body. Response will includebody
. This is the default if you do not pass any specific media type.application/vnd.github-commitcomment.text+json
: Returns a text only representation of the markdown body. Response will includebody_text
.application/vnd.github-commitcomment.html+json
: Returns HTML rendered from the body's markdown. Response will includebody_html
.application/vnd.github-commitcomment.full+json
: Returns raw, text, and HTML representations. Response will includebody
,body_text
, andbody_html
.
octokit.rest.repos.updateCommitComment({
owner,
repo,
comment_id,
body,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
comment_id | yes |
The unique identifier of the comment. |
body | yes |
The contents of the comment |
See also: GitHub Developer Guide documentation.
Update a deployment branch policy
Updates a deployment branch or tag policy for an environment.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.repos.updateDeploymentBranchPolicy({
owner,
repo,
environment_name,
branch_policy_id,
name,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
environment_name | yes |
The name of the environment. The name must be URL encoded. For example, any slashes in the name must be replaced with |
branch_policy_id | yes |
The unique identifier of the branch policy. |
name | yes |
The name pattern that branches must match in order to deploy to the environment. Wildcard characters will not match |
See also: GitHub Developer Guide documentation.
Update information about a GitHub Pages site
Updates information for a GitHub Pages site. For more information, see "About GitHub Pages.
The authenticated user must be a repository administrator, maintainer, or have the 'manage GitHub Pages settings' permission.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.repos.updateInformationAboutPagesSite({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
cname | no |
Specify a custom domain for the repository. Sending a |
https_enforced | no |
Specify whether HTTPS should be enforced for the repository. |
build_type | no |
The process by which the GitHub Pages site will be built. |
source | no |
See also: GitHub Developer Guide documentation.
Update a repository invitation
octokit.rest.repos.updateInvitation({
owner,
repo,
invitation_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
invitation_id | yes |
The unique identifier of the invitation. |
permissions | no |
The permissions that the associated user will have on the repository. Valid values are |
See also: GitHub Developer Guide documentation.
Update an organization repository ruleset
Update a ruleset for an organization.
octokit.rest.repos.updateOrgRuleset({
org,
ruleset_id,
bypass_actors[].actor_type,
bypass_actors[].bypass_mode,
rules[].type,
rules[].parameters.update_allows_fetch_and_merge,
rules[].parameters.required_deployment_environments,
rules[].parameters.dismiss_stale_reviews_on_push,
rules[].parameters.require_code_owner_review,
rules[].parameters.require_last_push_approval,
rules[].parameters.required_approving_review_count,
rules[].parameters.required_review_thread_resolution,
rules[].parameters.required_status_checks,
rules[].parameters.required_status_checks[].context,
rules[].parameters.strict_required_status_checks_policy,
rules[].parameters.operator,
rules[].parameters.pattern,
rules[].parameters.restricted_file_paths,
rules[].parameters.max_file_path_length,
rules[].parameters.restricted_file_extensions,
rules[].parameters.max_file_size,
rules[].parameters.workflows,
rules[].parameters.workflows[].path,
rules[].parameters.workflows[].repository_id
})
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
ruleset_id | yes |
The ID of the ruleset. |
name | no |
The name of the ruleset. |
target | no |
The target of the ruleset Note: The |
enforcement | no |
The enforcement level of the ruleset. |
bypass_actors | no |
The actors that can bypass the rules in this ruleset |
bypass_actors[].actor_id | no |
The ID of the actor that can bypass a ruleset. If |
bypass_actors[].actor_type | yes |
The type of actor that can bypass a ruleset. |
bypass_actors[].bypass_mode | yes |
When the specified actor can bypass the ruleset. |
conditions | no |
Conditions for an organization ruleset. The conditions object should contain both |
rules | no |
An array of rules within the ruleset. |
rules[].type | yes | |
rules[].parameters | no | |
rules[].parameters.update_allows_fetch_and_merge | yes |
Branch can pull changes from its upstream repository |
rules[].parameters.required_deployment_environments | yes |
The environments that must be successfully deployed to before branches can be merged. |
rules[].parameters.dismiss_stale_reviews_on_push | yes |
New, reviewable commits pushed will dismiss previous pull request review approvals. |
rules[].parameters.require_code_owner_review | yes |
Require an approving review in pull requests that modify files that have a designated code owner. |
rules[].parameters.require_last_push_approval | yes |
Whether the most recent reviewable push must be approved by someone other than the person who pushed it. |
rules[].parameters.required_approving_review_count | yes |
The number of approving reviews that are required before a pull request can be merged. |
rules[].parameters.required_review_thread_resolution | yes |
All conversations on code must be resolved before a pull request can be merged. |
rules[].parameters.required_status_checks | yes |
Status checks that are required. |
rules[].parameters.required_status_checks[].context | yes |
The status check context name that must be present on the commit. |
rules[].parameters.required_status_checks[].integration_id | no |
The optional integration ID that this status check must originate from. |
rules[].parameters.strict_required_status_checks_policy | yes |
Whether pull requests targeting a matching branch must be tested with the latest code. This setting will not take effect unless at least one status check is enabled. |
rules[].parameters.name | no |
How this rule will appear to users. |
rules[].parameters.negate | no |
If true, the rule will fail if the pattern matches. |
rules[].parameters.operator | yes |
The operator to use for matching. |
rules[].parameters.pattern | yes |
The pattern to match with. |
rules[].parameters.restricted_file_paths | yes |
The file paths that are restricted from being pushed to the commit graph. |
rules[].parameters.max_file_path_length | yes |
The maximum amount of characters allowed in file paths |
rules[].parameters.restricted_file_extensions | yes |
The file extensions that are restricted from being pushed to the commit graph. |
rules[].parameters.max_file_size | yes |
The maximum file size allowed in megabytes. This limit does not apply to Git Large File Storage (Git LFS). |
rules[].parameters.workflows | yes |
Workflows that must pass for this rule to pass. |
rules[].parameters.workflows[].path | yes |
The path to the workflow file |
rules[].parameters.workflows[].ref | no |
The ref (branch or tag) of the workflow file to use |
rules[].parameters.workflows[].repository_id | yes |
The ID of the repository where the workflow is defined |
rules[].parameters.workflows[].sha | no |
The commit SHA of the workflow file to use |
See also: GitHub Developer Guide documentation.
Update pull request review protection
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.
Updating pull request review enforcement requires admin or owner permissions to the repository and branch protection to be enabled.
Note: Passing new arrays of users
and teams
replaces their previous values.
octokit.rest.repos.updatePullRequestReviewProtection({
owner,
repo,
branch,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
branch | yes |
The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API. |
dismissal_restrictions | no |
Specify which users, teams, and apps can dismiss pull request reviews. Pass an empty |
dismissal_restrictions.users | no |
The list of user |
dismissal_restrictions.teams | no |
The list of team |
dismissal_restrictions.apps | no |
The list of app |
dismiss_stale_reviews | no |
Set to |
require_code_owner_reviews | no |
Blocks merging pull requests until code owners have reviewed. |
required_approving_review_count | no |
Specifies the number of reviewers required to approve pull requests. Use a number between 1 and 6 or 0 to not require reviewers. |
require_last_push_approval | no |
Whether the most recent push must be approved by someone other than the person who pushed it. Default: |
bypass_pull_request_allowances | no |
Allow specific users, teams, or apps to bypass pull request requirements. |
bypass_pull_request_allowances.users | no |
The list of user |
bypass_pull_request_allowances.teams | no |
The list of team |
bypass_pull_request_allowances.apps | no |
The list of app |
See also: GitHub Developer Guide documentation.
Update a release
Users with push access to the repository can edit a release.
octokit.rest.repos.updateRelease({
owner,
repo,
release_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
release_id | yes |
The unique identifier of the release. |
tag_name | no |
The name of the tag. |
target_commitish | no |
Specifies the commitish value that determines where the Git tag is created from. Can be any branch or commit SHA. Unused if the Git tag already exists. Default: the repository's default branch. |
name | no |
The name of the release. |
body | no |
Text describing the contents of the tag. |
draft | no |
|
prerelease | no |
|
make_latest | no |
Specifies whether this release should be set as the latest release for the repository. Drafts and prereleases cannot be set as latest. Defaults to |
discussion_category_name | no |
If specified, a discussion of the specified category is created and linked to the release. The value must be a category that already exists in the repository. If there is already a discussion linked to the release, this parameter is ignored. For more information, see "Managing categories for discussions in your repository." |
See also: GitHub Developer Guide documentation.
Update a release asset
Users with push access to the repository can edit a release asset.
octokit.rest.repos.updateReleaseAsset({
owner,
repo,
asset_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
asset_id | yes |
The unique identifier of the asset. |
name | no |
The file name of the asset. |
label | no |
An alternate short description of the asset. Used in place of the filename. |
state | no |
See also: GitHub Developer Guide documentation.
Update a repository ruleset
Update a ruleset for a repository.
octokit.rest.repos.updateRepoRuleset({
owner,
repo,
ruleset_id,
bypass_actors[].actor_type,
bypass_actors[].bypass_mode,
rules[].type,
rules[].parameters.update_allows_fetch_and_merge,
rules[].parameters.required_deployment_environments,
rules[].parameters.dismiss_stale_reviews_on_push,
rules[].parameters.require_code_owner_review,
rules[].parameters.require_last_push_approval,
rules[].parameters.required_approving_review_count,
rules[].parameters.required_review_thread_resolution,
rules[].parameters.required_status_checks,
rules[].parameters.required_status_checks[].context,
rules[].parameters.strict_required_status_checks_policy,
rules[].parameters.operator,
rules[].parameters.pattern,
rules[].parameters.restricted_file_paths,
rules[].parameters.max_file_path_length,
rules[].parameters.restricted_file_extensions,
rules[].parameters.max_file_size,
rules[].parameters.workflows,
rules[].parameters.workflows[].path,
rules[].parameters.workflows[].repository_id
})
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
ruleset_id | yes |
The ID of the ruleset. |
name | no |
The name of the ruleset. |
target | no |
The target of the ruleset Note: The |
enforcement | no |
The enforcement level of the ruleset. |
bypass_actors | no |
The actors that can bypass the rules in this ruleset |
bypass_actors[].actor_id | no |
The ID of the actor that can bypass a ruleset. If |
bypass_actors[].actor_type | yes |
The type of actor that can bypass a ruleset. |
bypass_actors[].bypass_mode | yes |
When the specified actor can bypass the ruleset. |
conditions | no |
Parameters for a repository ruleset ref name condition |
conditions.ref_name | no | |
conditions.ref_name.include | no |
Array of ref names or patterns to include. One of these patterns must match for the condition to pass. Also accepts |
conditions.ref_name.exclude | no |
Array of ref names or patterns to exclude. The condition will not pass if any of these patterns match. |
rules | no |
An array of rules within the ruleset. |
rules[].type | yes | |
rules[].parameters | no | |
rules[].parameters.update_allows_fetch_and_merge | yes |
Branch can pull changes from its upstream repository |
rules[].parameters.required_deployment_environments | yes |
The environments that must be successfully deployed to before branches can be merged. |
rules[].parameters.dismiss_stale_reviews_on_push | yes |
New, reviewable commits pushed will dismiss previous pull request review approvals. |
rules[].parameters.require_code_owner_review | yes |
Require an approving review in pull requests that modify files that have a designated code owner. |
rules[].parameters.require_last_push_approval | yes |
Whether the most recent reviewable push must be approved by someone other than the person who pushed it. |
rules[].parameters.required_approving_review_count | yes |
The number of approving reviews that are required before a pull request can be merged. |
rules[].parameters.required_review_thread_resolution | yes |
All conversations on code must be resolved before a pull request can be merged. |
rules[].parameters.required_status_checks | yes |
Status checks that are required. |
rules[].parameters.required_status_checks[].context | yes |
The status check context name that must be present on the commit. |
rules[].parameters.required_status_checks[].integration_id | no |
The optional integration ID that this status check must originate from. |
rules[].parameters.strict_required_status_checks_policy | yes |
Whether pull requests targeting a matching branch must be tested with the latest code. This setting will not take effect unless at least one status check is enabled. |
rules[].parameters.name | no |
How this rule will appear to users. |
rules[].parameters.negate | no |
If true, the rule will fail if the pattern matches. |
rules[].parameters.operator | yes |
The operator to use for matching. |
rules[].parameters.pattern | yes |
The pattern to match with. |
rules[].parameters.restricted_file_paths | yes |
The file paths that are restricted from being pushed to the commit graph. |
rules[].parameters.max_file_path_length | yes |
The maximum amount of characters allowed in file paths |
rules[].parameters.restricted_file_extensions | yes |
The file extensions that are restricted from being pushed to the commit graph. |
rules[].parameters.max_file_size | yes |
The maximum file size allowed in megabytes. This limit does not apply to Git Large File Storage (Git LFS). |
rules[].parameters.workflows | yes |
Workflows that must pass for this rule to pass. |
rules[].parameters.workflows[].path | yes |
The path to the workflow file |
rules[].parameters.workflows[].ref | no |
The ref (branch or tag) of the workflow file to use |
rules[].parameters.workflows[].repository_id | yes |
The ID of the repository where the workflow is defined |
rules[].parameters.workflows[].sha | no |
The commit SHA of the workflow file to use |
See also: GitHub Developer Guide documentation.
Update status check protection
Deprecated: This method has been renamed to repos.updateStatusCheckProtection
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.
Updating required status checks requires admin or owner permissions to the repository and branch protection to be enabled.
octokit.rest.repos.updateStatusCheckPotection({
owner,
repo,
branch,
checks[].context
})
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
branch | yes |
The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API. |
strict | no |
Require branches to be up to date before merging. |
contexts | no |
Deprecated: The list of status checks to require in order to merge into this branch. If any of these checks have recently been set by a particular GitHub App, they will be required to come from that app in future for the branch to merge. Use |
checks | no |
The list of status checks to require in order to merge into this branch. |
checks[].context | yes |
The name of the required check |
checks[].app_id | no |
The ID of the GitHub App that must provide this check. Omit this field to automatically select the GitHub App that has recently provided this check, or any app if it was not set by a GitHub App. Pass -1 to explicitly allow any app to set the status. |
See also: GitHub Developer Guide documentation.
Update status check protection
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.
Updating required status checks requires admin or owner permissions to the repository and branch protection to be enabled.
octokit.rest.repos.updateStatusCheckProtection({
owner,
repo,
branch,
checks[].context
})
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
branch | yes |
The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API. |
strict | no |
Require branches to be up to date before merging. |
contexts | no |
Deprecated: The list of status checks to require in order to merge into this branch. If any of these checks have recently been set by a particular GitHub App, they will be required to come from that app in future for the branch to merge. Use |
checks | no |
The list of status checks to require in order to merge into this branch. |
checks[].context | yes |
The name of the required check |
checks[].app_id | no |
The ID of the GitHub App that must provide this check. Omit this field to automatically select the GitHub App that has recently provided this check, or any app if it was not set by a GitHub App. Pass -1 to explicitly allow any app to set the status. |
See also: GitHub Developer Guide documentation.
Update a repository webhook
Updates a webhook configured in a repository. If you previously had a secret
set, you must provide the same secret
or set a new secret
or the secret will be removed. If you are only updating individual webhook config
properties, use "Update a webhook configuration for a repository."
octokit.rest.repos.updateWebhook({
owner,
repo,
hook_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
hook_id | yes |
The unique identifier of the hook. You can find this value in the |
config | no |
Configuration object of the webhook |
config.url | no |
The URL to which the payloads will be delivered. |
config.content_type | no |
The media type used to serialize the payloads. Supported values include |
config.secret | no |
If provided, the |
config.insecure_ssl | no | |
events | no |
Determines what events the hook is triggered for. This replaces the entire array of events. |
add_events | no |
Determines a list of events to be added to the list of events that the Hook triggers for. |
remove_events | no |
Determines a list of events to be removed from the list of events that the Hook triggers for. |
active | no |
Determines if notifications are sent when the webhook is triggered. Set to |
See also: GitHub Developer Guide documentation.
Update a webhook configuration for a repository
Updates the webhook configuration for a repository. To update more information about the webhook, including the active
state and events
, use "Update a repository webhook."
OAuth app tokens and personal access tokens (classic) need the write:repo_hook
or repo
scope to use this endpoint.
octokit.rest.repos.updateWebhookConfigForRepo({
owner,
repo,
hook_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
hook_id | yes |
The unique identifier of the hook. You can find this value in the |
url | no |
The URL to which the payloads will be delivered. |
content_type | no |
The media type used to serialize the payloads. Supported values include |
secret | no |
If provided, the |
insecure_ssl | no |
See also: GitHub Developer Guide documentation.
Upload a release asset
This endpoint makes use of a Hypermedia relation to determine which URL to access. The endpoint you call to upload release assets is specific to your release. Use the upload_url
returned in
the response of the Create a release endpoint to upload a release asset.
You need to use an HTTP client which supports SNI to make calls to this endpoint.
Most libraries will set the required Content-Length
header automatically. Use the required Content-Type
header to provide the media type of the asset. For a list of media types, see Media Types. For example:
application/zip
GitHub expects the asset data in its raw binary form, rather than JSON. You will send the raw binary content of the asset as the request body. Everything else about the endpoint is the same as the rest of the API. For example, you'll still need to pass your authentication to be able to upload an asset.
When an upstream failure occurs, you will receive a 502 Bad Gateway
status. This may leave an empty asset with a state of starter
. It can be safely deleted.
Notes:
- GitHub renames asset filenames that have special characters, non-alphanumeric characters, and leading or trailing periods. The "List release assets" endpoint lists the renamed filenames. For more information and help, contact GitHub Support.
- To find the
release_id
query theGET /repos/{owner}/{repo}/releases/latest
endpoint. - If you upload an asset with the same filename as another uploaded asset, you'll receive an error and must delete the old file before you can re-upload the new asset.
octokit.rest.repos.uploadReleaseAsset({
owner,
repo,
release_id,
name,
data,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
release_id | yes |
The unique identifier of the release. |
name | yes | |
label | no | |
data | yes |
The raw file data |
origin | no |
The URL origin (protocol + host name + port) is included in |
See also: GitHub Developer Guide documentation.
Search
Search code
Searches for query terms inside of a file. This method returns up to 100 results per page.
When searching for code, you can get text match metadata for the file content and file path fields when you pass the text-match
media type. For more details about how to receive highlighted search results, see Text match metadata.
For example, if you want to find the definition of the addClass
function inside jQuery repository, your query would look something like this:
q=addClass+in:file+language:js+repo:jquery/jquery
This query searches for the keyword addClass
within a file's contents. The query limits the search to files where the language is JavaScript in the jquery/jquery
repository.
Considerations for code search:
Due to the complexity of searching code, there are a few restrictions on how searches are performed:
- Only the default branch is considered. In most cases, this will be the
master
branch. - Only files smaller than 384 KB are searchable.
- You must always include at least one search term when searching source code. For example, searching for
language:go
is not valid, while [`amazing
language:go`](https://github.com/search?utf8=%E2%9C%93&q=amazing+language%3Ago&type=Code) is.
This endpoint requires you to authenticate and limits you to 10 requests per minute.
octokit.rest.search.code({
q,
});
Parameters
name | required | description |
---|---|---|
q | yes |
The query contains one or more search keywords and qualifiers. Qualifiers allow you to limit your search to specific areas of GitHub. The REST API supports the same qualifiers as the web interface for GitHub. To learn more about the format of the query, see Constructing a search query. See "Searching code" for a detailed list of qualifiers. |
sort | no |
This field is deprecated. Sorts the results of your query. Can only be |
order | no |
This field is deprecated. Determines whether the first search result returned is the highest number of matches ( |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
Search commits
Find commits via various criteria on the default branch (usually main
). This method returns up to 100 results per page.
When searching for commits, you can get text match metadata for the message field when you provide the text-match
media type. For more details about how to receive highlighted search results, see Text match
metadata.
For example, if you want to find commits related to CSS in the octocat/Spoon-Knife repository. Your query would look something like this:
q=repo:octocat/Spoon-Knife+css
octokit.rest.search.commits({
q,
});
Parameters
name | required | description |
---|---|---|
q | yes |
The query contains one or more search keywords and qualifiers. Qualifiers allow you to limit your search to specific areas of GitHub. The REST API supports the same qualifiers as the web interface for GitHub. To learn more about the format of the query, see Constructing a search query. See "Searching commits" for a detailed list of qualifiers. |
sort | no |
Sorts the results of your query by |
order | no |
Determines whether the first search result returned is the highest number of matches ( |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
Search issues and pull requests
Find issues by state and keyword. This method returns up to 100 results per page.
When searching for issues, you can get text match metadata for the issue title, issue body, and issue comment body fields when you pass the text-match
media type. For more details about how to receive highlighted
search results, see Text match metadata.
For example, if you want to find the oldest unresolved Python bugs on Windows. Your query might look something like this.
q=windows+label:bug+language:python+state:open&sort=created&order=asc
This query searches for the keyword windows
, within any open issue that is labeled as bug
. The search runs across repositories whose primary language is Python. The results are sorted by creation date in ascending order, which means the oldest issues appear first in the search results.
Note: For requests made by GitHub Apps with a user access token, you can't retrieve a combination of issues and pull requests in a single query. Requests that don't include the is:issue
or is:pull-request
qualifier will receive an HTTP 422 Unprocessable Entity
response. To get results for both issues and pull requests, you must send separate queries for issues and pull requests. For more information about the is
qualifier, see "Searching only issues or pull requests."
octokit.rest.search.issuesAndPullRequests({
q,
});
Parameters
name | required | description |
---|---|---|
q | yes |
The query contains one or more search keywords and qualifiers. Qualifiers allow you to limit your search to specific areas of GitHub. The REST API supports the same qualifiers as the web interface for GitHub. To learn more about the format of the query, see Constructing a search query. See "Searching issues and pull requests" for a detailed list of qualifiers. |
sort | no |
Sorts the results of your query by the number of |
order | no |
Determines whether the first search result returned is the highest number of matches ( |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
Search labels
Find labels in a repository with names or descriptions that match search keywords. Returns up to 100 results per page.
When searching for labels, you can get text match metadata for the label name and description fields when you pass the text-match
media type. For more details about how to receive highlighted search results, see Text match metadata.
For example, if you want to find labels in the linguist
repository that match bug
, defect
, or enhancement
. Your query might look like this:
q=bug+defect+enhancement&repository_id=64778136
The labels that best match the query appear first in the search results.
octokit.rest.search.labels({
repository_id,
q,
});
Parameters
name | required | description |
---|---|---|
repository_id | yes |
The id of the repository. |
q | yes |
The search keywords. This endpoint does not accept qualifiers in the query. To learn more about the format of the query, see Constructing a search query. |
sort | no |
Sorts the results of your query by when the label was |
order | no |
Determines whether the first search result returned is the highest number of matches ( |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
Search repositories
Find repositories via various criteria. This method returns up to 100 results per page.
When searching for repositories, you can get text match metadata for the name and description fields when you pass the text-match
media type. For more details about how to receive highlighted search results, see Text match metadata.
For example, if you want to search for popular Tetris repositories written in assembly code, your query might look like this:
q=tetris+language:assembly&sort=stars&order=desc
This query searches for repositories with the word tetris
in the name, the description, or the README. The results are limited to repositories where the primary language is assembly. The results are sorted by stars in descending order, so that the most popular repositories appear first in the search results.
octokit.rest.search.repos({
q,
});
Parameters
name | required | description |
---|---|---|
q | yes |
The query contains one or more search keywords and qualifiers. Qualifiers allow you to limit your search to specific areas of GitHub. The REST API supports the same qualifiers as the web interface for GitHub. To learn more about the format of the query, see Constructing a search query. See "Searching for repositories" for a detailed list of qualifiers. |
sort | no |
Sorts the results of your query by number of |
order | no |
Determines whether the first search result returned is the highest number of matches ( |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
Search topics
Find topics via various criteria. Results are sorted by best match. This method returns up to 100 results per page. See "Searching topics" for a detailed list of qualifiers.
When searching for topics, you can get text match metadata for the topic's short_description, description, name, or display_name field when you pass the text-match
media type. For more details about how to receive highlighted search results, see Text match metadata.
For example, if you want to search for topics related to Ruby that are featured on https://github.com/topics. Your query might look like this:
q=ruby+is:featured
This query searches for topics with the keyword ruby
and limits the results to find only topics that are featured. The topics that are the best match for the query appear first in the search results.
octokit.rest.search.topics({
q,
});
Parameters
name | required | description |
---|---|---|
q | yes |
The query contains one or more search keywords and qualifiers. Qualifiers allow you to limit your search to specific areas of GitHub. The REST API supports the same qualifiers as the web interface for GitHub. To learn more about the format of the query, see Constructing a search query. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
Search users
Find users via various criteria. This method returns up to 100 results per page.
When searching for users, you can get text match metadata for the issue login, public email, and name fields when you pass the text-match
media type. For more details about highlighting search results, see Text match metadata. For more details about how to receive highlighted search results, see Text match metadata.
For example, if you're looking for a list of popular users, you might try this query:
q=tom+repos:%3E42+followers:%3E1000
This query searches for users with the name tom
. The results are restricted to users with more than 42 repositories and over 1,000 followers.
This endpoint does not accept authentication and will only include publicly visible users. As an alternative, you can use the GraphQL API. The GraphQL API requires authentication and will return private users, including Enterprise Managed Users (EMUs), that you are authorized to view. For more information, see "GraphQL Queries."
octokit.rest.search.users({
q,
});
Parameters
name | required | description |
---|---|---|
q | yes |
The query contains one or more search keywords and qualifiers. Qualifiers allow you to limit your search to specific areas of GitHub. The REST API supports the same qualifiers as the web interface for GitHub. To learn more about the format of the query, see Constructing a search query. See "Searching users" for a detailed list of qualifiers. |
sort | no |
Sorts the results of your query by number of |
order | no |
Determines whether the first search result returned is the highest number of matches ( |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
Secret-Scanning
Get a secret scanning alert
Gets a single secret scanning alert detected in an eligible repository.
The authenticated user must be an administrator for the repository or for the organization that owns the repository to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the repo
or security_events
scope to use this endpoint. If this endpoint is only used with public repositories, the token can use the public_repo
scope instead.
octokit.rest.secretScanning.getAlert({
owner,
repo,
alert_number,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
alert_number | yes |
The number that identifies an alert. You can find this at the end of the URL for a code scanning alert within GitHub, and in the |
See also: GitHub Developer Guide documentation.
List secret scanning alerts for an enterprise
Lists secret scanning alerts for eligible repositories in an enterprise, from newest to oldest.
Alerts are only returned for organizations in the enterprise for which the authenticated user is an organization owner or a security manager.
The authenticated user must be a member of the enterprise in order to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the repo
scope or security_events
scope to use this endpoint.
octokit.rest.secretScanning.listAlertsForEnterprise({
enterprise,
});
Parameters
name | required | description |
---|---|---|
enterprise | yes |
The slug version of the enterprise name. You can also substitute this value with the enterprise id. |
state | no |
Set to |
secret_type | no |
A comma-separated list of secret types to return. By default all secret types are returned. See "Secret scanning patterns" for a complete list of secret types. |
resolution | no |
A comma-separated list of resolutions. Only secret scanning alerts with one of these resolutions are listed. Valid resolutions are |
sort | no |
The property to sort the results by. |
direction | no |
The direction to sort the results by. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
before | no |
A cursor, as given in the Link header. If specified, the query only searches for results before this cursor. For more information, see "Using pagination in the REST API." |
after | no |
A cursor, as given in the Link header. If specified, the query only searches for results after this cursor. For more information, see "Using pagination in the REST API." |
validity | no |
A comma-separated list of validities that, when present, will return alerts that match the validities in this list. Valid options are |
See also: GitHub Developer Guide documentation.
List secret scanning alerts for an organization
Lists secret scanning alerts for eligible repositories in an organization, from newest to oldest.
The authenticated user must be an administrator or security manager for the organization to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the repo
or security_events
scope to use this endpoint. If this endpoint is only used with public repositories, the token can use the public_repo
scope instead.
octokit.rest.secretScanning.listAlertsForOrg({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
state | no |
Set to |
secret_type | no |
A comma-separated list of secret types to return. By default all secret types are returned. See "Secret scanning patterns" for a complete list of secret types. |
resolution | no |
A comma-separated list of resolutions. Only secret scanning alerts with one of these resolutions are listed. Valid resolutions are |
sort | no |
The property to sort the results by. |
direction | no |
The direction to sort the results by. |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
before | no |
A cursor, as given in the Link header. If specified, the query only searches for events before this cursor. To receive an initial cursor on your first request, include an empty "before" query string. |
after | no |
A cursor, as given in the Link header. If specified, the query only searches for events after this cursor. To receive an initial cursor on your first request, include an empty "after" query string. |
validity | no |
A comma-separated list of validities that, when present, will return alerts that match the validities in this list. Valid options are |
See also: GitHub Developer Guide documentation.
List secret scanning alerts for a repository
Lists secret scanning alerts for an eligible repository, from newest to oldest.
The authenticated user must be an administrator for the repository or for the organization that owns the repository to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the repo
or security_events
scope to use this endpoint. If this endpoint is only used with public repositories, the token can use the public_repo
scope instead.
octokit.rest.secretScanning.listAlertsForRepo({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
state | no |
Set to |
secret_type | no |
A comma-separated list of secret types to return. By default all secret types are returned. See "Secret scanning patterns" for a complete list of secret types. |
resolution | no |
A comma-separated list of resolutions. Only secret scanning alerts with one of these resolutions are listed. Valid resolutions are |
sort | no |
The property to sort the results by. |
direction | no |
The direction to sort the results by. |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
before | no |
A cursor, as given in the Link header. If specified, the query only searches for events before this cursor. To receive an initial cursor on your first request, include an empty "before" query string. |
after | no |
A cursor, as given in the Link header. If specified, the query only searches for events after this cursor. To receive an initial cursor on your first request, include an empty "after" query string. |
validity | no |
A comma-separated list of validities that, when present, will return alerts that match the validities in this list. Valid options are |
See also: GitHub Developer Guide documentation.
List locations for a secret scanning alert
Lists all locations for a given secret scanning alert for an eligible repository.
The authenticated user must be an administrator for the repository or for the organization that owns the repository to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the repo
or security_events
scope to use this endpoint. If this endpoint is only used with public repositories, the token can use the public_repo
scope instead.
octokit.rest.secretScanning.listLocationsForAlert({
owner,
repo,
alert_number,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
alert_number | yes |
The number that identifies an alert. You can find this at the end of the URL for a code scanning alert within GitHub, and in the |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
Update a secret scanning alert
Updates the status of a secret scanning alert in an eligible repository.
The authenticated user must be an administrator for the repository or for the organization that owns the repository to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the repo
or security_events
scope to use this endpoint. If this endpoint is only used with public repositories, the token can use the public_repo
scope instead.
octokit.rest.secretScanning.updateAlert({
owner,
repo,
alert_number,
state,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
alert_number | yes |
The number that identifies an alert. You can find this at the end of the URL for a code scanning alert within GitHub, and in the |
state | yes |
Sets the state of the secret scanning alert. You must provide |
resolution | no |
Required when the |
resolution_comment | no |
An optional comment when closing an alert. Cannot be updated or deleted. Must be |
See also: GitHub Developer Guide documentation.
Security-Advisories
Create a temporary private fork
Create a temporary private fork to collaborate on fixing a security vulnerability in your repository.
Note: Forking a repository happens asynchronously. You may have to wait up to 5 minutes before you can access the fork.
octokit.rest.securityAdvisories.createFork({
owner,
repo,
ghsa_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
ghsa_id | yes |
The GHSA (GitHub Security Advisory) identifier of the advisory. |
See also: GitHub Developer Guide documentation.
Privately report a security vulnerability
Report a security vulnerability to the maintainers of the repository. See "Privately reporting a security vulnerability" for more information about private vulnerability reporting.
octokit.rest.securityAdvisories.createPrivateVulnerabilityReport({
owner,
repo,
summary,
description,
vulnerabilities[].package,
vulnerabilities[].package.ecosystem
})
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
summary | yes |
A short summary of the advisory. |
description | yes |
A detailed description of what the advisory impacts. |
vulnerabilities | no |
An array of products affected by the vulnerability detailed in a repository security advisory. |
vulnerabilities[].package | yes |
The name of the package affected by the vulnerability. |
vulnerabilities[].package.ecosystem | yes |
The package's language or package management ecosystem. |
vulnerabilities[].package.name | no |
The unique package name within its ecosystem. |
vulnerabilities[].vulnerable_version_range | no |
The range of the package versions affected by the vulnerability. |
vulnerabilities[].patched_versions | no |
The package version(s) that resolve the vulnerability. |
vulnerabilities[].vulnerable_functions | no |
The functions in the package that are affected. |
cwe_ids | no |
A list of Common Weakness Enumeration (CWE) IDs. |
severity | no |
The severity of the advisory. You must choose between setting this field or |
cvss_vector_string | no |
The CVSS vector that calculates the severity of the advisory. You must choose between setting this field or |
start_private_fork | no |
Whether to create a temporary private fork of the repository to collaborate on a fix. |
See also: GitHub Developer Guide documentation.
Create a repository security advisory
Creates a new repository security advisory.
In order to create a draft repository security advisory, the authenticated user must be a security manager or administrator of that repository.
OAuth app tokens and personal access tokens (classic) need the repo
or repository_advisories:write
scope to use this endpoint.
octokit.rest.securityAdvisories.createRepositoryAdvisory({
owner,
repo,
summary,
description,
vulnerabilities,
vulnerabilities[].package,
vulnerabilities[].package.ecosystem,
credits[].login,
credits[].type
})
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
summary | yes |
A short summary of the advisory. |
description | yes |
A detailed description of what the advisory impacts. |
cve_id | no |
The Common Vulnerabilities and Exposures (CVE) ID. |
vulnerabilities | yes |
A product affected by the vulnerability detailed in a repository security advisory. |
vulnerabilities[].package | yes |
The name of the package affected by the vulnerability. |
vulnerabilities[].package.ecosystem | yes |
The package's language or package management ecosystem. |
vulnerabilities[].package.name | no |
The unique package name within its ecosystem. |
vulnerabilities[].vulnerable_version_range | no |
The range of the package versions affected by the vulnerability. |
vulnerabilities[].patched_versions | no |
The package version(s) that resolve the vulnerability. |
vulnerabilities[].vulnerable_functions | no |
The functions in the package that are affected. |
cwe_ids | no |
A list of Common Weakness Enumeration (CWE) IDs. |
credits | no |
A list of users receiving credit for their participation in the security advisory. |
credits[].login | yes |
The username of the user credited. |
credits[].type | yes |
The type of credit the user is receiving. |
severity | no |
The severity of the advisory. You must choose between setting this field or |
cvss_vector_string | no |
The CVSS vector that calculates the severity of the advisory. You must choose between setting this field or |
start_private_fork | no |
Whether to create a temporary private fork of the repository to collaborate on a fix. |
See also: GitHub Developer Guide documentation.
Request a CVE for a repository security advisory
If you want a CVE identification number for the security vulnerability in your project, and don't already have one, you can request a CVE identification number from GitHub. For more information see "Requesting a CVE identification number."
You may request a CVE for public repositories, but cannot do so for private repositories.
In order to request a CVE for a repository security advisory, the authenticated user must be a security manager or administrator of that repository.
OAuth app tokens and personal access tokens (classic) need the repo
or repository_advisories:write
scope to use this endpoint.
octokit.rest.securityAdvisories.createRepositoryAdvisoryCveRequest({
owner,
repo,
ghsa_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
ghsa_id | yes |
The GHSA (GitHub Security Advisory) identifier of the advisory. |
See also: GitHub Developer Guide documentation.
Get a global security advisory
Gets a global security advisory using its GitHub Security Advisory (GHSA) identifier.
octokit.rest.securityAdvisories.getGlobalAdvisory({
ghsa_id,
});
Parameters
name | required | description |
---|---|---|
ghsa_id | yes |
The GHSA (GitHub Security Advisory) identifier of the advisory. |
See also: GitHub Developer Guide documentation.
Get a repository security advisory
Get a repository security advisory using its GitHub Security Advisory (GHSA) identifier.
Anyone can access any published security advisory on a public repository.
The authenticated user can access an unpublished security advisory from a repository if they are a security manager or administrator of that repository, or if they are a collaborator on the security advisory.
OAuth app tokens and personal access tokens (classic) need the repo
or repository_advisories:read
scope to to get a published security advisory in a private repository, or any unpublished security advisory that the authenticated user has access to.
octokit.rest.securityAdvisories.getRepositoryAdvisory({
owner,
repo,
ghsa_id,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
ghsa_id | yes |
The GHSA (GitHub Security Advisory) identifier of the advisory. |
See also: GitHub Developer Guide documentation.
List global security advisories
Lists all global security advisories that match the specified parameters. If no other parameters are defined, the request will return only GitHub-reviewed advisories that are not malware.
By default, all responses will exclude advisories for malware, because malware are not standard vulnerabilities. To list advisories for malware, you must include the type
parameter in your request, with the value malware
. For more information about the different types of security advisories, see "About the GitHub Advisory database."
octokit.rest.securityAdvisories.listGlobalAdvisories();
Parameters
name | required | description |
---|---|---|
ghsa_id | no |
If specified, only advisories with this GHSA (GitHub Security Advisory) identifier will be returned. |
type | no |
If specified, only advisories of this type will be returned. By default, a request with no other parameters defined will only return reviewed advisories that are not malware. |
cve_id | no |
If specified, only advisories with this CVE (Common Vulnerabilities and Exposures) identifier will be returned. |
ecosystem | no |
If specified, only advisories for these ecosystems will be returned. |
severity | no |
If specified, only advisories with these severities will be returned. |
cwes | no |
If specified, only advisories with these Common Weakness Enumerations (CWEs) will be returned. Example: |
is_withdrawn | no |
Whether to only return advisories that have been withdrawn. |
affects | no |
If specified, only return advisories that affect any of Example: |
published | no |
If specified, only return advisories that were published on a date or date range. For more information on the syntax of the date range, see "Understanding the search syntax." |
updated | no |
If specified, only return advisories that were updated on a date or date range. For more information on the syntax of the date range, see "Understanding the search syntax." |
modified | no |
If specified, only show advisories that were updated or published on a date or date range. For more information on the syntax of the date range, see "Understanding the search syntax." |
before | no |
A cursor, as given in the Link header. If specified, the query only searches for results before this cursor. For more information, see "Using pagination in the REST API." |
after | no |
A cursor, as given in the Link header. If specified, the query only searches for results after this cursor. For more information, see "Using pagination in the REST API." |
direction | no |
The direction to sort the results by. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
sort | no |
The property to sort the results by. |
See also: GitHub Developer Guide documentation.
List repository security advisories for an organization
Lists repository security advisories for an organization.
The authenticated user must be an owner or security manager for the organization to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the repo
or repository_advisories:write
scope to use this endpoint.
octokit.rest.securityAdvisories.listOrgRepositoryAdvisories({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
direction | no |
The direction to sort the results by. |
sort | no |
The property to sort the results by. |
before | no |
A cursor, as given in the Link header. If specified, the query only searches for results before this cursor. For more information, see "Using pagination in the REST API." |
after | no |
A cursor, as given in the Link header. If specified, the query only searches for results after this cursor. For more information, see "Using pagination in the REST API." |
per_page | no |
The number of advisories to return per page. For more information, see "Using pagination in the REST API." |
state | no |
Filter by the state of the repository advisories. Only advisories of this state will be returned. |
See also: GitHub Developer Guide documentation.
List repository security advisories
Lists security advisories in a repository.
The authenticated user can access unpublished security advisories from a repository if they are a security manager or administrator of that repository, or if they are a collaborator on any security advisory.
OAuth app tokens and personal access tokens (classic) need the repo
or repository_advisories:read
scope to to get a published security advisory in a private repository, or any unpublished security advisory that the authenticated user has access to.
octokit.rest.securityAdvisories.listRepositoryAdvisories({
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
direction | no |
The direction to sort the results by. |
sort | no |
The property to sort the results by. |
before | no |
A cursor, as given in the Link header. If specified, the query only searches for results before this cursor. For more information, see "Using pagination in the REST API." |
after | no |
A cursor, as given in the Link header. If specified, the query only searches for results after this cursor. For more information, see "Using pagination in the REST API." |
per_page | no |
The number of advisories to return per page. For more information, see "Using pagination in the REST API." |
state | no |
Filter by state of the repository advisories. Only advisories of this state will be returned. |
See also: GitHub Developer Guide documentation.
Update a repository security advisory
Update a repository security advisory using its GitHub Security Advisory (GHSA) identifier.
In order to update any security advisory, the authenticated user must be a security manager or administrator of that repository, or a collaborator on the repository security advisory.
OAuth app tokens and personal access tokens (classic) need the repo
or repository_advisories:write
scope to use this endpoint.
octokit.rest.securityAdvisories.updateRepositoryAdvisory({
owner,
repo,
ghsa_id,
vulnerabilities[].package,
vulnerabilities[].package.ecosystem,
credits[].login,
credits[].type
})
Parameters
name | required | description |
---|---|---|
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
ghsa_id | yes |
The GHSA (GitHub Security Advisory) identifier of the advisory. |
summary | no |
A short summary of the advisory. |
description | no |
A detailed description of what the advisory impacts. |
cve_id | no |
The Common Vulnerabilities and Exposures (CVE) ID. |
vulnerabilities | no |
A product affected by the vulnerability detailed in a repository security advisory. |
vulnerabilities[].package | yes |
The name of the package affected by the vulnerability. |
vulnerabilities[].package.ecosystem | yes |
The package's language or package management ecosystem. |
vulnerabilities[].package.name | no |
The unique package name within its ecosystem. |
vulnerabilities[].vulnerable_version_range | no |
The range of the package versions affected by the vulnerability. |
vulnerabilities[].patched_versions | no |
The package version(s) that resolve the vulnerability. |
vulnerabilities[].vulnerable_functions | no |
The functions in the package that are affected. |
cwe_ids | no |
A list of Common Weakness Enumeration (CWE) IDs. |
credits | no |
A list of users receiving credit for their participation in the security advisory. |
credits[].login | yes |
The username of the user credited. |
credits[].type | yes |
The type of credit the user is receiving. |
severity | no |
The severity of the advisory. You must choose between setting this field or |
cvss_vector_string | no |
The CVSS vector that calculates the severity of the advisory. You must choose between setting this field or |
state | no |
The state of the advisory. |
collaborating_users | no |
A list of usernames who have been granted write access to the advisory. |
collaborating_teams | no |
A list of team slugs which have been granted write access to the advisory. |
See also: GitHub Developer Guide documentation.
Teams
Add or update team membership for a user
Adds an organization member to a team. An authenticated organization owner or team maintainer can add organization members to a team.
Team synchronization is available for organizations using GitHub Enterprise Cloud. For more information, see GitHub's products in the GitHub Help documentation.
Note: When you have team synchronization set up for a team with your organization's identity provider (IdP), you will see an error if you attempt to use the API for making changes to the team's membership. If you have access to manage group membership in your IdP, you can manage GitHub team membership through your identity provider, which automatically adds and removes team members in an organization. For more information, see "Synchronizing teams between your identity provider and GitHub."
An organization owner can add someone who is not part of the team's organization to a team. When an organization owner adds someone to a team who is not an organization member, this endpoint will send an invitation to the person via email. This newly-created membership will be in the "pending" state until the person accepts the invitation, at which point the membership will transition to the "active" state and the user will be added as a member of the team.
If the user is already a member of the team, this endpoint will update the role of the team member's role. To update the membership of a team member, the authenticated user must be an organization owner or a team maintainer.
Note: You can also specify a team by org_id
and team_id
using the route PUT /organizations/{org_id}/team/{team_id}/memberships/{username}
.
octokit.rest.teams.addOrUpdateMembershipForUserInOrg({
org,
team_slug,
username,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
team_slug | yes |
The slug of the team name. |
username | yes |
The handle for the GitHub user account. |
role | no |
The role that this user should have in the team. |
See also: GitHub Developer Guide documentation.
Add or update team project permissions
Adds an organization project to a team. To add a project to a team or update the team's permission on a project, the authenticated user must have admin
permissions for the project. The project and team must be part of the same organization.
Note: You can also specify a team by org_id
and team_id
using the route PUT /organizations/{org_id}/team/{team_id}/projects/{project_id}
.
octokit.rest.teams.addOrUpdateProjectPermissionsInOrg({
org,
team_slug,
project_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
team_slug | yes |
The slug of the team name. |
project_id | yes |
The unique identifier of the project. |
permission | no |
The permission to grant to the team for this project. Default: the team's |
See also: GitHub Developer Guide documentation.
Add or update team repository permissions
To add a repository to a team or update the team's permission on a repository, the authenticated user must have admin access to the repository, and must be able to see the team. The repository must be owned by the organization, or a direct fork of a repository owned by the organization. You will get a 422 Unprocessable Entity
status if you attempt to add a repository to a team that is not owned by the organization. Note that, if you choose not to pass any parameters, you'll need to set Content-Length
to zero when calling out to this endpoint. For more information, see "HTTP method."
Note: You can also specify a team by org_id
and team_id
using the route PUT /organizations/{org_id}/team/{team_id}/repos/{owner}/{repo}
.
For more information about the permission levels, see "Repository permission levels for an organization".
octokit.rest.teams.addOrUpdateRepoPermissionsInOrg({
org,
team_slug,
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
team_slug | yes |
The slug of the team name. |
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
permission | no |
The permission to grant the team on this repository. We accept the following permissions to be set: |
See also: GitHub Developer Guide documentation.
Check team permissions for a project
Checks whether a team has read
, write
, or admin
permissions for an organization project. The response includes projects inherited from a parent team.
Note: You can also specify a team by org_id
and team_id
using the route GET /organizations/{org_id}/team/{team_id}/projects/{project_id}
.
octokit.rest.teams.checkPermissionsForProjectInOrg({
org,
team_slug,
project_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
team_slug | yes |
The slug of the team name. |
project_id | yes |
The unique identifier of the project. |
See also: GitHub Developer Guide documentation.
Check team permissions for a repository
Checks whether a team has admin
, push
, maintain
, triage
, or pull
permission for a repository. Repositories inherited through a parent team will also be checked.
You can also get information about the specified repository, including what permissions the team grants on it, by passing the following custom media type via the application/vnd.github.v3.repository+json
accept header.
If a team doesn't have permission for the repository, you will receive a 404 Not Found
response status.
If the repository is private, you must have at least read
permission for that repository, and your token must have the repo
or admin:org
scope. Otherwise, you will receive a 404 Not Found
response status.
Note: You can also specify a team by org_id
and team_id
using the route GET /organizations/{org_id}/team/{team_id}/repos/{owner}/{repo}
.
octokit.rest.teams.checkPermissionsForRepoInOrg({
org,
team_slug,
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
team_slug | yes |
The slug of the team name. |
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Create a team
To create a team, the authenticated user must be a member or owner of {org}
. By default, organization members can create teams. Organization owners can limit team creation to organization owners. For more information, see "Setting team creation permissions."
When you create a new team, you automatically become a team maintainer without explicitly adding yourself to the optional array of maintainers
. For more information, see "About teams".
octokit.rest.teams.create({
org,
name,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
name | yes |
The name of the team. |
description | no |
The description of the team. |
maintainers | no |
List GitHub IDs for organization members who will become team maintainers. |
repo_names | no |
The full name (e.g., "organization-name/repository-name") of repositories to add the team to. |
privacy | no |
The level of privacy this team should have. The options are:
|
notification_setting | no |
The notification setting the team has chosen. The options are:
|
permission | no |
Deprecated. The permission that new repositories will be added to the team with when none is specified. |
parent_team_id | no |
The ID of a team to set as the parent team. |
See also: GitHub Developer Guide documentation.
Create a discussion comment
Creates a new comment on a team discussion.
This endpoint triggers notifications. Creating content too quickly using this endpoint may result in secondary rate limiting. For more information, see "Rate limits for the API" and "Best practices for using the REST API."
Note: You can also specify a team by org_id
and team_id
using the route POST /organizations/{org_id}/team/{team_id}/discussions/{discussion_number}/comments
.
OAuth app tokens and personal access tokens (classic) need the write:discussion
scope to use this endpoint.
octokit.rest.teams.createDiscussionCommentInOrg({
org,
team_slug,
discussion_number,
body,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
team_slug | yes |
The slug of the team name. |
discussion_number | yes |
The number that identifies the discussion. |
body | yes |
The discussion comment's body text. |
See also: GitHub Developer Guide documentation.
Create a discussion
Creates a new discussion post on a team's page.
This endpoint triggers notifications. Creating content too quickly using this endpoint may result in secondary rate limiting. For more information, see "Rate limits for the API" and "Best practices for using the REST API."
Note: You can also specify a team by org_id
and team_id
using the route POST /organizations/{org_id}/team/{team_id}/discussions
.
OAuth app tokens and personal access tokens (classic) need the write:discussion
scope to use this endpoint.
octokit.rest.teams.createDiscussionInOrg({
org,
team_slug,
title,
body,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
team_slug | yes |
The slug of the team name. |
title | yes |
The discussion post's title. |
body | yes |
The discussion post's body text. |
private | no |
Private posts are only visible to team members, organization owners, and team maintainers. Public posts are visible to all members of the organization. Set to |
See also: GitHub Developer Guide documentation.
Delete a discussion comment
Deletes a comment on a team discussion.
Note: You can also specify a team by org_id
and team_id
using the route DELETE /organizations/{org_id}/team/{team_id}/discussions/{discussion_number}/comments/{comment_number}
.
OAuth app tokens and personal access tokens (classic) need the write:discussion
scope to use this endpoint.
octokit.rest.teams.deleteDiscussionCommentInOrg({
org,
team_slug,
discussion_number,
comment_number,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
team_slug | yes |
The slug of the team name. |
discussion_number | yes |
The number that identifies the discussion. |
comment_number | yes |
The number that identifies the comment. |
See also: GitHub Developer Guide documentation.
Delete a discussion
Delete a discussion from a team's page.
Note: You can also specify a team by org_id
and team_id
using the route DELETE /organizations/{org_id}/team/{team_id}/discussions/{discussion_number}
.
OAuth app tokens and personal access tokens (classic) need the write:discussion
scope to use this endpoint.
octokit.rest.teams.deleteDiscussionInOrg({
org,
team_slug,
discussion_number,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
team_slug | yes |
The slug of the team name. |
discussion_number | yes |
The number that identifies the discussion. |
See also: GitHub Developer Guide documentation.
Delete a team
To delete a team, the authenticated user must be an organization owner or team maintainer.
If you are an organization owner, deleting a parent team will delete all of its child teams as well.
Note: You can also specify a team by org_id
and team_id
using the route DELETE /organizations/{org_id}/team/{team_id}
.
octokit.rest.teams.deleteInOrg({
org,
team_slug,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
team_slug | yes |
The slug of the team name. |
See also: GitHub Developer Guide documentation.
Get a team by name
Gets a team using the team's slug
. To create the slug
, GitHub replaces special characters in the name
string, changes all words to lowercase, and replaces spaces with a -
separator. For example, "My TEam Näme"
would become my-team-name
.
Note: You can also specify a team by org_id
and team_id
using the route GET /organizations/{org_id}/team/{team_id}
.
octokit.rest.teams.getByName({
org,
team_slug,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
team_slug | yes |
The slug of the team name. |
See also: GitHub Developer Guide documentation.
Get a discussion comment
Get a specific comment on a team discussion.
Note: You can also specify a team by org_id
and team_id
using the route GET /organizations/{org_id}/team/{team_id}/discussions/{discussion_number}/comments/{comment_number}
.
OAuth app tokens and personal access tokens (classic) need the read:discussion
scope to use this endpoint.
octokit.rest.teams.getDiscussionCommentInOrg({
org,
team_slug,
discussion_number,
comment_number,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
team_slug | yes |
The slug of the team name. |
discussion_number | yes |
The number that identifies the discussion. |
comment_number | yes |
The number that identifies the comment. |
See also: GitHub Developer Guide documentation.
Get a discussion
Get a specific discussion on a team's page.
Note: You can also specify a team by org_id
and team_id
using the route GET /organizations/{org_id}/team/{team_id}/discussions/{discussion_number}
.
OAuth app tokens and personal access tokens (classic) need the read:discussion
scope to use this endpoint.
octokit.rest.teams.getDiscussionInOrg({
org,
team_slug,
discussion_number,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
team_slug | yes |
The slug of the team name. |
discussion_number | yes |
The number that identifies the discussion. |
See also: GitHub Developer Guide documentation.
Get team membership for a user
Team members will include the members of child teams.
To get a user's membership with a team, the team must be visible to the authenticated user.
Note: You can also specify a team by org_id
and team_id
using the route GET /organizations/{org_id}/team/{team_id}/memberships/{username}
.
Note:
The response contains the state
of the membership and the member's role
.
The role
for organization owners is set to maintainer
. For more information about maintainer
roles, see Create a team.
octokit.rest.teams.getMembershipForUserInOrg({
org,
team_slug,
username,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
team_slug | yes |
The slug of the team name. |
username | yes |
The handle for the GitHub user account. |
See also: GitHub Developer Guide documentation.
List teams
Lists all teams in an organization that are visible to the authenticated user.
octokit.rest.teams.list({
org,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List child teams
Lists the child teams of the team specified by {team_slug}
.
Note: You can also specify a team by org_id
and team_id
using the route GET /organizations/{org_id}/team/{team_id}/teams
.
octokit.rest.teams.listChildInOrg({
org,
team_slug,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
team_slug | yes |
The slug of the team name. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List discussion comments
List all comments on a team discussion.
Note: You can also specify a team by org_id
and team_id
using the route GET /organizations/{org_id}/team/{team_id}/discussions/{discussion_number}/comments
.
OAuth app tokens and personal access tokens (classic) need the read:discussion
scope to use this endpoint.
octokit.rest.teams.listDiscussionCommentsInOrg({
org,
team_slug,
discussion_number,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
team_slug | yes |
The slug of the team name. |
discussion_number | yes |
The number that identifies the discussion. |
direction | no |
The direction to sort the results by. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List discussions
List all discussions on a team's page.
Note: You can also specify a team by org_id
and team_id
using the route GET /organizations/{org_id}/team/{team_id}/discussions
.
OAuth app tokens and personal access tokens (classic) need the read:discussion
scope to use this endpoint.
octokit.rest.teams.listDiscussionsInOrg({
org,
team_slug,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
team_slug | yes |
The slug of the team name. |
direction | no |
The direction to sort the results by. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
pinned | no |
Pinned discussions only filter |
See also: GitHub Developer Guide documentation.
List teams for the authenticated user
List all of the teams across all of the organizations to which the authenticated user belongs.
OAuth app tokens and personal access tokens (classic) need the user
, repo
, or read:org
scope to use this endpoint.
When using a fine-grained personal access token, the resource owner of the token must be a single organization, and the response will only include the teams from that organization.
octokit.rest.teams.listForAuthenticatedUser();
Parameters
name | required | description |
---|---|---|
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List team members
Team members will include the members of child teams.
To list members in a team, the team must be visible to the authenticated user.
octokit.rest.teams.listMembersInOrg({
org,
team_slug,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
team_slug | yes |
The slug of the team name. |
role | no |
Filters members returned by their role in the team. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List pending team invitations
The return hash contains a role
field which refers to the Organization Invitation role and will be one of the following values: direct_member
, admin
, billing_manager
, hiring_manager
, or reinstate
. If the invitee is not a GitHub member, the login
field in the return hash will be null
.
Note: You can also specify a team by org_id
and team_id
using the route GET /organizations/{org_id}/team/{team_id}/invitations
.
octokit.rest.teams.listPendingInvitationsInOrg({
org,
team_slug,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
team_slug | yes |
The slug of the team name. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List team projects
Lists the organization projects for a team.
Note: You can also specify a team by org_id
and team_id
using the route GET /organizations/{org_id}/team/{team_id}/projects
.
octokit.rest.teams.listProjectsInOrg({
org,
team_slug,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
team_slug | yes |
The slug of the team name. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List team repositories
Lists a team's repositories visible to the authenticated user.
Note: You can also specify a team by org_id
and team_id
using the route GET /organizations/{org_id}/team/{team_id}/repos
.
octokit.rest.teams.listReposInOrg({
org,
team_slug,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
team_slug | yes |
The slug of the team name. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
Remove team membership for a user
To remove a membership between a user and a team, the authenticated user must have 'admin' permissions to the team or be an owner of the organization that the team is associated with. Removing team membership does not delete the user, it just removes their membership from the team.
Team synchronization is available for organizations using GitHub Enterprise Cloud. For more information, see GitHub's products in the GitHub Help documentation.
Note: When you have team synchronization set up for a team with your organization's identity provider (IdP), you will see an error if you attempt to use the API for making changes to the team's membership. If you have access to manage group membership in your IdP, you can manage GitHub team membership through your identity provider, which automatically adds and removes team members in an organization. For more information, see "Synchronizing teams between your identity provider and GitHub."
Note: You can also specify a team by org_id
and team_id
using the route DELETE /organizations/{org_id}/team/{team_id}/memberships/{username}
.
octokit.rest.teams.removeMembershipForUserInOrg({
org,
team_slug,
username,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
team_slug | yes |
The slug of the team name. |
username | yes |
The handle for the GitHub user account. |
See also: GitHub Developer Guide documentation.
Remove a project from a team
Removes an organization project from a team. An organization owner or a team maintainer can remove any project from the team. To remove a project from a team as an organization member, the authenticated user must have read
access to both the team and project, or admin
access to the team or project. This endpoint removes the project from the team, but does not delete the project.
Note: You can also specify a team by org_id
and team_id
using the route DELETE /organizations/{org_id}/team/{team_id}/projects/{project_id}
.
octokit.rest.teams.removeProjectInOrg({
org,
team_slug,
project_id,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
team_slug | yes |
The slug of the team name. |
project_id | yes |
The unique identifier of the project. |
See also: GitHub Developer Guide documentation.
Remove a repository from a team
If the authenticated user is an organization owner or a team maintainer, they can remove any repositories from the team. To remove a repository from a team as an organization member, the authenticated user must have admin access to the repository and must be able to see the team. This does not delete the repository, it just removes it from the team.
Note: You can also specify a team by org_id
and team_id
using the route DELETE /organizations/{org_id}/team/{team_id}/repos/{owner}/{repo}
.
octokit.rest.teams.removeRepoInOrg({
org,
team_slug,
owner,
repo,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
team_slug | yes |
The slug of the team name. |
owner | yes |
The account owner of the repository. The name is not case sensitive. |
repo | yes |
The name of the repository without the |
See also: GitHub Developer Guide documentation.
Update a discussion comment
Edits the body text of a discussion comment.
Note: You can also specify a team by org_id
and team_id
using the route PATCH /organizations/{org_id}/team/{team_id}/discussions/{discussion_number}/comments/{comment_number}
.
OAuth app tokens and personal access tokens (classic) need the write:discussion
scope to use this endpoint.
octokit.rest.teams.updateDiscussionCommentInOrg({
org,
team_slug,
discussion_number,
comment_number,
body,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
team_slug | yes |
The slug of the team name. |
discussion_number | yes |
The number that identifies the discussion. |
comment_number | yes |
The number that identifies the comment. |
body | yes |
The discussion comment's body text. |
See also: GitHub Developer Guide documentation.
Update a discussion
Edits the title and body text of a discussion post. Only the parameters you provide are updated.
Note: You can also specify a team by org_id
and team_id
using the route PATCH /organizations/{org_id}/team/{team_id}/discussions/{discussion_number}
.
OAuth app tokens and personal access tokens (classic) need the write:discussion
scope to use this endpoint.
octokit.rest.teams.updateDiscussionInOrg({
org,
team_slug,
discussion_number,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
team_slug | yes |
The slug of the team name. |
discussion_number | yes |
The number that identifies the discussion. |
title | no |
The discussion post's title. |
body | no |
The discussion post's body text. |
See also: GitHub Developer Guide documentation.
Update a team
To edit a team, the authenticated user must either be an organization owner or a team maintainer.
Note: You can also specify a team by org_id
and team_id
using the route PATCH /organizations/{org_id}/team/{team_id}
.
octokit.rest.teams.updateInOrg({
org,
team_slug,
});
Parameters
name | required | description |
---|---|---|
org | yes |
The organization name. The name is not case sensitive. |
team_slug | yes |
The slug of the team name. |
name | no |
The name of the team. |
description | no |
The description of the team. |
privacy | no |
The level of privacy this team should have. Editing teams without specifying this parameter leaves
|
notification_setting | no |
The notification setting the team has chosen. Editing teams without specifying this parameter leaves
|
permission | no |
Deprecated. The permission that new repositories will be added to the team with when none is specified. |
parent_team_id | no |
The ID of a team to set as the parent team. |
See also: GitHub Developer Guide documentation.
Users
Add an email address for the authenticated user
Deprecated: This method has been renamed to users.addEmailForAuthenticatedUser
OAuth app tokens and personal access tokens (classic) need the user
scope to use this endpoint.
octokit.rest.users.addEmailForAuthenticated({
emails,
});
Parameters
name | required | description |
---|---|---|
emails | yes |
Adds one or more email addresses to your GitHub account. Must contain at least one email address. Note: Alternatively, you can pass a single email address or an |
See also: GitHub Developer Guide documentation.
Add an email address for the authenticated user
OAuth app tokens and personal access tokens (classic) need the user
scope to use this endpoint.
octokit.rest.users.addEmailForAuthenticatedUser({
emails,
});
Parameters
name | required | description |
---|---|---|
emails | yes |
Adds one or more email addresses to your GitHub account. Must contain at least one email address. Note: Alternatively, you can pass a single email address or an |
See also: GitHub Developer Guide documentation.
Add social accounts for the authenticated user
Add one or more social accounts to the authenticated user's profile.
OAuth app tokens and personal access tokens (classic) need the user
scope to use this endpoint.
octokit.rest.users.addSocialAccountForAuthenticatedUser({
account_urls,
});
Parameters
name | required | description |
---|---|---|
account_urls | yes |
Full URLs for the social media profiles to add. |
See also: GitHub Developer Guide documentation.
Block a user
Blocks the given user and returns a 204. If the authenticated user cannot block the given user a 422 is returned.
octokit.rest.users.block({
username,
});
Parameters
name | required | description |
---|---|---|
username | yes |
The handle for the GitHub user account. |
See also: GitHub Developer Guide documentation.
Check if a user is blocked by the authenticated user
Returns a 204 if the given user is blocked by the authenticated user. Returns a 404 if the given user is not blocked by the authenticated user, or if the given user account has been identified as spam by GitHub.
octokit.rest.users.checkBlocked({
username,
});
Parameters
name | required | description |
---|---|---|
username | yes |
The handle for the GitHub user account. |
See also: GitHub Developer Guide documentation.
Check if a user follows another user
octokit.rest.users.checkFollowingForUser({
username,
target_user,
});
Parameters
name | required | description |
---|---|---|
username | yes |
The handle for the GitHub user account. |
target_user | yes |
See also: GitHub Developer Guide documentation.
Check if a person is followed by the authenticated user
octokit.rest.users.checkPersonIsFollowedByAuthenticated({
username,
});
Parameters
name | required | description |
---|---|---|
username | yes |
The handle for the GitHub user account. |
See also: GitHub Developer Guide documentation.
Create a GPG key for the authenticated user
Deprecated: This method has been renamed to users.createGpgKeyForAuthenticatedUser
Adds a GPG key to the authenticated user's GitHub account.
OAuth app tokens and personal access tokens (classic) need the write:gpg_key
scope to use this endpoint.
octokit.rest.users.createGpgKeyForAuthenticated({
armored_public_key,
});
Parameters
name | required | description |
---|---|---|
name | no |
A descriptive name for the new key. |
armored_public_key | yes |
A GPG key in ASCII-armored format. |
See also: GitHub Developer Guide documentation.
Create a GPG key for the authenticated user
Adds a GPG key to the authenticated user's GitHub account.
OAuth app tokens and personal access tokens (classic) need the write:gpg_key
scope to use this endpoint.
octokit.rest.users.createGpgKeyForAuthenticatedUser({
armored_public_key,
});
Parameters
name | required | description |
---|---|---|
name | no |
A descriptive name for the new key. |
armored_public_key | yes |
A GPG key in ASCII-armored format. |
See also: GitHub Developer Guide documentation.
Create a public SSH key for the authenticated user
Deprecated: This method has been renamed to users.createPublicSshKeyForAuthenticatedUser
Adds a public SSH key to the authenticated user's GitHub account.
OAuth app tokens and personal access tokens (classic) need the write:gpg_key
scope to use this endpoint.
octokit.rest.users.createPublicSshKeyForAuthenticated({
key,
});
Parameters
name | required | description |
---|---|---|
title | no |
A descriptive name for the new key. |
key | yes |
The public SSH key to add to your GitHub account. |
See also: GitHub Developer Guide documentation.
Create a public SSH key for the authenticated user
Adds a public SSH key to the authenticated user's GitHub account.
OAuth app tokens and personal access tokens (classic) need the write:gpg_key
scope to use this endpoint.
octokit.rest.users.createPublicSshKeyForAuthenticatedUser({
key,
});
Parameters
name | required | description |
---|---|---|
title | no |
A descriptive name for the new key. |
key | yes |
The public SSH key to add to your GitHub account. |
See also: GitHub Developer Guide documentation.
Create a SSH signing key for the authenticated user
Creates an SSH signing key for the authenticated user's GitHub account.
OAuth app tokens and personal access tokens (classic) need the write:ssh_signing_key
scope to use this endpoint.
octokit.rest.users.createSshSigningKeyForAuthenticatedUser({
key,
});
Parameters
name | required | description |
---|---|---|
title | no |
A descriptive name for the new key. |
key | yes |
The public SSH key to add to your GitHub account. For more information, see "Checking for existing SSH keys." |
See also: GitHub Developer Guide documentation.
Delete an email address for the authenticated user
Deprecated: This method has been renamed to users.deleteEmailForAuthenticatedUser
OAuth app tokens and personal access tokens (classic) need the user
scope to use this endpoint.
octokit.rest.users.deleteEmailForAuthenticated({
emails,
});
Parameters
name | required | description |
---|---|---|
emails | yes |
Email addresses associated with the GitHub user account. |
See also: GitHub Developer Guide documentation.
Delete an email address for the authenticated user
OAuth app tokens and personal access tokens (classic) need the user
scope to use this endpoint.
octokit.rest.users.deleteEmailForAuthenticatedUser({
emails,
});
Parameters
name | required | description |
---|---|---|
emails | yes |
Email addresses associated with the GitHub user account. |
See also: GitHub Developer Guide documentation.
Delete a GPG key for the authenticated user
Deprecated: This method has been renamed to users.deleteGpgKeyForAuthenticatedUser
Removes a GPG key from the authenticated user's GitHub account.
OAuth app tokens and personal access tokens (classic) need the admin:gpg_key
scope to use this endpoint.
octokit.rest.users.deleteGpgKeyForAuthenticated({
gpg_key_id,
});
Parameters
name | required | description |
---|---|---|
gpg_key_id | yes |
The unique identifier of the GPG key. |
See also: GitHub Developer Guide documentation.
Delete a GPG key for the authenticated user
Removes a GPG key from the authenticated user's GitHub account.
OAuth app tokens and personal access tokens (classic) need the admin:gpg_key
scope to use this endpoint.
octokit.rest.users.deleteGpgKeyForAuthenticatedUser({
gpg_key_id,
});
Parameters
name | required | description |
---|---|---|
gpg_key_id | yes |
The unique identifier of the GPG key. |
See also: GitHub Developer Guide documentation.
Delete a public SSH key for the authenticated user
Deprecated: This method has been renamed to users.deletePublicSshKeyForAuthenticatedUser
Removes a public SSH key from the authenticated user's GitHub account.
OAuth app tokens and personal access tokens (classic) need the admin:public_key
scope to use this endpoint.
octokit.rest.users.deletePublicSshKeyForAuthenticated({
key_id,
});
Parameters
name | required | description |
---|---|---|
key_id | yes |
The unique identifier of the key. |
See also: GitHub Developer Guide documentation.
Delete a public SSH key for the authenticated user
Removes a public SSH key from the authenticated user's GitHub account.
OAuth app tokens and personal access tokens (classic) need the admin:public_key
scope to use this endpoint.
octokit.rest.users.deletePublicSshKeyForAuthenticatedUser({
key_id,
});
Parameters
name | required | description |
---|---|---|
key_id | yes |
The unique identifier of the key. |
See also: GitHub Developer Guide documentation.
Delete social accounts for the authenticated user
Deletes one or more social accounts from the authenticated user's profile.
OAuth app tokens and personal access tokens (classic) need the user
scope to use this endpoint.
octokit.rest.users.deleteSocialAccountForAuthenticatedUser({
account_urls,
});
Parameters
name | required | description |
---|---|---|
account_urls | yes |
Full URLs for the social media profiles to delete. |
See also: GitHub Developer Guide documentation.
Delete an SSH signing key for the authenticated user
Deletes an SSH signing key from the authenticated user's GitHub account.
OAuth app tokens and personal access tokens (classic) need the admin:ssh_signing_key
scope to use this endpoint.
octokit.rest.users.deleteSshSigningKeyForAuthenticatedUser({
ssh_signing_key_id,
});
Parameters
name | required | description |
---|---|---|
ssh_signing_key_id | yes |
The unique identifier of the SSH signing key. |
See also: GitHub Developer Guide documentation.
Follow a user
Note that you'll need to set Content-Length
to zero when calling out to this endpoint. For more information, see "HTTP verbs."
OAuth app tokens and personal access tokens (classic) need the user:follow
scope to use this endpoint.
octokit.rest.users.follow({
username,
});
Parameters
name | required | description |
---|---|---|
username | yes |
The handle for the GitHub user account. |
See also: GitHub Developer Guide documentation.
Get the authenticated user
OAuth app tokens and personal access tokens (classic) need the user
scope in order for the response to include private profile information.
octokit.rest.users.getAuthenticated();
Parameters
This endpoint has no parameters
See also: GitHub Developer Guide documentation.
Get a user
Provides publicly available information about someone with a GitHub account.
The email
key in the following response is the publicly visible email address from your GitHub profile page. When setting up your profile, you can select a primary email address to be “public” which provides an email entry for this endpoint. If you do not set a public email address for email
, then it will have a value of null
. You only see publicly visible email addresses when authenticated with GitHub. For more information, see Authentication.
The Emails API enables you to list all of your email addresses, and toggle a primary email to be visible publicly. For more information, see "Emails API".
octokit.rest.users.getByUsername({
username,
});
Parameters
name | required | description |
---|---|---|
username | yes |
The handle for the GitHub user account. |
See also: GitHub Developer Guide documentation.
Get contextual information for a user
Provides hovercard information. You can find out more about someone in relation to their pull requests, issues, repositories, and organizations.
The subject_type
and subject_id
parameters provide context for the person's hovercard, which returns more information than without the parameters. For example, if you wanted to find out more about octocat
who owns the Spoon-Knife
repository, you would use a subject_type
value of repository
and a subject_id
value of 1300192
(the ID of the Spoon-Knife
repository).
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
octokit.rest.users.getContextForUser({
username,
});
Parameters
name | required | description |
---|---|---|
username | yes |
The handle for the GitHub user account. |
subject_type | no |
Identifies which additional information you'd like to receive about the person's hovercard. Can be |
subject_id | no |
Uses the ID for the |
See also: GitHub Developer Guide documentation.
Get a GPG key for the authenticated user
Deprecated: This method has been renamed to users.getGpgKeyForAuthenticatedUser
View extended details for a single GPG key.
OAuth app tokens and personal access tokens (classic) need the read:gpg_key
scope to use this endpoint.
octokit.rest.users.getGpgKeyForAuthenticated({
gpg_key_id,
});
Parameters
name | required | description |
---|---|---|
gpg_key_id | yes |
The unique identifier of the GPG key. |
See also: GitHub Developer Guide documentation.
Get a GPG key for the authenticated user
View extended details for a single GPG key.
OAuth app tokens and personal access tokens (classic) need the read:gpg_key
scope to use this endpoint.
octokit.rest.users.getGpgKeyForAuthenticatedUser({
gpg_key_id,
});
Parameters
name | required | description |
---|---|---|
gpg_key_id | yes |
The unique identifier of the GPG key. |
See also: GitHub Developer Guide documentation.
Get a public SSH key for the authenticated user
Deprecated: This method has been renamed to users.getPublicSshKeyForAuthenticatedUser
View extended details for a single public SSH key.
OAuth app tokens and personal access tokens (classic) need the read:public_key
scope to use this endpoint.
octokit.rest.users.getPublicSshKeyForAuthenticated({
key_id,
});
Parameters
name | required | description |
---|---|---|
key_id | yes |
The unique identifier of the key. |
See also: GitHub Developer Guide documentation.
Get a public SSH key for the authenticated user
View extended details for a single public SSH key.
OAuth app tokens and personal access tokens (classic) need the read:public_key
scope to use this endpoint.
octokit.rest.users.getPublicSshKeyForAuthenticatedUser({
key_id,
});
Parameters
name | required | description |
---|---|---|
key_id | yes |
The unique identifier of the key. |
See also: GitHub Developer Guide documentation.
Get an SSH signing key for the authenticated user
Gets extended details for an SSH signing key.
OAuth app tokens and personal access tokens (classic) need the read:ssh_signing_key
scope to use this endpoint.
octokit.rest.users.getSshSigningKeyForAuthenticatedUser({
ssh_signing_key_id,
});
Parameters
name | required | description |
---|---|---|
ssh_signing_key_id | yes |
The unique identifier of the SSH signing key. |
See also: GitHub Developer Guide documentation.
List users
Lists all users, in the order that they signed up on GitHub. This list includes personal user accounts and organization accounts.
Note: Pagination is powered exclusively by the since
parameter. Use the Link header to get the URL for the next page of users.
octokit.rest.users.list();
Parameters
name | required | description |
---|---|---|
since | no |
A user ID. Only return users with an ID greater than this ID. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List users blocked by the authenticated user
Deprecated: This method has been renamed to users.listBlockedByAuthenticatedUser
List the users you've blocked on your personal account.
octokit.rest.users.listBlockedByAuthenticated();
Parameters
name | required | description |
---|---|---|
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List users blocked by the authenticated user
List the users you've blocked on your personal account.
octokit.rest.users.listBlockedByAuthenticatedUser();
Parameters
name | required | description |
---|---|---|
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List email addresses for the authenticated user
Deprecated: This method has been renamed to users.listEmailsForAuthenticatedUser
Lists all of your email addresses, and specifies which one is visible to the public.
OAuth app tokens and personal access tokens (classic) need the user:email
scope to use this endpoint.
octokit.rest.users.listEmailsForAuthenticated();
Parameters
name | required | description |
---|---|---|
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List email addresses for the authenticated user
Lists all of your email addresses, and specifies which one is visible to the public.
OAuth app tokens and personal access tokens (classic) need the user:email
scope to use this endpoint.
octokit.rest.users.listEmailsForAuthenticatedUser();
Parameters
name | required | description |
---|---|---|
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List the people the authenticated user follows
Deprecated: This method has been renamed to users.listFollowedByAuthenticatedUser
Lists the people who the authenticated user follows.
octokit.rest.users.listFollowedByAuthenticated();
Parameters
name | required | description |
---|---|---|
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List the people the authenticated user follows
Lists the people who the authenticated user follows.
octokit.rest.users.listFollowedByAuthenticatedUser();
Parameters
name | required | description |
---|---|---|
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List followers of the authenticated user
Lists the people following the authenticated user.
octokit.rest.users.listFollowersForAuthenticatedUser();
Parameters
name | required | description |
---|---|---|
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List followers of a user
Lists the people following the specified user.
octokit.rest.users.listFollowersForUser({
username,
});
Parameters
name | required | description |
---|---|---|
username | yes |
The handle for the GitHub user account. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List the people a user follows
Lists the people who the specified user follows.
octokit.rest.users.listFollowingForUser({
username,
});
Parameters
name | required | description |
---|---|---|
username | yes |
The handle for the GitHub user account. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List GPG keys for the authenticated user
Deprecated: This method has been renamed to users.listGpgKeysForAuthenticatedUser
Lists the current user's GPG keys.
OAuth app tokens and personal access tokens (classic) need the read:gpg_key
scope to use this endpoint.
octokit.rest.users.listGpgKeysForAuthenticated();
Parameters
name | required | description |
---|---|---|
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List GPG keys for the authenticated user
Lists the current user's GPG keys.
OAuth app tokens and personal access tokens (classic) need the read:gpg_key
scope to use this endpoint.
octokit.rest.users.listGpgKeysForAuthenticatedUser();
Parameters
name | required | description |
---|---|---|
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List GPG keys for a user
Lists the GPG keys for a user. This information is accessible by anyone.
octokit.rest.users.listGpgKeysForUser({
username,
});
Parameters
name | required | description |
---|---|---|
username | yes |
The handle for the GitHub user account. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List public email addresses for the authenticated user
Deprecated: This method has been renamed to users.listPublicEmailsForAuthenticatedUser
Lists your publicly visible email address, which you can set with the Set primary email visibility for the authenticated user endpoint.
OAuth app tokens and personal access tokens (classic) need the user:email
scope to use this endpoint.
octokit.rest.users.listPublicEmailsForAuthenticated();
Parameters
name | required | description |
---|---|---|
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List public email addresses for the authenticated user
Lists your publicly visible email address, which you can set with the Set primary email visibility for the authenticated user endpoint.
OAuth app tokens and personal access tokens (classic) need the user:email
scope to use this endpoint.
octokit.rest.users.listPublicEmailsForAuthenticatedUser();
Parameters
name | required | description |
---|---|---|
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List public keys for a user
Lists the verified public SSH keys for a user. This is accessible by anyone.
octokit.rest.users.listPublicKeysForUser({
username,
});
Parameters
name | required | description |
---|---|---|
username | yes |
The handle for the GitHub user account. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List public SSH keys for the authenticated user
Deprecated: This method has been renamed to users.listPublicSshKeysForAuthenticatedUser
Lists the public SSH keys for the authenticated user's GitHub account.
OAuth app tokens and personal access tokens (classic) need the read:public_key
scope to use this endpoint.
octokit.rest.users.listPublicSshKeysForAuthenticated();
Parameters
name | required | description |
---|---|---|
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List public SSH keys for the authenticated user
Lists the public SSH keys for the authenticated user's GitHub account.
OAuth app tokens and personal access tokens (classic) need the read:public_key
scope to use this endpoint.
octokit.rest.users.listPublicSshKeysForAuthenticatedUser();
Parameters
name | required | description |
---|---|---|
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List social accounts for the authenticated user
Lists all of your social accounts.
octokit.rest.users.listSocialAccountsForAuthenticatedUser();
Parameters
name | required | description |
---|---|---|
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List social accounts for a user
Lists social media accounts for a user. This endpoint is accessible by anyone.
octokit.rest.users.listSocialAccountsForUser({
username,
});
Parameters
name | required | description |
---|---|---|
username | yes |
The handle for the GitHub user account. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List SSH signing keys for the authenticated user
Lists the SSH signing keys for the authenticated user's GitHub account.
OAuth app tokens and personal access tokens (classic) need the read:ssh_signing_key
scope to use this endpoint.
octokit.rest.users.listSshSigningKeysForAuthenticatedUser();
Parameters
name | required | description |
---|---|---|
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
List SSH signing keys for a user
Lists the SSH signing keys for a user. This operation is accessible by anyone.
octokit.rest.users.listSshSigningKeysForUser({
username,
});
Parameters
name | required | description |
---|---|---|
username | yes |
The handle for the GitHub user account. |
per_page | no |
The number of results per page (max 100). For more information, see "Using pagination in the REST API." |
page | no |
The page number of the results to fetch. For more information, see "Using pagination in the REST API." |
See also: GitHub Developer Guide documentation.
Set primary email visibility for the authenticated user
Deprecated: This method has been renamed to users.setPrimaryEmailVisibilityForAuthenticatedUser
Sets the visibility for your primary email addresses.
octokit.rest.users.setPrimaryEmailVisibilityForAuthenticated({
visibility,
});
Parameters
name | required | description |
---|---|---|
visibility | yes |
Denotes whether an email is publicly visible. |
See also: GitHub Developer Guide documentation.
Set primary email visibility for the authenticated user
Sets the visibility for your primary email addresses.
octokit.rest.users.setPrimaryEmailVisibilityForAuthenticatedUser({
visibility,
});
Parameters
name | required | description |
---|---|---|
visibility | yes |
Denotes whether an email is publicly visible. |
See also: GitHub Developer Guide documentation.
Unblock a user
Unblocks the given user and returns a 204.
octokit.rest.users.unblock({
username,
});
Parameters
name | required | description |
---|---|---|
username | yes |
The handle for the GitHub user account. |
See also: GitHub Developer Guide documentation.
Unfollow a user
OAuth app tokens and personal access tokens (classic) need the user:follow
scope to use this endpoint.
octokit.rest.users.unfollow({
username,
});
Parameters
name | required | description |
---|---|---|
username | yes |
The handle for the GitHub user account. |
See also: GitHub Developer Guide documentation.
Update the authenticated user
Note: If your email is set to private and you send an email
parameter as part of this request to update your profile, your privacy settings are still enforced: the email address will not be displayed on your public profile or via the API.
octokit.rest.users.updateAuthenticated();
Parameters
name | required | description |
---|---|---|
name | no |
The new name of the user. |
no |
The publicly visible email address of the user. | |
blog | no |
The new blog URL of the user. |
twitter_username | no |
The new Twitter username of the user. |
company | no |
The new company of the user. |
location | no |
The new location of the user. |
hireable | no |
The new hiring availability of the user. |
bio | no |
The new short biography of the user. |
See also: GitHub Developer Guide documentation.