Skip to content

Runners

Runners: list the ones the user owns, every runner of the instance (an administrator’s), a group’s or a project’s; read, update (pausing included) and remove one; list its jobs and its managers; enable or disable it for a project; register one with a registration token, verify a runner authentication token, and delete a runner by its token; and reset the registration tokens of the instance, a group or a project, or a runner’s own authentication token.

Runner controllers, the experimental control plane administrators use to manage runners, are the actions served from Ultimate: controllers, their scopes and their tokens.

  • “List the runners available to project 42”
  • “Show the details of runner 5”
  • “Which jobs has runner 5 run today?”
  • “Pause the runner tagged gpu”
  • Dynamic, the default surface: call gitlab_execute_action with action set to the action’s ID, such as runner.controller_create, and its parameters in params. gitlab_find_action finds an ID from a description of the task.
  • Meta (GITLAB_MCP_TOOL_SURFACE=meta): call gitlab_runner with action set to the action’s name, such as controller_create, and its parameters in params.
  • Individual (GITLAB_MCP_TOOL_SURFACE=individual): call the action’s own tool, such as gitlab_runner_controller_create, with its parameters as the arguments.

How many of these actions an instance serves at each tier, out of a total of 36:

  • Free: 21
  • Premium: 21
  • Ultimate: 36

Read-only actions: 14 of 36, the ones a deployment in read-only mode keeps. A token with read_api and not api is served 17 of the 36.

The description of each action, and of each of its parameters, is the text the server serves for it on the default surface, quoted as served. The token lines say what GitLab 19.5.0 requires of a token for the requests each action sends; on an instance with Admin Mode turned on, an action only an administrator may run also needs admin_mode. A destructive action runs only once confirmed, unless GITLAB_MCP_YOLO_MODE (or AUTOPILOT) skips that step: the dynamic surface needs confirm: true on gitlab_execute_action, and the other two take a confirm parameter or the client’s prompt (Destructive actions).

Action Tier Individual
runner.controller_create Ultimate gitlab_runner_controller_create
runner.controller_delete Ultimate gitlab_runner_controller_delete
runner.controller_get Ultimate gitlab_runner_controller_get
runner.controller_list Ultimate gitlab_runner_controller_list
runner.controller_scope_add_instance Ultimate gitlab_runner_controller_scope_add_instance
runner.controller_scope_add_runner Ultimate gitlab_runner_controller_scope_add_runner
runner.controller_scope_list Ultimate gitlab_runner_controller_scope_list
runner.controller_scope_remove_instance Ultimate gitlab_runner_controller_scope_remove_instance
runner.controller_scope_remove_runner Ultimate gitlab_runner_controller_scope_remove_runner
runner.controller_token_create Ultimate gitlab_runner_controller_token_create
runner.controller_token_get Ultimate gitlab_runner_controller_token_get
runner.controller_token_list Ultimate gitlab_runner_controller_token_list
runner.controller_token_revoke Ultimate gitlab_runner_controller_token_revoke
runner.controller_token_rotate Ultimate gitlab_runner_controller_token_rotate
runner.controller_update Ultimate gitlab_runner_controller_update
runner.delete_by_token Free gitlab_runner_delete_by_token
runner.delete_registered Free gitlab_runner_delete_registered
runner.disable_project Free gitlab_runner_disable_project
runner.enable_project Free gitlab_runner_enable_project
runner.get Free gitlab_runner_get
runner.jobs Free gitlab_runner_jobs
runner.list Free gitlab_runner_list
runner.list_all Free gitlab_runner_list_all
runner.list_group Free gitlab_runner_list_group
runner.list_managers Free gitlab_runner_list_managers
runner.list_project Free gitlab_runner_list_project
runner.register Free gitlab_runner_register
runner.remove Free gitlab_runner_remove
runner.reset_group_reg_token Free gitlab_runner_reset_group_reg_token
runner.reset_instance_reg_token Free gitlab_runner_reset_instance_reg_token
runner.reset_project_reg_token Free gitlab_runner_reset_project_reg_token
runner.reset_token Free gitlab_runner_reset_token
runner.reset_token_by_token Free gitlab_runner_reset_token_by_token
runner.router_discovery Free gitlab_runner_router_discovery
runner.update Free gitlab_runner_update
runner.verify Free gitlab_runner_verify

