GitHub Actions

GitHub Actions Self-Hosted Runners API

Manage self-hosted runners for workflows

GitHub OpenAPI

Operations 11

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

GET /repos/{owner}/{repo}/actions/runners List a repository's self-hosted runners · Github Actions List Self-hosted Runners for a Repository #
Ask an LLM
“Which self-hosted runners are registered to my repository and are they online?”
“Can I find a repository runner by its name?”
Tell an agent
List the self-hosted runners registered to {owner}/{repo}.
Find the runner named {name} in {owner}/{repo}.
GET /repos/{owner}/{repo}/actions/runners/{runner_id} Get details of one self-hosted runner · Github Actions Get a Self-hosted Runner for a Repository #
Ask an LLM
“Is a specific self-hosted runner online and busy right now?”
“What operating system and labels does a given runner report?”
Tell an agent
Get self-hosted runner {runner_id} in {owner}/{repo}.
Check the status and OS of runner {runner_id}.
DELETE /repos/{owner}/{repo}/actions/runners/{runner_id} Force-remove a self-hosted runner from a repo · Github Actions Delete a Self-hosted Runner From a Repository #
Ask an LLM
“How do I force the removal of a dead runner that no longer exists on the machine?”
“Can I deregister a self-hosted runner from my repository through the API?”
Tell an agent destructive · confirm first
Force-remove runner {runner_id} from {owner}/{repo}.
Delete the offline self-hosted runner {runner_id}.
GET /repos/{owner}/{repo}/actions/runners/downloads List runner application downloads · Github Actions List Runner Applications for a Repository #
Ask an LLM
“Where do I download the runner application binary for Linux, macOS or Windows?”
“What runner software packages are available to install on my own machine?”
Tell an agent
List the runner application binaries I can download for {owner}/{repo}.
Get the download URL of the runner package for my OS and architecture.
POST /repos/{owner}/{repo}/actions/runners/registration-token Get a token to register a new runner · Github Actions Create a Registration Token for a Repository #
Ask an LLM
“How do I get the token the config script needs to register a self-hosted runner?”
“What do I need before adding a new runner machine to my repository?”
Tell an agent
Create a runner registration token for {owner}/{repo}.
Give me a token to register a new self-hosted runner on {repo}.
POST /repos/{owner}/{repo}/actions/runners/remove-token Get a token to unregister a runner · Github Actions Create a Remove Token for a Repository #
Ask an LLM
“Which token does the config script need to cleanly remove a runner from my repository?”
“How do I unregister a self-hosted runner from the machine it runs on?”
Tell an agent
Create a runner remove token for {owner}/{repo}.
Give me a token to unregister a self-hosted runner from {repo}.
GET /repos/{owner}/{repo}/actions/runners/{runner_id}/labels List the labels on a self-hosted runner · Github Actions List Labels for a Self-hosted Runner for a Repository #
Ask an LLM
“What labels does a self-hosted runner have that jobs can target with runs-on?”
“Which custom and default labels are attached to one of my runners?”
Tell an agent
List the labels on runner {runner_id} in {owner}/{repo}.
Show which runs-on labels runner {runner_id} answers to.
POST /repos/{owner}/{repo}/actions/runners/{runner_id}/labels Add custom labels to a runner · Github Actions Add Custom Labels to a Self-hosted Runner for a Repository #
Ask an LLM
“How do I tag a self-hosted runner with an extra label like gpu without losing its existing ones?”
“Can I append new labels to a runner?”
Tell an agent
Add labels {labels} to runner {runner_id} in {owner}/{repo}.
Append the label {labels} to runner {runner_id}, keeping its current labels.
PUT /repos/{owner}/{repo}/actions/runners/{runner_id}/labels Replace all custom labels on a runner · Github Actions Set Custom Labels for a Self-hosted Runner for a Repository #
Ask an LLM
“How do I overwrite a runner's custom labels with a completely new set?”
“Can I reset a runner's labels to an exact list in one call?”
Tell an agent
Replace the custom labels on runner {runner_id} in {owner}/{repo} with {labels}.
Set runner {runner_id}'s labels to exactly {labels}, dropping the old ones.
DELETE /repos/{owner}/{repo}/actions/runners/{runner_id}/labels Clear every custom label from a runner · Github Actions Remove All Custom Labels From a Self-hosted Runner for a… #
Ask an LLM
“How do I strip all custom labels off a runner and leave only the defaults?”
“Can I wipe a runner's custom labels in one go?”
Tell an agent destructive · confirm first
Remove all custom labels from runner {runner_id} in {owner}/{repo}.
Clear every custom label on runner {runner_id}.
DELETE /repos/{owner}/{repo}/actions/runners/{runner_id}/labels/{name} Remove one custom label from a runner · Github Actions Remove a Custom Label From a Self-hosted Runner for a Repository #
Ask an LLM
“How do I take a single label off a self-hosted runner?”
“Can I drop one custom label while keeping the runner's other labels?”
Tell an agent destructive · confirm first
Remove the label {name} from runner {runner_id} in {owner}/{repo}.
Untag runner {runner_id} from label {name} only.

