GitLab CI/CD runners API

openapi: 3.2.0
info:
  title: GitLab access_requests Runners API
  version: v4
  description: Operations related to access requests
servers:
- url: https://gitlab.com
tags:
- name: runners
  description: Operations about runners
paths:
  /api/v4/groups/{id}/runners:
    get:
      summary: List group's runners
      description: List all runners available in the group as well as its ancestor groups, including any allowed shared runners.
      parameters:
      - in: path
        name: id
        description: The ID of a group
        required: true
        schema:
          type: string
      - in: query
        name: type
        description: The type of runners to return
        required: false
        schema:
          type: string
          enum:
          - instance_type
          - group_type
          - project_type
      - in: query
        name: paused
        description: Whether to include only runners that are accepting or ignoring new jobs
        required: false
        schema:
          type: boolean
      - in: query
        name: status
        description: The status of runners to return
        required: false
        schema:
          type: string
          enum:
          - active
          - paused
          - online
          - offline
          - never_contacted
          - stale
      - in: query
        name: tag_list
        description: A list of runner tags
        required: false
        example: '[''macos'', ''shell'']'
        schema:
          type: array
          items:
            type: string
      - in: query
        name: version_prefix
        description: The version prefix of runners to return
        required: false
        example: '''15.1.'' or ''16.'''
        schema:
          type: string
      - in: query
        name: page
        description: Current page number
        required: false
        example: 1
        schema:
          type: integer
          format: int32
          default: 1
      - in: query
        name: per_page
        description: Number of items per page
        required: false
        example: 20
        schema:
          type: integer
          format: int32
          default: 20
      responses:
        '200':
          description: Get runners available for group
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Entities_Ci_Runner'
        '400':
          description: Scope contains invalid value
        '403':
          description: Forbidden
      tags:
      - runners
      operationId: getApiV4GroupsIdRunners
  /api/v4/groups/{id}/runners/reset_registration_token:
    post:
      summary: Reset the runner registration token for a group
      description: Reset runner registration token
      parameters:
      - in: path
        name: id
        description: The ID of a group
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Reset runner registration token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Entities_Ci_ResetTokenResult'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Group Not Found
      tags:
      - runners
      operationId: postApiV4GroupsIdRunnersResetRegistrationToken
  /api/v4/projects/{id}/runners:
    get:
      summary: List project's runners
      description: List all runners available in the project, including from ancestor groups and any allowed shared runners.
      parameters:
      - in: path
        name: id
        description: The ID or URL-encoded path of the project owned by the authenticated user
        required: true
        schema:
          type: string
      - in: query
        name: scope
        description: 'Deprecated: Use `type` or `status` instead. The scope of runners to return'
        required: false
        schema:
          type: string
          enum:
          - specific
          - shared
          - instance_type
          - group_type
          - project_type
          - active
          - paused
          - online
          - offline
          - never_contacted
          - stale
      - in: query
        name: type
        description: The type of runners to return
        required: false
        schema:
          type: string
          enum:
          - instance_type
          - group_type
          - project_type
      - in: query
        name: paused
        description: Whether to include only runners that are accepting or ignoring new jobs
        required: false
        schema:
          type: boolean
      - in: query
        name: status
        description: The status of runners to return
        required: false
        schema:
          type: string
          enum:
          - active
          - paused
          - online
          - offline
          - never_contacted
          - stale
      - in: query
        name: tag_list
        description: A list of runner tags
        required: false
        example: '[''macos'', ''shell'']'
        schema:
          type: array
          items:
            type: string
      - in: query
        name: version_prefix
        description: The version prefix of runners to return
        required: false
        example: '''15.1.'' or ''16.'''
        schema:
          type: string
      - in: query
        name: page
        description: Current page number
        required: false
        example: 1
        schema:
          type: integer
          format: int32
          default: 1
      - in: query
        name: per_page
        description: Number of items per page
        required: false
        example: 20
        schema:
          type: integer
          format: int32
          default: 20
      responses:
        '200':
          description: Get runners available for project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Entities_Ci_Runner'
        '400':
          description: Scope contains invalid value
        '403':
          description: No access granted
      tags:
      - runners
      operationId: getApiV4ProjectsIdRunners
    post:
      summary: Assign a runner to project
      description: Assign an available project runner to the project.
      parameters:
      - in: path
        name: id
        description: The ID or URL-encoded path of the project owned by the authenticated user
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Assign a runner to project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Entities_Ci_Runner'
        '400':
          description: Bad Request
        '403':
          description: No access granted
        '404':
          description: Runner not found
      tags:
      - runners
      operationId: postApiV4ProjectsIdRunners
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postApiV4ProjectsIdRunners'
        required: true
  /api/v4/projects/{id}/runners/{runner_id}:
    delete:
      summary: Unassign a project runner from the project
      description: It is not possible to unassign a runner from the owner project. If so, an error is returned. Use the call to delete a runner instead.
      parameters:
      - in: path
        name: id
        description: The ID or URL-encoded path of the project owned by the authenticated user
        required: true
        schema:
          type: string
      - in: path
        name: runner_id
        description: The ID of a runner
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '400':
          description: Bad Request
        '204':
          description: Unassign a runner from project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Entities_Ci_Runner'
        '403':
          description: You cannot unassign a runner from the owner project. Delete the runner instead
        '404':
          description: Runner not found
        '412':
          description: Precondition Failed
      tags:
      - runners
      operationId: deleteApiV4ProjectsIdRunnersRunnerId
  /api/v4/projects/{id}/runners/reset_registration_token:
    post:
      summary: Reset the runner registration token for a project
      description: Reset runner registration token
      parameters:
      - in: path
        name: id
        description: The ID of a project
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Reset runner registration token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Entities_Ci_ResetTokenResult'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Project Not Found
      tags:
      - runners
      operationId: postApiV4ProjectsIdRunnersResetRegistrationToken
  /api/v4/runners:
    get:
      summary: List available runners
      description: Get runners available for user
      parameters:
      - in: query
        name: scope
        description: 'Deprecated: Use `type` or `status` instead. The scope of runners to return'
        required: false
        schema:
          type: string
          enum:
          - specific
          - shared
          - instance_type
          - group_type
          - project_type
          - active
          - paused
          - online
          - offline
          - never_contacted
          - stale
      - in: query
        name: type
        description: The type of runners to return
        required: false
        schema:
          type: string
          enum:
          - instance_type
          - group_type
          - project_type
      - in: query
        name: paused
        description: Whether to include only runners that are accepting or ignoring new jobs
        required: false
        schema:
          type: boolean
      - in: query
        name: status
        description: The status of runners to return
        required: false
        schema:
          type: string
          enum:
          - active
          - paused
          - online
          - offline
          - never_contacted
          - stale
      - in: query
        name: tag_list
        description: A list of runner tags
        required: false
        example: '[''macos'', ''shell'']'
        schema:
          type: array
          items:
            type: string
      - in: query
        name: version_prefix
        description: The version prefix of runners to return
        required: false
        example: '''15.1.'' or ''16.'''
        schema:
          type: string
      - in: query
        name: page
        description: Current page number
        required: false
        example: 1
        schema:
          type: integer
          format: int32
          default: 1
      - in: query
        name: per_page
        description: Number of items per page
        required: false
        example: 20
        schema:
          type: integer
          format: int32
          default: 20
      responses:
        '200':
          description: Get runners available for user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Entities_Ci_Runner'
        '400':
          description: Scope contains invalid value
        '401':
          description: Unauthorized
      tags:
      - runners
      operationId: getApiV4Runners
  /api/v4/runners/all:
    get:
      summary: List all runners
      description: Get a list of all runners in the GitLab instance (shared and project). Access is restricted to users with either administrator access or auditor access.
      parameters:
      - in: query
        name: scope
        description: 'Deprecated: Use `type` or `status` instead. The scope of runners to return'
        required: false
        schema:
          type: string
          enum:
          - specific
          - shared
          - instance_type
          - group_type
          - project_type
          - active
          - paused
          - online
          - offline
          - never_contacted
          - stale
      - in: query
        name: type
        description: The type of runners to return
        required: false
        schema:
          type: string
          enum:
          - instance_type
          - group_type
          - project_type
      - in: query
        name: paused
        description: Whether to include only runners that are accepting or ignoring new jobs
        required: false
        schema:
          type: boolean
      - in: query
        name: status
        description: The status of runners to return
        required: false
        schema:
          type: string
          enum:
          - active
          - paused
          - online
          - offline
          - never_contacted
          - stale
      - in: query
        name: tag_list
        description: A list of runner tags
        required: false
        example: '[''macos'', ''shell'']'
        schema:
          type: array
          items:
            type: string
      - in: query
        name: version_prefix
        description: The version prefix of runners to return
        required: false
        example: '''15.1.'' or ''16.'''
        schema:
          type: string
      - in: query
        name: page
        description: Current page number
        required: false
        example: 1
        schema:
          type: integer
          format: int32
          default: 1
      - in: query
        name: per_page
        description: Number of items per page
        required: false
        example: 20
        schema:
          type: integer
          format: int32
          default: 20
      responses:
        '200':
          description: Get all runners - shared and project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Entities_Ci_Runner'
        '400':
          description: Scope contains invalid value
        '401':
          description: Unauthorized
      tags:
      - runners
      operationId: getApiV4RunnersAll
  /api/v4/runners/{id}:
    get:
      summary: Get runner's details
      description: At least the Maintainer role is required to get runner details at the project and group level. Instance-level runner details via this endpoint are available to all signed in users.
      parameters:
      - in: path
        name: id
        description: The ID of a runner
        required: true
        schema:
          type: integer
          format: int32
      - in: query
        name: include_projects
        description: Include projects in the response. Set to false to improve performance for runners with many projects.
        required: false
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: Get runner's details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Entities_Ci_RunnerDetails'
        '401':
          description: Unauthorized
        '403':
          description: No access granted
        '404':
          description: Runner not found
      tags:
      - runners
      operationId: getApiV4RunnersId
    put:
      summary: Update details of a runner
      description: Update runner's details
      parameters:
      - in: path
        name: id
        description: The ID of a runner
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Update runner's details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Entities_Ci_RunnerDetails'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: No access granted
        '404':
          description: Runner not found
      tags:
      - runners
      operationId: putApiV4RunnersId
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/putApiV4RunnersId'
        required: true
    delete:
      summary: Delete a runner
      description: Remove a runner
      parameters:
      - in: path
        name: id
        description: The ID of a runner
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '401':
          description: Unauthorized
        '204':
          description: Remove a runner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Entities_Ci_Runner'
        '403':
          description: No access granted
        '404':
          description: Runner not found
        '412':
          description: Precondition Failed
      tags:
      - runners
      operationId: deleteApiV4RunnersId
  /api/v4/runners/{id}/managers:
    get:
      description: Get a list of all runner's managers
      parameters:
      - in: path
        name: id
        description: The ID of a runner
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Get a list of all runner's managers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Entities_Ci_RunnerManager'
        '403':
          description: Forbidden
      tags:
      - runners
      operationId: getApiV4RunnersIdManagers
  /api/v4/runners/{id}/projects:
    get:
      summary: List runner's projects
      description: Get a paginated list of all projects associated with the specified runner. Access is restricted based on user permissions.
      parameters:
      - in: path
        name: id
        description: The ID of a runner
        required: true
        schema:
          type: integer
          format: int32
      - in: query
        name: page
        description: Current page number
        required: false
        example: 1
        schema:
          type: integer
          format: int32
          default: 1
      - in: query
        name: per_page
        description: Number of items per page
        required: false
        example: 20
        schema:
          type: integer
          format: int32
          default: 20
      responses:
        '200':
          description: Get projects associated with a runner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Entities_BasicProjectDetails'
        '401':
          description: Unauthorized
        '403':
          description: No access granted
        '404':
          description: Runner not found
      tags:
      - runners
      operationId: getApiV4RunnersIdProjects
  /api/v4/runners/{id}/jobs:
    get:
      summary: List runner's jobs
      description: List jobs that are being processed or were processed by the specified runner. The list of jobs is limited to projects where the user has at least the Reporter role.
      parameters:
      - in: path
        name: id
        description: The ID of a runner
        required: true
        schema:
          type: integer
          format: int32
      - in: query
        name: system_id
        description: System ID associated with the runner manager
        required: false
        schema:
          type: string
      - in: query
        name: status
        description: Status of the job
        required: false
        schema:
          type: string
          enum:
          - created
          - waiting_for_resource
          - preparing
          - waiting_for_callback
          - pending
          - running
          - success
          - failed
          - canceling
          - canceled
          - skipped
          - manual
          - scheduled
      - in: query
        name: order_by
        description: Order by `id`
        required: false
        schema:
          type: string
          enum:
          - id
      - in: query
        name: sort
        description: Sort by `asc` or `desc` order. Specify `order_by` as well, including for `id`
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      - in: query
        name: cursor
        description: Cursor for obtaining the next set of records
        required: false
        schema:
          type: string
      - in: query
        name: page
        description: Current page number
        required: false
        example: 1
        schema:
          type: integer
          format: int32
          default: 1
      - in: query
        name: per_page
        description: Number of items per page
        required: false
        example: 20
        schema:
          type: integer
          format: int32
          default: 20
      responses:
        '200':
          description: List jobs running on a runner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Entities_Ci_JobBasicWithProject'
        '401':
          description: Unauthorized
        '403':
          description: No access granted
        '404':
          description: Runner not found
      tags:
      - runners
      operationId: getApiV4RunnersIdJobs
  /api/v4/runners/{id}/reset_authentication_token:
    post:
      summary: Reset runner's authentication token
      description: Reset runner authentication token
      parameters:
      - in: path
        name: id
        description: The ID of the runner
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '201':
          description: Reset runner authentication token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Entities_Ci_ResetTokenResult'
        '403':
          description: No access granted
        '404':
          description: Runner not found
        '422':
          description: Unprocessable Entity
      tags:
      - runners
      operationId: postApiV4RunnersIdResetAuthenticationToken
  /api/v4/runners/reset_registration_token:
    post:
      summary: Reset instance's runner registration token
      description: Reset runner registration token
      responses:
        '201':
          description: Reset runner registration token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Entities_Ci_ResetTokenResult'
        '403':
          description: Forbidden
      tags:
      - runners
      operationId: postApiV4RunnersResetRegistrationToken
  /api/v4/user/runners:
    post:
      summary: Create a runner owned by currently authenticated user
      description: Create a new runner
      responses:
        '201':
          description: Create a runner owned by currently authenticated user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Entities_Ci_RunnerRegistrationDetails'
        '400':
          description: Bad Request
        '403':
          description: Forbidden
      tags:
      - runners
      operationId: postApiV4UserRunners
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postApiV4UserRunners'
        required: true