Register a new runner controller (admin-only, experimental API) with optional description and state (enabled/disabled/dry_run). Returns: the created controller with id, description, state, and timestamps. See also: runner.controller_get, runner.controller_update, runner.controller_list.

  • Meta-tool: gitlab_runner, action controller_create
  • Individual tool: gitlab_runner_controller_create
  • Tier: Ultimate
  • Classic or OAuth token: api
  • Fine-grained token: Runner Controller: Create at instance (permissions page)
  • Behavior: writes, not idempotent
Parameter Type Mandatory Description
description string no Description of the runner controller
state string (disabled, enabled, dry_run) no State: enabled, disabled, or dry_run

Delete a runner controller by controller_id (destructive, admin-only, experimental API). Returns: a success confirmation. See also: runner.controller_list, runner.controller_get, runner.controller_update.

  • Meta-tool: gitlab_runner, action controller_delete
  • Individual tool: gitlab_runner_controller_delete
  • Tier: Ultimate
  • Classic or OAuth token: api
  • Fine-grained token: Runner Controller: Delete at instance (permissions page)
  • Behavior: writes, destructive (needs confirmation), idempotent
Parameter Type Mandatory Description
controller_id integer yes Runner controller ID

Get one runner controller by controller_id (admin-only, experimental API). Returns: the controller with id, description, state, connected flag, and created/updated timestamps. See also: runner.controller_list, runner.controller_update, runner.controller_delete.

  • Meta-tool: gitlab_runner, action controller_get
  • Individual tool: gitlab_runner_controller_get
  • Tier: Ultimate
  • Classic or OAuth token: read_api (or api)
  • Fine-grained token: Runner Controller: Read at instance (permissions page)
  • Behavior: read-only, idempotent
Parameter Type Mandatory Description
controller_id integer yes Runner controller ID

List registered runner controllers (admin-only, experimental API) with offset pagination. Returns: controllers with id, description, state, created/updated timestamps, plus pagination metadata. See also: runner.controller_get, runner.controller_create, runner.controller_update.

  • Meta-tool: gitlab_runner, action controller_list
  • Individual tool: gitlab_runner_controller_list
  • Tier: Ultimate
  • Classic or OAuth token: read_api (or api)
  • Fine-grained token: Runner Controller: Read at instance (permissions page)
  • Behavior: read-only, idempotent
Parameter Type Mandatory Description
order_by string no Column to order the result set by (e.g. id, created_at)
page integer no Page number to fetch, 1-based. Defaults to 1. Use the next_page field from the previous response to paginate forward.
per_page integer no Items per page. Defaults to 20, minimum 1, maximum 100. Use 100 to minimize round trips when the result set is large.
sort string (asc, desc) no Sort order: asc or desc

Grant a runner controller the instance-level scope (admin only). Returns: the created instance-level scoping with created/updated timestamps. See also: runner.controller_scope_remove_instance, runner.controller_scope_list, runner.controller_scope_add_runner.

  • Meta-tool: gitlab_runner, action controller_scope_add_instance
  • Individual tool: gitlab_runner_controller_scope_add_instance
  • Tier: Ultimate
  • Classic or OAuth token: api
  • Fine-grained token: Runner Controller: Update at instance (permissions page)
  • Behavior: writes, not idempotent
Parameter Type Mandatory Description
controller_id integer yes Runner controller ID