Documentation

📖
Documentation
https://docs.github.com/en/rest/actions
📖
Authentication
https://docs.github.com/en/rest/overview/authenticating-to-the-rest-api
📖
GettingStarted
https://docs.github.com/en/actions/get-started/quickstart
📖
APIReference
https://docs.github.com/en/rest/actions
📖
RateLimits
https://docs.github.com/en/rest/overview/rate-limits-for-the-rest-api

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/github-actions/refs/heads/main/openapi/github-actions-self-hosted-runners-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/github-actions/refs/heads/main/json-schema/github-actions-workflow-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/github-actions/refs/heads/main/json-schema/github-actions-run-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/github-actions/refs/heads/main/json-schema/github-actions-job-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/github-actions/refs/heads/main/json-schema/github-actions-artifact-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/github-actions/refs/heads/main/json-schema/github-actions-secret-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/github-actions/refs/heads/main/json-schema/github-actions-runner-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/github-actions/refs/heads/main/json-schema/github-actions-variable-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/github-actions/refs/heads/main/json-schema/github-actions-cache-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/github-actions/refs/heads/main/json-schema/github-actions-simple-user-schema.json

Other Resources

🔗
Overlay
https://raw.githubusercontent.com/api-evangelist/github-actions/refs/heads/main/overlays/github-actions-self-hosted-runners-api-overlay.yaml
🔗
ChangeLog
https://github.blog/changelog/label/actions/
🔗
SDKs
https://github.com/octokit/octokit.js
🔗
SDKs
https://github.com/octokit/octokit.rb
🔗
SDKs
https://github.com/octokit/octokit.net
🔗
SDKs
https://github.com/google/go-github
🔗
CLI
https://cli.github.com/manual/gh_workflow_run
🔗
JSONLD
https://raw.githubusercontent.com/api-evangelist/github-actions/refs/heads/main/json-ld/github-actions-context.jsonld

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/github-actions:github-actions-self-hosted-runners-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

github-actions-self-hosted-runners-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: GitHub Actions Self-Hosted Runners API
  description: REST API for managing GitHub Actions workflows, runs, artifacts, secrets, runners, caches, variables, permissions, and OIDC.
  version: 1.0.0
  contact:
    name: GitHub Support
    url: https://support.github.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
- url: https://api.github.com
  description: GitHub REST API
security:
- bearerAuth: []
- personalAccessToken: []
tags:
- name: Self-Hosted Runners
  description: Manage self-hosted runners for workflows
