Assign a runner to a project

POST

/api/v4/projects/{id}/runners

• GitLab REST API

Assigns an available project runner to a project.

Authorizations

• http
• oauth2

Parameters

Path Parameters

id

required

One of:

string

string

integer

integer

The ID or URL-encoded path of the project owned by the authenticated user

Request Body ^required

Media type application/json

object

runner_id

required

The ID of a runner

integer

nullable

Example ^generated

{
  "runner_id": 1
}

Responses

201

Created

Media type application/json

object

id

integer format: int64

description

string

ip_address

string

active

boolean

paused

boolean

is_shared

boolean

runner_type

string

name

string

online

boolean

created_by

object

id

integer format: int64

username

string

public_email

string

name

string

state

string

locked

boolean

avatar_url

string

avatar_path

string

custom_attributes

Array<object>

object

key

string

value

string

web_url

string

created_at

string format: date-time

status

string

job_execution_status

string

Example

{
  "id": 8,
  "description": "test-1-20150125",
  "ip_address": "127.0.0.1",
  "active": true,
  "paused": false,
  "is_shared": true,
  "runner_type": "instance_type",
  "name": "test",
  "online": true,
  "created_by": {
    "id": 1,
    "username": "admin",
    "public_email": "john@example.com",
    "name": "Administrator",
    "state": "active",
    "avatar_url": "https://gravatar.com/avatar/1",
    "avatar_path": "/user/avatar/28/The-Big-Lebowski-400-400.png",
    "custom_attributes": [
      {
        "key": "foo",
        "value": "bar"
      }
    ],
    "web_url": "https://gitlab.example.com/root"
  },
  "created_at": "2025-05-03T00:00:00.000Z",
  "status": "online",
  "job_execution_status": "idle"
}

400

Bad Request

403

Runner is locked

404

Runner not found