Scope a runner controller to a specific instance runner by runner ID (admin only). Returns: the created runner-level scoping with the runner ID and created/updated timestamps. See also: runner.controller_scope_remove_runner, runner.controller_scope_list, runner.controller_scope_add_instance.

  • Meta-tool: gitlab_runner, action controller_scope_add_runner
  • Individual tool: gitlab_runner_controller_scope_add_runner
  • Tier: Ultimate
  • Classic or OAuth token: api
  • Fine-grained token: Runner Controller: Update at instance (permissions page)
  • Behavior: writes, not idempotent
Parameter Type Mandatory Description
controller_id integer yes Runner controller ID
runner_id integer yes Instance-level runner ID to scope

List every scope assigned to a runner controller (admin only). Returns: instance-level scopings with timestamps and runner-level scopings with runner IDs and timestamps. See also: runner.controller_scope_add_instance, runner.controller_scope_add_runner, runner.controller_scope_remove_runner.

  • Meta-tool: gitlab_runner, action controller_scope_list
  • Individual tool: gitlab_runner_controller_scope_list
  • Tier: Ultimate
  • Classic or OAuth token: read_api (or api)
  • Fine-grained token: Runner Controller: Read at instance (permissions page)
  • Behavior: read-only, idempotent
Parameter Type Mandatory Description
controller_id integer yes Runner controller ID

Revoke a runner controller’s instance-level scope (admin only, destructive). Returns: a success confirmation naming the removed instance-level scope. See also: runner.controller_scope_add_instance, runner.controller_scope_list, runner.controller_scope_remove_runner.

  • Meta-tool: gitlab_runner, action controller_scope_remove_instance
  • Individual tool: gitlab_runner_controller_scope_remove_instance
  • Tier: Ultimate
  • Classic or OAuth token: api
  • Fine-grained token: Runner Controller: Update at instance (permissions page)
  • Behavior: writes, destructive (needs confirmation), idempotent
Parameter Type Mandatory Description
controller_id integer yes Runner controller ID

Remove a specific runner from a runner controller’s scope by runner ID (admin only, destructive). Returns: a success confirmation naming the removed runner scope. See also: runner.controller_scope_add_runner, runner.controller_scope_list, runner.controller_scope_remove_instance.

  • Meta-tool: gitlab_runner, action controller_scope_remove_runner
  • Individual tool: gitlab_runner_controller_scope_remove_runner
  • Tier: Ultimate
  • Classic or OAuth token: api
  • Fine-grained token: Runner Controller: Update at instance (permissions page)
  • Behavior: writes, destructive (needs confirmation), idempotent
Parameter Type Mandatory Description
controller_id integer yes Runner controller ID
runner_id integer yes Runner ID to remove from scope

Create a runner controller token (admin-only). Returns: the new token including its one-time secret value, id, runner controller id, and description. See also: runner.controller_token_list, runner.controller_token_rotate, runner.controller_token_revoke.

  • Meta-tool: gitlab_runner, action controller_token_create
  • Individual tool: gitlab_runner_controller_token_create
  • Tier: Ultimate
  • Classic or OAuth token: api
  • Fine-grained token: Runner Controller Token: Create at instance (permissions page)
  • Behavior: writes, not idempotent
Parameter Type Mandatory Description
controller_id integer yes Runner controller ID
description string no Description of the token

Get one runner controller token by id (admin-only). Returns: the token’s id, runner controller id, description, last-used time, and timestamps. See also: runner.controller_token_list, runner.controller_token_rotate, runner.controller_token_revoke.

  • Meta-tool: gitlab_runner, action controller_token_get
  • Individual tool: gitlab_runner_controller_token_get
  • Tier: Ultimate
  • Classic or OAuth token: read_api (or api)
  • Fine-grained token: Runner Controller Token: Read at instance (permissions page)
  • Behavior: read-only, idempotent
Parameter Type Mandatory Description
controller_id integer yes Runner controller ID
token_id integer yes Token ID

List runner controller tokens for a controller (admin-only). Returns: each token’s id, runner controller id, description, last-used time, and timestamps, with pagination metadata. See also: runner.controller_token_get, runner.controller_token_create, runner.controller_token_revoke.

  • Meta-tool: gitlab_runner, action controller_token_list
  • Individual tool: gitlab_runner_controller_token_list
  • Tier: Ultimate
  • Classic or OAuth token: read_api (or api)
  • Fine-grained token: Runner Controller Token: Read at instance (permissions page)
  • Behavior: read-only, idempotent