paths:
  /repos/{owner}/{repo}/actions/runners:
    get:
      operationId: listSelfHostedRunnersForRepo
      summary: Github Actions List Self-hosted Runners for a Repository
      description: Lists all self-hosted runners configured in a repository.
      tags:
      - Self-Hosted Runners
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - name: name
        in: query
        schema:
          type: string
        example: Example Title
      - $ref: '#/components/parameters/perPage'
      - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: Successfully retrieved runners
          content:
            application/json:
              schema:
                type: object
                properties:
                  total_count:
                    type: integer
                  runners:
                    type: array
                    items:
                      $ref: '#/components/schemas/SelfHostedRunner'
              examples:
                Listselfhostedrunnersforrepo200Example:
                  summary: Default listSelfHostedRunnersForRepo 200 response
                  x-microcks-default: true
                  value:
                    total_count: 10
                    runners:
                    - id: abc123
                      name: Example Title
                      os: example_value
                      status: example_value
                      busy: true
                      labels:
                      - {}
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /repos/{owner}/{repo}/actions/runners/{runner_id}:
    get:
      operationId: getSelfHostedRunnerForRepo
      summary: Github Actions Get a Self-hosted Runner for a Repository
      description: Gets a specific self-hosted runner configured in a repository.
      tags:
      - Self-Hosted Runners
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - $ref: '#/components/parameters/runnerId'
      responses:
        '200':
          description: Successfully retrieved runner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SelfHostedRunner'
              examples:
                Getselfhostedrunnerforrepo200Example:
                  summary: Default getSelfHostedRunnerForRepo 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    name: Example Title
                    os: example_value
                    status: example_value
                    busy: true
                    labels:
                    - id: abc123
                      name: Example Title
                      type: read-only
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteSelfHostedRunnerFromRepo
      summary: Github Actions Delete a Self-hosted Runner From a Repository
      description: Forces the removal of a self-hosted runner from a repository.
      tags:
      - Self-Hosted Runners
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - $ref: '#/components/parameters/runnerId'
      responses:
        '204':
          description: Successfully deleted runner
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /repos/{owner}/{repo}/actions/runners/downloads:
    get:
      operationId: listRunnerApplicationsForRepo
      summary: Github Actions List Runner Applications for a Repository
      description: Lists binaries for the runner application that you can download.
      tags:
      - Self-Hosted Runners
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      responses:
        '200':
          description: Successfully retrieved runner applications
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RunnerApplication'
              examples:
                Listrunnerapplicationsforrepo200Example:
                  summary: Default listRunnerApplicationsForRepo 200 response
                  x-microcks-default: true
                  value:
                  - os: example_value
                    architecture: example_value
                    download_url: https://www.example.com
                    filename: example_value
                    temp_download_token: example_value
                    sha256_checksum: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /repos/{owner}/{repo}/actions/runners/registration-token:
    post:
      operationId: createRegistrationTokenForRepo
      summary: Github Actions Create a Registration Token for a Repository
      description: Returns a token that you can pass to the config script for a self-hosted runner.
      tags:
      - Self-Hosted Runners
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      responses:
        '201':
          description: Successfully created registration token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationToken'
              examples:
                Createregistrationtokenforrepo201Example:
                  summary: Default createRegistrationTokenForRepo 201 response
                  x-microcks-default: true
                  value:
                    token: example_value
                    expires_at: '2026-01-15T10:30:00Z'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /repos/{owner}/{repo}/actions/runners/remove-token:
    post:
      operationId: createRemoveTokenForRepo
      summary: Github Actions Create a Remove Token for a Repository
      description: Returns a token that you can pass to remove a self-hosted runner from a repository.
      tags:
      - Self-Hosted Runners
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      responses:
        '201':
          description: Successfully created remove token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationToken'
              examples:
                Createremovetokenforrepo201Example:
                  summary: Default createRemoveTokenForRepo 201 response
                  x-microcks-default: true
                  value:
                    token: example_value
                    expires_at: '2026-01-15T10:30:00Z'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /repos/{owner}/{repo}/actions/runners/{runner_id}/labels:
    get:
      operationId: listLabelsForSelfHostedRunnerForRepo
      summary: Github Actions List Labels for a Self-hosted Runner for a Repository
      description: Lists all labels for a self-hosted runner configured in a repository.
      tags:
      - Self-Hosted Runners
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - $ref: '#/components/parameters/runnerId'
      responses:
        '200':
          description: Successfully retrieved labels
          content:
            application/json:
              schema:
                type: object
                properties:
                  total_count:
                    type: integer
                  labels:
                    type: array
                    items:
                      $ref: '#/components/schemas/RunnerLabel'
              examples:
                Listlabelsforselfhostedrunnerforrepo200Example:
                  summary: Default listLabelsForSelfHostedRunnerForRepo 200 response
                  x-microcks-default: true
                  value:
                    total_count: 10
                    labels:
                    - id: abc123
                      name: Example Title
                      type: read-only
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: addCustomLabelsToSelfHostedRunnerForRepo
      summary: Github Actions Add Custom Labels to a Self-hosted Runner for a Repository
      description: Adds custom labels to a self-hosted runner configured in a repository.
      tags:
      - Self-Hosted Runners
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - $ref: '#/components/parameters/runnerId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - labels
              properties:
                labels:
                  type: array
                  items:
                    type: string
                  minItems: 1
                  maxItems: 100
            examples:
              AddcustomlabelstoselfhostedrunnerforrepoRequestExample:
                summary: Default addCustomLabelsToSelfHostedRunnerForRepo request
                x-microcks-default: true
                value:
                  labels:
                  - example_value
      responses:
        '200':
          description: Successfully added labels
          content:
            application/json:
              schema:
                type: object
                properties:
                  total_count:
                    type: integer
                  labels:
                    type: array
                    items:
                      $ref: '#/components/schemas/RunnerLabel'
              examples:
                Addcustomlabelstoselfhostedrunnerforrepo200Example:
                  summary: Default addCustomLabelsToSelfHostedRunnerForRepo 200 response
                  x-microcks-default: true
                  value:
                    total_count: 10
                    labels:
                    - id: abc123
                      name: Example Title
                      type: read-only
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: setCustomLabelsForSelfHostedRunnerForRepo
      summary: Github Actions Set Custom Labels for a Self-hosted Runner for a Repository
      description: Remove all previous custom labels and set the new custom labels for a specific self-hosted runner.
      tags:
      - Self-Hosted Runners
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - $ref: '#/components/parameters/runnerId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - labels
              properties:
                labels:
                  type: array
                  items:
                    type: string
                  maxItems: 100
            examples:
              SetcustomlabelsforselfhostedrunnerforrepoRequestExample:
                summary: Default setCustomLabelsForSelfHostedRunnerForRepo request
                x-microcks-default: true
                value:
                  labels:
                  - example_value
      responses:
        '200':
          description: Successfully set labels
          content:
            application/json:
              schema:
                type: object
                properties:
                  total_count:
                    type: integer
                  labels:
                    type: array
                    items:
                      $ref: '#/components/schemas/RunnerLabel'
              examples:
                Setcustomlabelsforselfhostedrunnerforrepo200Example:
                  summary: Default setCustomLabelsForSelfHostedRunnerForRepo 200 response
                  x-microcks-default: true
                  value:
                    total_count: 10
                    labels:
                    - id: abc123
                      name: Example Title
                      type: read-only
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: removeAllCustomLabelsFromSelfHostedRunnerForRepo
      summary: Github Actions Remove All Custom Labels From a Self-hosted Runner for a…
      description: Remove all custom labels from a self-hosted runner configured in a repository.
      tags:
      - Self-Hosted Runners
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - $ref: '#/components/parameters/runnerId'
      responses:
        '200':
          description: Successfully removed all custom labels
          content:
            application/json:
              schema:
                type: object
                properties:
                  total_count:
                    type: integer
                  labels:
                    type: array
                    items:
                      $ref: '#/components/schemas/RunnerLabel'
              examples:
                Removeallcustomlabelsfromselfhostedrunnerforrepo200Example:
                  summary: Default removeAllCustomLabelsFromSelfHostedRunnerForRepo 200 response
                  x-microcks-default: true
                  value:
                    total_count: 10
                    labels:
                    - id: abc123
                      name: Example Title
                      type: read-only
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /repos/{owner}/{repo}/actions/runners/{runner_id}/labels/{name}:
    delete:
      operationId: removeCustomLabelFromSelfHostedRunnerForRepo
      summary: Github Actions Remove a Custom Label From a Self-hosted Runner for a Repository
      description: Remove a custom label from a self-hosted runner configured in a repository.
      tags:
      - Self-Hosted Runners
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - $ref: '#/components/parameters/runnerId'
      - name: name
        in: path
        required: true
        schema:
          type: string
        example: Example Title
      responses:
        '200':
          description: Successfully removed label
          content:
            application/json:
              schema:
                type: object
                properties:
                  total_count:
                    type: integer
                  labels:
                    type: array
                    items:
                      $ref: '#/components/schemas/RunnerLabel'
              examples:
                Removecustomlabelfromselfhostedrunnerforrepo200Example:
                  summary: Default removeCustomLabelFromSelfHostedRunnerForRepo 200 response
                  x-microcks-default: true
                  value:
                    total_count: 10
                    labels:
                    - id: abc123
                      name: Example Title
                      type: read-only
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    RunnerApplication:
      type: object
      properties:
        os:
          type: string
          example: example_value
        architecture:
          type: string
          example: example_value
        download_url:
          type: string
          format: uri
          example: https://www.example.com
        filename:
          type: string
          example: example_value
        temp_download_token:
          type: string
          example: example_value
        sha256_checksum:
          type: string
          example: example_value
    AuthenticationToken:
      type: object
      properties:
        token:
          type: string
          example: example_value
        expires_at:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
    SelfHostedRunner:
      type: object
      properties:
        id:
          type: integer
          description: The id of the runner.
          example: abc123
        name:
          type: string
          description: The name of the runner.
          example: Example Title
        os:
          type: string
          description: The operating system of the runner.
          example: example_value
        status:
          type: string
          description: The status of the runner.
          example: example_value
        busy:
          type: boolean
          example: true
        labels:
          type: array
          items:
            $ref: '#/components/schemas/RunnerLabel'
          example: []
    RunnerLabel:
      type: object
      properties:
        id:
          type: integer
          example: abc123
        name:
          type: string
          example: Example Title
        type:
          type: string
          enum:
          - read-only
          - custom
          example: read-only
  parameters:
    repo:
      name: repo
      in: path
      required: true
      schema:
        type: string
      description: The name of the repository without the .git extension.
    page:
      name: page
      in: query
      schema:
        type: integer
        default: 1
      description: The page number of the results to fetch.
    runnerId:
      name: runner_id
      in: path
      required: true
      schema:
        type: integer
      description: Unique identifier of the self-hosted runner.
    perPage:
      name: per_page
      in: query
      schema:
        type: integer
        default: 30
        maximum: 100
      description: The number of results per page (max 100).
    owner:
      name: owner
      in: path
      required: true
      schema:
        type: string
      description: The account owner of the repository.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: GitHub personal access token or OAuth token
    personalAccessToken:
      type: http
      scheme: bearer
      description: Fine-grained personal access token with Actions permissions