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 for repositories or the organization_self_hosted_runners permission for organizations. Authenticated users must have admin access to the repository or organization to use this API.

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

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. 

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

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. You must authenticate using an access token with the repo scope 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"

{
  "total_count": 2,
  "runners": [
    {
      "id": 23,
      "name": "MBP",
      "os": "macos",
      "status": "online"
    },
    {
      "id": 24,
      "name": "iMac",
      "os": "macos",
      "status": "offline"
    }
  ]
}

Get a self-hosted runner for a repository

Gets a specific self-hosted runner. You must authenticate using an access token with the repo scope 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 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. 

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

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 /repos/:owner/:repo/actions/runners/:runner_id

Response

Status: 204 No Content

List runner applications for an organization

Warning: The self-hosted runners API for organizations is currently in public beta and subject to change.

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. 

GET /orgs/:org/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 for an organization

Warning: The self-hosted runners API for organizations is currently in public beta and subject to change.

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. 

POST /orgs/:org/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 --token TOKEN

Response

Status: 201 Created

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

List self-hosted runners for an organization

Warning: The self-hosted runners API for organizations is currently in public beta and subject to change.

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

GET /orgs/:org/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"

{
  "total_count": 2,
  "runners": [
    {
      "id": 23,
      "name": "MBP",
      "os": "macos",
      "status": "online"
    },
    {
      "id": 24,
      "name": "iMac",
      "os": "macos",
      "status": "offline"
    }
  ]
}

Get a self-hosted runner for an organization

Warning: The self-hosted runners API for organizations is currently in public beta and subject to change.

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

GET /orgs/:org/actions/runners/:runner_id

Response

Status: 200 OK

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

Create a remove token for an organization

Warning: The self-hosted runners API for organizations is currently in public beta and subject to change.

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. 

POST /orgs/:org/actions/runners/remove-token

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

Response

Status: 201 Created

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

Delete a self-hosted runner from an organization

Warning: The self-hosted runners API for organizations is currently in public beta and subject to change.

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 /orgs/:org/actions/runners/:runner_id

Response

Status: 204 No Content