Parameter Type Mandatory Description
controller_id integer yes Runner controller ID
order_by string no Column to order the result set by (e.g. id, created_at)
page integer no Page number to fetch, 1-based. Defaults to 1. Use the next_page field from the previous response to paginate forward.
per_page integer no Items per page. Defaults to 20, minimum 1, maximum 100. Use 100 to minimize round trips when the result set is large.
sort string (asc, desc) no Sort order: asc or desc

Revoke a runner controller token permanently (admin-only). Returns: a success confirmation that the runner controller token was deleted. See also: runner.controller_token_list, runner.controller_token_get, runner.controller_token_rotate.

  • Meta-tool: gitlab_runner, action controller_token_revoke
  • Individual tool: gitlab_runner_controller_token_revoke
  • Tier: Ultimate
  • Classic or OAuth token: api
  • Fine-grained token: Runner Controller Token: Revoke at instance (permissions page)
  • Behavior: writes, destructive (needs confirmation), idempotent
Parameter Type Mandatory Description
controller_id integer yes Runner controller ID
token_id integer yes Token ID

Rotate a runner controller token (admin-only). Requires confirmation. Returns: the token with its newly issued one-time secret value and unchanged id. See also: runner.controller_token_get, runner.controller_token_list, runner.controller_token_revoke.

  • Meta-tool: gitlab_runner, action controller_token_rotate
  • Individual tool: gitlab_runner_controller_token_rotate
  • Tier: Ultimate
  • Classic or OAuth token: api
  • Fine-grained token: Runner Controller Token: Rotate at instance (permissions page)
  • Behavior: writes, destructive (needs confirmation), idempotent
Parameter Type Mandatory Description
controller_id integer yes Runner controller ID
token_id integer yes Token ID

Update a runner controller’s description or state (enabled/disabled/dry_run) by controller_id (admin-only, experimental API). Returns: the updated controller with id, description, state, and timestamps. See also: runner.controller_get, runner.controller_list, runner.controller_delete.

  • Meta-tool: gitlab_runner, action controller_update
  • Individual tool: gitlab_runner_controller_update
  • Tier: Ultimate
  • Classic or OAuth token: api
  • Fine-grained token: Runner Controller: Update at instance (permissions page)
  • Behavior: writes, idempotent
Parameter Type Mandatory Description
controller_id integer yes Runner controller ID
description string no New description. Pass an empty string to remove it. Omit the field to leave it untouched
state string (disabled, enabled, dry_run) no New state: enabled, disabled, or dry_run

Delete a registered runner by its authentication token. Returns: a success confirmation. See also: runner.delete_registered, runner.remove.

  • Meta-tool: gitlab_runner, action delete_by_token
  • Individual tool: gitlab_runner_delete_by_token
  • Tier: Free
  • Classic or OAuth token: read_api (or api); GitLab authenticates the token this action sends as a parameter and does not judge this one’s scope
  • Fine-grained token: a request GitLab does not judge by the grant (permissions page)
  • Behavior: writes, destructive (needs confirmation), idempotent
Parameter Type Mandatory Description
token string yes Runner authentication token

Delete a registered runner by its numeric runner_id. Returns: a success confirmation. See also: runner.delete_by_token, runner.remove.

  • Meta-tool: gitlab_runner, action delete_registered
  • Individual tool: gitlab_runner_delete_registered
  • Tier: Free
  • Classic or OAuth token: api
  • Fine-grained token: Runner: Delete at project or group or instance (permissions page)
  • Behavior: writes, destructive (needs confirmation), idempotent
Parameter Type Mandatory Description
runner_id integer yes Runner ID to delete

