히스토리

• GitLab 18.9에서 FF_USE_JOB_ROUTER 플래그와 함께 도입되었습니다. 이 기능은 실험 단계이며 GitLab 테스팅 계약이 적용됩니다.
• GitLab 18.10에서 connected 필드가 추가되었습니다.

러너 컨트롤러 API를 사용하면 CI/CD 작업 승인 제어를 위한 러너 컨트롤러를 관리할 수 있습니다. 러너 컨트롤러는 작업 라우터에 연결하여 커스텀 정책에 따라 작업을 평가하고, 승인 또는 거부 여부를 결정합니다. 이 API는 러너 컨트롤러를 생성, 조회, 업데이트, 삭제하는 엔드포인트를 제공합니다.

전제 조건:

• GitLab 인스턴스에 대한 관리자 액세스 권한이 있어야 합니다.

모든 러너 컨트롤러 목록 조회#

모든 러너 컨트롤러를 나열합니다.

GET /runner_controllers

응답:

성공하면 다음 응답 속성과 함께 200 OK를 반환합니다:

요청 예시:

curl --request GET \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/runner_controllers"

응답 예시:

[
    {
        "id": 1,
        "description": "Runner controller",
        "state": "enabled",
        "created_at": "2026-01-01T00:00:00Z",
        "updated_at": "2026-01-02T00:00:00Z"
    },
    {
        "id": 2,
        "description": "Another runner controller",
        "state": "disabled",
        "created_at": "2026-01-03T00:00:00Z",
        "updated_at": "2026-01-04T00:00:00Z"
    }
]

단일 러너 컨트롤러 조회#

ID로 특정 러너 컨트롤러의 세부 정보를 조회합니다.

GET /runner_controllers/:id

응답:

성공하면 다음 응답 속성과 함께 200 OK를 반환합니다:

요청 예시:

curl --request GET \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/runner_controllers/1"

응답 예시:

{
    "id": 1,
    "description": "Runner controller",
    "state": "enabled",
    "connected": true,
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-02T00:00:00Z"
}

러너 컨트롤러 등록#

새 러너 컨트롤러를 등록합니다.

POST /runner_controllers

지원되는 속성:

응답:

성공하면 다음 응답 속성과 함께 201 Created를 반환합니다:

요청 예시:

curl --request POST \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --data '{"description": "New runner controller", "state": "dry_run"}' \
     --url "https://gitlab.example.com/api/v4/runner_controllers"

응답 예시:

{
    "id": 3,
    "description": "New runner controller",
    "state": "dry_run",
    "created_at": "2026-01-05T00:00:00Z",
    "updated_at": "2026-01-05T00:00:00Z"
}

러너 컨트롤러 업데이트#

ID로 기존 러너 컨트롤러의 세부 정보를 업데이트합니다.

PUT /runner_controllers/:id

지원되는 속성:

성공하면 다음 응답 속성과 함께 200 OK를 반환합니다:

요청 예시:

curl --request PUT \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --data '{"description": "Updated runner controller", "state": "enabled"}' \
     --url "https://gitlab.example.com/api/v4/runner_controllers/3"

응답 예시:

{
    "id": 3,
    "description": "Updated runner controller",
    "state": "enabled",
    "created_at": "2026-01-05T00:00:00Z",
    "updated_at": "2026-01-06T00:00:00Z"
}

러너 컨트롤러 삭제#

ID로 특정 러너 컨트롤러를 삭제합니다.

DELETE /runner_controllers/:id

성공하면 204 No Content를 반환합니다.

curl --request DELETE \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/runner_controllers/3"

러너 컨트롤러 스코프#

러너 컨트롤러 스코프는 러너 컨트롤러가 승인 제어를 위해 평가하는 작업의 범위를 정의합니다. 러너 컨트롤러가 승인 요청을 받으려면 최소 하나의 스코프가 있어야 합니다. 스코프가 없으면 컨트롤러의 상태가 enabled 또는 dry_run이더라도 비활성 상태를 유지합니다.

러너 컨트롤러 스코프는 상호 배타적인 두 가지 스코프 유형을 지원합니다:

• 인스턴스 스코프: 러너 컨트롤러가 GitLab 인스턴스의 모든 러너에 대한 작업을 평가합니다.
• 러너 스코프: 러너 컨트롤러가 특정 인스턴스 러너에 대한 작업만 평가합니다.

러너 컨트롤러는 인스턴스 스코프 또는 하나 이상의 러너 스코프를 가질 수 있지만, 둘 다 가질 수는 없습니다.

러너 컨트롤러의 모든 스코프 목록 조회#

특정 러너 컨트롤러에 대해 구성된 모든 스코프를 나열합니다:

GET /runner_controllers/:id/scopes

지원되는 속성:

성공하면 200 OK와 다음 응답 속성을 반환합니다:

요청 예시:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/runner_controllers/1/scopes"

응답 예시:

{
    "instance_level_scopings": [
        {
            "created_at": "2026-01-01T00:00:00Z",
            "updated_at": "2026-01-01T00:00:00Z"
        }
    ],
    "runner_level_scopings": []
}

인스턴스 스코프 추가#

러너 컨트롤러에 인스턴스 스코프를 추가합니다. 추가되면 러너 컨트롤러가 GitLab 인스턴스의 모든 러너에 대한 작업을 평가합니다.

러너 컨트롤러는 인스턴스 스코프를 하나만 가질 수 있습니다. 이미 인스턴스 스코프가 존재하면 이 엔드포인트는 오류를 반환합니다.

POST /runner_controllers/:id/scopes/instance

지원되는 속성:

성공하면 201 Created와 다음 응답 속성을 반환합니다:

요청 예시:

curl --request POST \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/runner_controllers/1/scopes/instance"

응답 예시:

{
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z"
}

인스턴스 스코프 제거#

러너 컨트롤러에서 인스턴스 스코프를 제거합니다.

DELETE /runner_controllers/:id/scopes/instance

지원되는 속성:

성공하면 204 No Content를 반환합니다.

요청 예시:

curl --request DELETE \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/runner_controllers/1/scopes/instance"

러너 스코프 추가#

히스토리

• GitLab 18.10에서 도입되었습니다.

러너 컨트롤러에 러너 스코프를 추가합니다. 추가되면 러너 컨트롤러가 지정된 러너에 대한 작업만 평가합니다.

인스턴스 스코프가 있는 러너 컨트롤러는 러너 스코프를 가질 수 없습니다. 러너 스코프를 추가하기 전에 인스턴스 스코프를 제거하세요.

POST /runner_controllers/:id/scopes/runners/:runner_id

지원되는 속성:

성공하면 201 Created와 다음 응답 속성을 반환합니다:

요청 예시:

curl --request POST \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/runner_controllers/1/scopes/runners/5"

응답 예시:

{
    "runner_id": 5,
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z"
}

러너 스코프 제거#

히스토리

• GitLab 18.10에서 도입되었습니다.

러너 컨트롤러에서 러너 스코프를 제거합니다.

DELETE /runner_controllers/:id/scopes/runners/:runner_id

지원되는 속성:

성공하면 204 No Content를 반환합니다.

요청 예시:

curl --request DELETE \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/runner_controllers/1/scopes/runners/5"