GitHub v3 REST API

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

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](https://docs.github.com/[email protected]/rest/reference/actions#create-or-update-an-organization-secret). 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.

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

Cancel a workflow run Cancels a workflow run using its `id`. You must authenticate using an access token with the `repo` scope to use this endpoint. GitHub Apps must have the `actions:write` permission to use this endpoint.

Create or update an organization secret Creates or updates an organization secret with an encrypted value. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). 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](https://github.com/github/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](https://pynacl.readthedocs.io/en/stable/public/#nacl-public-sealedbox) 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](https://www.nuget.org/packages/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](https://github.com/RubyCrypto/rbnacl) gem. ```ruby 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) ```

Create or update a repository secret Creates or updates a repository secret with an encrypted value. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). You must authenticate using an access token with the `repo` scope to use this endpoint. GitHub Apps must have the `secrets` repository permission to use this endpoint. #### Example encrypting a secret using Node.js Encrypt your secret using the [tweetsodium](https://github.com/github/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](https://pynacl.readthedocs.io/en/stable/public/#nacl-public-sealedbox) 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](https://www.nuget.org/packages/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](https://github.com/RubyCrypto/rbnacl) gem. ```ruby 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) ```

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

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

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. You must authenticate using an access token with the `admin:org` scope to use this endpoint. #### Example using remove token To remove your self-hosted runner from an organization, replace `TOKEN` with the remove token provided by this endpoint. ``` ./config.sh remove --token TOKEN ```

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