Remove a runner assignment from a project by project_id and runner_id. Returns: a success confirmation. See also: runner.enable_project, runner.list_project.

  • Meta-tool: gitlab_runner, action disable_project
  • Individual tool: gitlab_runner_disable_project
  • Tier: Free
  • Classic or OAuth token: api
  • Fine-grained token: Runner: Assign at project (permissions page)
  • Behavior: writes, destructive (needs confirmation), idempotent
Parameter Type Mandatory Description
project_id string/integer yes Project ID or URL-encoded path
runner_id integer yes Runner ID to remove from project

Assign an existing runner to a project by project_id and runner_id. Requires confirmation. Returns: the enabled runner. See also: runner.disable_project, runner.list_project.

  • Meta-tool: gitlab_runner, action enable_project
  • Individual tool: gitlab_runner_enable_project
  • Tier: Free
  • Classic or OAuth token: api
  • Fine-grained token: Runner: Assign at project (permissions page)
  • Behavior: writes, destructive (needs confirmation), not idempotent
Parameter Type Mandatory Description
project_id string/integer yes Project ID or URL-encoded path
runner_id integer yes Runner ID to assign

Get full configuration for one runner by numeric runner_id. Returns: runner details including tags, locked, access level, maximum timeout, contact time, and associated groups/projects. See also: runner.list, runner.update, runner.jobs.

  • Meta-tool: gitlab_runner, action get
  • Individual tool: gitlab_runner_get
  • Tier: Free
  • Classic or OAuth token: read_api (or api)
  • Fine-grained token: Runner: Read at project or group or instance (permissions page)
  • Behavior: read-only, idempotent
Parameter Type Mandatory Description
runner_id integer yes Runner ID

List jobs processed by a runner, with status/order/sort filters and pagination. Returns: jobs with id, name, status, stage, ref, and duration, plus pagination metadata. See also: runner.get, job.get.

  • Meta-tool: gitlab_runner, action jobs
  • Individual tool: gitlab_runner_jobs
  • Tier: Free
  • Classic or OAuth token: read_api (or api)
  • Fine-grained token: Runner: Read at project or group or instance (permissions page)
  • Behavior: read-only, idempotent
Parameter Type Mandatory Description
runner_id integer yes Runner ID
order_by string no Order by field: id (default)
page integer no Page number to fetch, 1-based. Defaults to 1. Use the next_page field from the previous response to paginate forward.
page_token string no Next page of a keyset listing: the next_page_token of the previous response of this action, passed back unchanged. It carries the position and every filter of the listing as GitLab read them, and those are what the next page is asked with, whatever filters are sent beside it. Leave it empty for the first page.
pagination string no Pagination method: ‘keyset’ for keyset-based pagination on large ordered result sets, or ‘offset’ (the default). Keyset avoids deep-offset cost, and a keyset page names the next one in next_page_token rather than next_page.
per_page integer no Items per page. Defaults to 20, minimum 1, maximum 100. Use 100 to minimize round trips when the result set is large.
sort string (asc, desc) no Sort direction: asc, desc
status string (created, waiting_for_resource, preparing, waiting_for_callback, pending, running, success, failed, canceling, canceled, skipped, manual, scheduled) no Job status filter: created, waiting_for_resource, preparing, waiting_for_callback, pending, running, success, failed, canceling, canceled, skipped, manual, or scheduled

List runners owned by the authenticated user, with type/status/tag/scope filters and pagination. Returns: runners with id, name, type, status, paused/shared/online flags, plus pagination metadata. See also: runner.get, runner.list_all, runner.list_project.

  • Meta-tool: gitlab_runner, action list
  • Individual tool: gitlab_runner_list
  • Tier: Free
  • Classic or OAuth token: read_api (or api)
  • Fine-grained token: Runner: Read at user (permissions page)
  • Behavior: read-only, idempotent