components:
  schemas:
    API_Entities_BasicGroupDetails:
      type: object
      properties:
        id:
          type: integer
          format: int32
        web_url:
          type: string
          example: http://gitlab.example.com/groups/diaspora
        name:
          type: string
          example: Diaspora
      required:
      - id
      - web_url
      - name
      description: API_Entities_BasicGroupDetails model
    API_Entities_Ci_RunnerRegistrationDetails:
      type: object
      properties:
        id:
          type: string
        token:
          type: string
        token_expires_at:
          type: string
      required:
      - id
      - token
      - token_expires_at
      description: API_Entities_Ci_RunnerRegistrationDetails model
    API_Entities_Ci_JobBasicWithProject:
      type: object
      properties:
        id:
          type: integer
          format: int32
          example: 1
        status:
          type: string
          example: waiting_for_resource
        stage:
          type: string
          example: deploy
        name:
          type: string
          example: deploy_to_production
        ref:
          type: string
          example: main
        tag:
          type: boolean
        coverage:
          type: number
          format: float
          example: 98.29
        allow_failure:
          type: boolean
        created_at:
          type: string
          format: date-time
          example: '2015-12-24T15:51:21.880Z'
        started_at:
          type: string
          format: date-time
          example: '2015-12-24T17:54:30.733Z'
        finished_at:
          type: string
          format: date-time
          example: '2015-12-24T17:54:31.198Z'
        erased_at:
          type: string
          format: date-time
          example: '2015-12-24T18:00:29.728Z'
        duration:
          type: number
          format: float
          example: 0.465
          description: Time spent running
        queued_duration:
          type: number
          format: float
          example: 0.123
          description: Time spent enqueued
        user:
          $ref: '#/components/schemas/API_Entities_User'
        commit:
          $ref: '#/components/schemas/API_Entities_Commit'
        pipeline:
          $ref: '#/components/schemas/API_Entities_Ci_PipelineBasic'
        failure_reason:
          type: string
          example: script_failure
        web_url:
          type: string
          example: https://example.com/foo/bar/-/jobs/1
        project:
          $ref: '#/components/schemas/API_Entities_ProjectIdentity'
      required:
      - id
      - status
      - stage
      - name
      - ref
      - tag
      - coverage
      - allow_failure
      - created_at
      - started_at
      - finished_at
      - erased_at
      - duration
      - queued_duration
      - user
      - commit
      - pipeline
      - web_url
      - project
      description: API_Entities_Ci_JobBasicWithProject model
    postApiV4UserRunners:
      type: object
      properties:
        runner_type:
          type: string
          description: Specifies the scope of the runner
          enum:
          - instance_type
          - group_type
          - project_type
        group_id:
          type: integer
          format: int32
          description: The ID of the group that the runner is created in
          example: 1
        project_id:
          type: integer
          format: int32
          description: The ID of the project that the runner is created in
          example: 1
        description:
          type: string
          description: Description of the runner
        maintenance_note:
          type: string
          description: Free-form maintenance notes for the runner (1024 characters)
        paused:
          type: boolean
          description: Specifies if the runner should ignore new jobs (defaults to false)
        locked:
          type: boolean
          description: Specifies if the runner should be locked for the current project (defaults to false)
        access_level:
          type: string
          description: The access level of the runner
          enum:
          - not_protected
          - ref_protected
        run_untagged:
          type: boolean
          description: Specifies if the runner should handle untagged jobs  (defaults to true)
        tag_list:
          type: array
          description: A list of runner tags
          items:
            type: string
        maximum_timeout:
          type: integer
          format: int32
          description: Maximum timeout that limits the amount of time (in seconds) that runners can run jobs
        token_expires_at:
          type: string
          format: date-time
          description: The expiration time for the runner authentication token (ISO 8601 format). Must be between 5 minutes and 15 days in the future, and cannot exceed instance/group/project limits.
        token_rotation_deadline:
          type: string
          format: date-time
          description: The deadline for token rotation (ISO 8601 format). Must be specified with token_expires_at and be <= token_expires_at.
      required:
      - runner_type
      - group_id
      - project_id
      description: Create a runner owned by currently authenticated user
    putApiV4RunnersId:
      type: object
      properties:
        description:
          type: string
          description: The description of the runner
        active:
          type: boolean
          description: 'Deprecated: Use `paused` instead. Flag indicating whether the runner is allowed to receive jobs'
        paused:
          type: boolean
          description: Specifies if the runner should ignore new jobs
        tag_list:
          type: array
          description: The list of tags for a runner
          example: '[''macos'', ''shell'']'
          items:
            type: string
        run_untagged:
          type: boolean
          description: Specifies if the runner can execute untagged jobs
        locked:
          type: boolean
          description: Specifies if the runner is locked
        access_level:
          type: string
          description: The access level of the runner
          enum:
          - not_protected
          - ref_protected
        maximum_timeout:
          type: integer
          format: int32
          description: Maximum timeout that limits the amount of time (in seconds) that runners can run jobs
        maintenance_note:
          type: string
          description: Free-form maintenance notes for the runner (1024 characters)
      description: Update runner's details
    API_Entities_UserBasic:
      type: object
      properties:
        id:
          type: integer
          format: int32
          example: 1
        username:
          type: string
          example: admin
        public_email:
          type: string
          example: john@example.com
        name:
          type: string
          example: Administrator
        state:
          type: string
          example: active
        locked:
          type: boolean
        avatar_url:
          type: string
          example: https://gravatar.com/avatar/1
        avatar_path:
          type: string
          example: /user/avatar/28/The-Big-Lebowski-400-400.png
        custom_attributes:
          type: array
          items:
            $ref: '#/components/schemas/API_Entities_CustomAttribute'
        web_url:
          type: string
          example: https://gitlab.example.com/root
      required:
      - id
      - username
      - public_email
      - name
      - state
      - locked
      - avatar_url
      - web_url
      description: API_Entities_UserBasic model
    API_Entities_LicenseBasic:
      type: object
      properties:
        key:
          type: string
          example: gpl-3.0
        name:
          type: string
          example: GNU General Public License v3.0
        nickname:
          type: string
          example: GNU GPLv3
        html_url:
          type: string
          example: http://choosealicense.com/licenses/gpl-3.0
        source_url:
          type: string
      required:
      - key
      - name
      - nickname
      - html_url
      - source_url
    API_Entities_Ci_RunnerManager:
      type: object
      properties:
        id:
          type: integer
          format: int32
          example: 8
        system_id:
          type: string
          example: runner-1
        version:
          type: string
          example: 16.11.0
        revision:
          type: string
          example: 91a27

# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/gitlab-ci/refs/heads/main/openapi/gitlab-ci-runners-api-openapi.yml