Create a self-hosted runner group for an organization The self-hosted runner groups REST API is available with GitHub Enterprise Cloud and GitHub Enterprise Server. For more information, see "[GitHub's products](https://docs.github.com/github/getting-started-with-github/githubs-products)." Creates a new self-hosted runner group for an organization. You must authenticate using an access token with the `admin:org` scope to use this endpoint.

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](/developers/webhooks-and-events/webhook-events-and-payloads#workflow_dispatch) 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](/actions/reference/events-that-trigger-workflows#workflow_dispatch)." You must authenticate using an access token with the `repo` scope to use this endpoint. GitHub Apps must have the `actions:write` permission to use this endpoint. For more information, see "[Creating a personal access token for the command line](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line)."

Delete an artifact Deletes an artifact for a workflow run. You must authenticate using an access token with the `repo` scope to use this endpoint. GitHub Apps must have the `actions:write` permission to use this endpoint.

Delete an organization secret Deletes a secret in an organization using the secret name. 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.

Delete a repository secret Deletes a secret in a repository using the secret name. You must authenticate using an access token with the `repo` scope to use this endpoint. GitHub Apps must have the `secrets` repository permission to use this endpoint.

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. You must authenticate using an access token with the `admin:org` scope to use this endpoint.

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. You must authenticate using an access token with the `repo` scope to use this endpoint.

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

Delete a workflow run Delete a specific workflow run. Anyone with write access to the repository can use this endpoint. If the repository is private you must use an access token with the `repo` scope. GitHub Apps must have the `actions:write` permission to use this endpoint.

Delete workflow run logs Deletes all logs for a workflow run. You must authenticate using an access token with the `repo` scope to use this endpoint. GitHub Apps must have the `actions:write` permission to use this endpoint.

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`. Anyone with read access to the repository can use this endpoint. If the repository is private you must use an access token with the `repo` scope. GitHub Apps must have the `actions:read` permission to use this endpoint.

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 you must use an access token with the `repo` scope. GitHub Apps must have the `actions:read` permission to use this endpoint.

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 you must use an access token with the `repo` scope. GitHub Apps must have the `actions:read` permission to use this endpoint.

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 you must use an access token with the `repo` scope. GitHub Apps must have the `actions:read` permission to use this endpoint.

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 you must use an access token with the `repo` scope. GitHub Apps must have the `actions:read` permission to use this endpoint.

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. 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.

Get an organization secret Gets a single organization secret without revealing its encrypted value. 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.

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 you must use an access token with the `repo` scope. GitHub Apps must have the `secrets` repository permission to use this endpoint.

Get a repository secret Gets a single repository secret without revealing its encrypted value. You must authenticate using an access token with the `repo` scope to use this endpoint. GitHub Apps must have the `secrets` repository permission to use this endpoint.

Get a self-hosted runner for an organization Gets a specific self-hosted runner configured in an organization. You must authenticate using an access token with the `admin:org` scope to use this endpoint.

Get a self-hosted runner for a repository Gets a specific self-hosted runner configured in a repository. You must authenticate using an access token with the `repo` scope to use this endpoint.

Get a self-hosted runner group for an organization Gets a specific self-hosted runner group for an organization. You must authenticate using an access token with the `admin:org` scope to use this endpoint.

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. If the repository is private you must use an access token with the `repo` scope. GitHub Apps must have the `actions:read` permission to use this endpoint.

Get a workflow run Gets a specific workflow run. Anyone with read access to the repository can use this endpoint. If the repository is private you must use an access token with the `repo` scope. GitHub Apps must have the `actions:read` permission to use this endpoint.

List artifacts for a repository Lists all artifacts for a repository. Anyone with read access to the repository can use this endpoint. If the repository is private you must use an access token with the `repo` scope. GitHub Apps must have the `actions:read` permission to use this endpoint.

List jobs for a workflow run Lists jobs for a workflow run. Anyone with read access to the repository can use this endpoint. If the repository is private you must use an access token with the `repo` scope. GitHub Apps must have the `actions:read` permission to use this endpoint. You can use parameters to narrow the list of results. For more information about using parameters, see [Parameters](https://docs.github.com/[email protected]/rest/overview/resources-in-the-rest-api#parameters).

List organization secrets Lists all secrets available in an organization without revealing their encrypted values. 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.

List repository access to a self-hosted runner group in an organization The self-hosted runner groups REST API is available with GitHub Enterprise Cloud and GitHub Enterprise Server. For more information, see "[GitHub's products](https://docs.github.com/github/getting-started-with-github/githubs-products)." Lists the repositories with access to a self-hosted runner group configured in an organization. You must authenticate using an access token with the `admin:org` scope to use this endpoint.

List repository secrets Lists all secrets available in a repository without revealing their encrypted values. You must authenticate using an access token with the `repo` scope to use this endpoint. GitHub Apps must have the `secrets` repository permission to use this endpoint.

List repository workflows Lists the workflows in a repository. Anyone with read access to the repository can use this endpoint. If the repository is private you must use an access token with the `repo` scope. GitHub Apps must have the `actions:read` permission to use this endpoint.

List runner applications for an organization Lists binaries for the runner application that you can download and run. You must authenticate using an access token with the `admin:org` scope to use this endpoint.

List runner applications for a repository Lists binaries for the runner application that you can download and run. You must authenticate using an access token with the `repo` scope to use this endpoint.

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`. 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.

List self-hosted runner groups for an organization Lists all self-hosted runner groups configured in an organization and inherited from an enterprise. You must authenticate using an access token with the `admin:org` scope to use this endpoint.

List self-hosted runners for an organization Lists all self-hosted runners configured in an organization. You must authenticate using an access token with the `admin:org` scope to use this endpoint.

List self-hosted runners for a repository Lists all self-hosted runners configured in a repository. You must authenticate using an access token with the `repo` scope to use this endpoint.

List self-hosted runners in a group for an organization Lists self-hosted runners that are in a specific organization group. You must authenticate using an access token with the `admin:org` scope to use this endpoint.

List workflow run artifacts Lists artifacts for a workflow run. Anyone with read access to the repository can use this endpoint. If the repository is private you must use an access token with the `repo` scope. GitHub Apps must have the `actions:read` permission to use this endpoint.

List workflow runs 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](https://docs.github.com/[email protected]/rest/overview/resources-in-the-rest-api#parameters). Anyone with read access to the repository can use this endpoint. If the repository is private you must use an access token with the `repo` scope.

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](https://docs.github.com/[email protected]/rest/overview/resources-in-the-rest-api#parameters). Anyone with read access to the repository can use this endpoint. If the repository is private you must use an access token with the `repo` scope. GitHub Apps must have the `actions:read` permission to use this endpoint.