Parameter Type Mandatory Description
order_by string no Field to order results by, e.g. id
page integer no Page number to fetch, 1-based. Defaults to 1. Use the next_page field from the previous response to paginate forward.
paused boolean no Filter by paused state
per_page integer no Items per page. Defaults to 20, minimum 1, maximum 100. Use 100 to minimize round trips when the result set is large.
scope string (active, paused, online, offline) no Deprecated runner scope filter: active, paused, online, or offline. Prefer type and status instead
sort string (asc, desc) no Sort direction: asc or desc
status string (online, offline, stale, never_contacted) no Runner status filter: online, offline, stale, or never_contacted.
tag_list string[] no List of tags to filter by
type string (instance_type, group_type, project_type) no Runner type filter: instance_type (instance-level shared runners), group_type (group runners), or project_type (project-specific runners).

List every runner on the instance (admin token required), with type/status/tag/scope filters and pagination. Returns: runners with id, name, type, status, flags, plus pagination metadata. See also: runner.list, runner.get.

  • Meta-tool: gitlab_runner, action list_all
  • Individual tool: gitlab_runner_list_all
  • Tier: Free
  • Classic or OAuth token: read_api (or api)
  • Fine-grained token: Runner: Read at instance (permissions page)
  • Behavior: read-only, idempotent
Parameter Type Mandatory Description
order_by string no Field to order results by, e.g. id
page integer no Page number to fetch, 1-based. Defaults to 1. Use the next_page field from the previous response to paginate forward.
paused boolean no Filter by paused state
per_page integer no Items per page. Defaults to 20, minimum 1, maximum 100. Use 100 to minimize round trips when the result set is large.
scope string (specific, shared, active, paused, online, offline) no Deprecated runner scope filter: specific, shared, active, paused, online, or offline. Prefer type and status instead
sort string (asc, desc) no Sort direction: asc or desc
status string (online, offline, stale, never_contacted) no Runner status filter: online, offline, stale, or never_contacted.
tag_list string[] no List of tags to filter by
type string (instance_type, group_type, project_type) no Runner type filter: instance_type (instance-level shared runners), group_type (group runners), or project_type (project-specific runners).

List runners available in a group (specific and shared), with type/status/tag filters and pagination. Returns: runners with id, name, type, status, flags, plus pagination metadata. See also: runner.list, runner.list_project.

  • Meta-tool: gitlab_runner, action list_group
  • Individual tool: gitlab_runner_list_group
  • Tier: Free
  • Classic or OAuth token: read_api (or api)
  • Fine-grained token: Runner: Read at group (permissions page)
  • Behavior: read-only, idempotent
Parameter Type Mandatory Description
group_id string/integer yes Group ID or URL-encoded path
order_by string no Field to order results by, e.g. id
page integer no Page number to fetch, 1-based. Defaults to 1. Use the next_page field from the previous response to paginate forward.
per_page integer no Items per page. Defaults to 20, minimum 1, maximum 100. Use 100 to minimize round trips when the result set is large.
sort string (asc, desc) no Sort direction: asc or desc
status string (online, offline, stale, never_contacted) no Runner status filter: online, offline, stale, or never_contacted.
tag_list string[] no List of tags to filter by
type string (instance_type, group_type, project_type) no Runner type filter: instance_type (instance-level shared runners), group_type (group runners), or project_type (project-specific runners).

List the managers of a runner by runner_id. Returns: runner managers with system id, version, revision, platform, architecture, status, and IP. See also: runner.get, runner.list.

  • Meta-tool: gitlab_runner, action list_managers
  • Individual tool: gitlab_runner_list_managers
  • Tier: Free
  • Classic or OAuth token: read_api (or api)
  • Fine-grained token: Runner: Read at project or group or instance (permissions page)
  • Behavior: read-only, idempotent
Parameter Type Mandatory Description
runner_id integer yes Runner ID

List runners assigned to a project, with type/status/tag/scope filters and pagination. Returns: runners with id, name, type, status, flags, plus pagination metadata. See also: runner.enable_project, runner.disable_project, runner.list.

  • Meta-tool: gitlab_runner, action list_project
  • Individual tool: gitlab_runner_list_project
  • Tier: Free
  • Classic or OAuth token: read_api (or api)
  • Fine-grained token: Runner: Read at project (permissions page)
  • Behavior: read-only, idempotent
