Self-hosted runners

Self-hosted runners allow you to host your own runners and customize the environment used to run jobs in your GitHub Actions workflows. For more information, see "Hosting your own runners" in the GitHub Help documentation.

This API is available for authenticated users, OAuth Apps, and GitHub Apps. Access tokens require repo scope for private repos and public_repo scope for public repos. GitHub Apps must have the administration permission to use this API. Authenticated users must have admin access to the repository to use this API.

GitHub Actions is available with GitHub Free, GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub One. GitHub Actions is not available for repositories owned by accounts using legacy per-repository plans. For more information, see GitHub's products in the GitHub Help documentation.

Warning: The GitHub Actions API is currently in public beta and subject to change.

List downloads for the self-hosted runner application

Lists binaries for the self-hosted runner application that you can download and run. Anyone with admin access to the repository can use this endpoint. GitHub Apps must have the administration permission to use this endpoint.

GET /repos/:owner/:repo/actions/runners/downloads

Response

Status: 200 OK
[
  {
    "os": "osx",
    "architecture": "x64",
    "download_url": "https://github.com/actions/runner/releases/download/v2.164.0/actions-runner-osx-x64-2.164.0.tar.gz",
    "filename": "actions-runner-osx-x64-2.164.0.tar.gz"
  },
  {
    "os": "linux",
    "architecture": "x64",
    "download_url": "https://github.com/actions/runner/releases/download/v2.164.0/actions-runner-linux-x64-2.164.0.tar.gz",
    "filename": "actions-runner-linux-x64-2.164.0.tar.gz"
  },
  {
    "os": "linux",
    "architecture": "arm",
    "download_url": "https://github.com/actions/runner/releases/download/v2.164.0/actions-runner-linux-arm-2.164.0.tar.gz",
    "filename": "actions-runner-linux-arm-2.164.0.tar.gz"
  },
  {
    "os": "win",
    "architecture": "x64",
    "download_url": "https://github.com/actions/runner/releases/download/v2.164.0/actions-runner-win-x64-2.164.0.zip",
    "filename": "actions-runner-win-x64-2.164.0.zip"
  },
  {
    "os": "linux",
    "architecture": "arm64",
    "download_url": "https://github.com/actions/runner/releases/download/v2.164.0/actions-runner-linux-arm64-2.164.0.tar.gz",
    "filename": "actions-runner-linux-arm64-2.164.0.tar.gz"
  }
]

Create a registration token

Returns a token that you can pass to the config script. The token expires after one hour. Anyone with admin access to the repository can use this endpoint. GitHub Apps must have the administration permission to use this endpoint.

POST /repos/:owner/:repo/actions/runners/registration-token

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

Response

Status: 201 Created
{
  "token": "LLBF3JGZDX3P5PMEXLND6TS6FCWO6",
  "expires_at": "2020-01-22T12:13:35.123-08:00"
}

List self-hosted runners for a repository

Lists all self-hosted runners for a repository. Anyone with admin access to the repository can use this endpoint. GitHub Apps must have the administration permission to use this endpoint.

GET /repos/:owner/:repo/actions/runners

Response

Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="next",
      <https://api.github.com/resource?page=5>; rel="last"
[
  [
    {
      "id": 23,
      "name": "MBP",
      "os": "macos",
      "status": "online"
    },
    {
      "id": 24,
      "name": "iMac",
      "os": "macos",
      "status": "offline"
    }
  ]
]

Get a self-hosted runner

Gets a specific self-hosted runner. Anyone with admin access to the repository can use this endpoint. GitHub Apps must have the administration permission to use this endpoint.

GET /repos/:owner/:repo/actions/runners/:runner_id

Response

Status: 200 OK
{
  "id": 23,
  "name": "MBP",
  "os": "macos",
  "status": "online"
}

Create a remove token

Returns a token that you can pass to remove a self-hosted runner from a repository. The token expires after one hour. Anyone with admin access to the repository can use this endpoint. GitHub Apps must have the administration permission to use this endpoint.

POST /repos/:owner/:repo/actions/runners/remove-token

Example using remove token

Remove your self-hosted runner from a repository, replacing TOKEN with the remove token provided by this endpoint.

./config.sh remove --token TOKEN

Response

Status: 201 Created
{
  "token": "AABF3JGZDX3P5PMEXLND6TS6FCWO6",
  "expires_at": "2020-01-29T12:13:35.123-08:00"
}

Remove a self-hosted runner

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. Anyone with admin access to the repository can use this endpoint. GitHub Apps must have the administration permission to use this endpoint.

DELETE /repos/:owner/:repo/actions/runners/:runner_id

Response

Status: 204 No Content