Parameter Type Mandatory Description
project_id string/integer yes Project ID or URL-encoded path
order_by string no Field to order results by, e.g. id
page integer no Page number to fetch, 1-based. Defaults to 1. Use the next_page field from the previous response to paginate forward.
paused boolean no Filter by paused state
per_page integer no Items per page. Defaults to 20, minimum 1, maximum 100. Use 100 to minimize round trips when the result set is large.
scope string (active, paused, online, offline) no Deprecated runner scope filter: active, paused, online, or offline. Prefer type and status instead
sort string (asc, desc) no Sort direction: asc or desc
status string (online, offline, stale, never_contacted) no Runner status filter: online, offline, stale, or never_contacted.
tag_list string[] no List of tags to filter by
type string (instance_type, group_type, project_type) no Runner type filter: instance_type (instance-level shared runners), group_type (group runners), or project_type (project-specific runners).

Register a new runner with a registration token, optional info hashmap, tags, and configuration. Returns: the created runner including its authentication token. See also: runner.verify, runner.list.

  • Meta-tool: gitlab_runner, action register
  • Individual tool: gitlab_runner_register
  • Tier: Free
  • Classic or OAuth token: read_api (or api); GitLab authenticates the token this action sends as a parameter and does not judge this one’s scope
  • Fine-grained token: a request GitLab does not judge by the grant (permissions page)
  • Behavior: writes, not idempotent
Parameter Type Mandatory Description
token string yes Registration token
access_level string no Access level: not_protected, ref_protected
active boolean no Deprecated: registration active state. Prefer paused instead
description string no Runner description
info object no Runner manager info hashmap (name, version, revision, platform, architecture)
locked boolean no Lock runner to current project
maintenance_note string no Maintenance note
maximum_timeout integer no Maximum job timeout in seconds
paused boolean no Register in paused state
run_untagged boolean no Whether to run untagged jobs
tag_list string[] no List of runner tags

Remove (unregister) a runner by numeric runner_id. Returns: a success confirmation. See also: runner.disable_project, runner.delete_registered, runner.get.

  • Meta-tool: gitlab_runner, action remove
  • Individual tool: gitlab_runner_remove
  • Tier: Free
  • Classic or OAuth token: api
  • Fine-grained token: Runner: Delete at project or group or instance (permissions page)
  • Behavior: writes, destructive (needs confirmation), idempotent
Parameter Type Mandatory Description
runner_id integer yes Runner ID to remove

Reset a group’s runner registration token by group_id (deprecated). Requires confirmation. Returns: the new registration token and its expiry. See also: runner.reset_instance_reg_token, runner.reset_project_reg_token.

  • Meta-tool: gitlab_runner, action reset_group_reg_token
  • Individual tool: gitlab_runner_reset_group_reg_token
  • Tier: Free
  • Classic or OAuth token: api
  • Fine-grained token: Runner Registration Token: Reset at group (permissions page)
  • Behavior: writes, destructive (needs confirmation), idempotent
Parameter Type Mandatory Description
group_id string/integer yes Group ID or URL-encoded path

Reset the instance-level runner registration token (deprecated, admin only). Requires confirmation. Returns: the new registration token and its expiry. See also: runner.reset_group_reg_token, runner.reset_project_reg_token.

  • Meta-tool: gitlab_runner, action reset_instance_reg_token
  • Individual tool: gitlab_runner_reset_instance_reg_token
  • Tier: Free
  • Classic or OAuth token: api
  • Fine-grained token: Runner Registration Token: Reset at instance (permissions page)
  • Behavior: writes, destructive (needs confirmation), idempotent

No parameters.

Reset a project’s runner registration token by project_id (deprecated). Requires confirmation. Returns: the new registration token and its expiry. See also: runner.reset_instance_reg_token, runner.reset_group_reg_token.

  • Meta-tool: gitlab_runner, action reset_project_reg_token
  • Individual tool: gitlab_runner_reset_project_reg_token
  • Tier: Free
  • Classic or OAuth token: api
  • Fine-grained token: Runner Registration Token: Reset at project (permissions page)
  • Behavior: writes, destructive (needs confirmation), idempotent
Parameter Type Mandatory Description
project_id string/integer yes Project ID or URL-encoded path

Reset a runner’s authentication token by runner_id. Requires confirmation. Returns: the new token and its expiry. See also: runner.verify, runner.get.

  • Meta-tool: gitlab_runner, action reset_token
  • Individual tool: gitlab_runner_reset_token
  • Tier: Free
  • Classic or OAuth token: api
  • Fine-grained token: Runner: Update at project or group or instance (permissions page)
  • Behavior: writes, destructive (needs confirmation), idempotent
Parameter Type Mandatory Description
runner_id integer yes Runner ID

Reset a runner’s authentication token with its current authentication token. Requires confirmation. Returns: the new token and its expiry. See also: runner.verify, runner.reset_token.

  • Meta-tool: gitlab_runner, action reset_token_by_token
  • Individual tool: gitlab_runner_reset_token_by_token
  • Tier: Free
  • Classic or OAuth token: read_api (or api); GitLab authenticates the token this action sends as a parameter and does not judge this one’s scope
  • Fine-grained token: a request GitLab does not judge by the grant (permissions page)
  • Behavior: writes, destructive (needs confirmation), idempotent
Parameter Type Mandatory Description
token string yes Current runner authentication token, which the reset invalidates

Discover the Job Router information for a runner by its authentication token (GitLab 18.7 or later, behind feature flags). Returns: the Job Router server URL. See also: runner.verify, runner.get.

  • Meta-tool: gitlab_runner, action router_discovery
  • Individual tool: gitlab_runner_router_discovery
  • Tier: Free
  • Classic or OAuth token: read_api (or api); GitLab authenticates the token this action sends as a parameter and does not judge this one’s scope
  • Fine-grained token: a request GitLab does not judge by the grant (permissions page)
  • Behavior: read-only, idempotent
Parameter Type Mandatory Description
token string yes Runner authentication token, sent as the Runner-Token header GitLab authenticates the runner by

Update a runner’s configuration (description, pause state, tags, locked, access level, timeout) by runner_id. Returns: the updated runner details. See also: runner.get, runner.remove.

  • Meta-tool: gitlab_runner, action update
  • Individual tool: gitlab_runner_update
  • Tier: Free
  • Classic or OAuth token: api
  • Fine-grained token: Runner: Update at project or group or instance (permissions page)
  • Behavior: writes, idempotent
Parameter Type Mandatory Description
runner_id integer yes Runner ID
access_level string no Access level: not_protected, ref_protected
active boolean no Deprecated: runner active state. Prefer paused instead
description string no Runner description. Pass an empty string to remove it. Omit the field to leave it untouched
locked boolean no Whether runner is locked to current project
maintenance_note string no Maintenance note for the runner. Pass an empty string to remove it. Omit the field to leave it untouched
maximum_timeout integer no Maximum job timeout in seconds
paused boolean no Pause/unpause the runner
run_untagged boolean no Whether to run untagged jobs
tag_list string[] no List of runner tags. Pass [] to remove every tag. Omit the field to leave them untouched

Verify that a runner authentication token is valid. Returns: a success confirmation when the token authenticates. See also: runner.register, runner.reset_token.

  • Meta-tool: gitlab_runner, action verify
  • Individual tool: gitlab_runner_verify
  • Tier: Free
  • Classic or OAuth token: read_api (or api); GitLab authenticates the token this action sends as a parameter and does not judge this one’s scope
  • Fine-grained token: a request GitLab does not judge by the grant (permissions page)
  • Behavior: read-only, idempotent
Parameter Type Mandatory Description
token string yes Runner authentication token to verify