러너 API

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

이 페이지는 인스턴스에 등록된 러너에 대한 엔드포인트를 설명합니다. 현재 사용자에 연결된 러너를 만들려면 러너 생성을 참조하세요.

페이지네이션은 다음 API 엔드포인트에서 사용할 수 있으며(기본적으로 20개 항목 반환):

GET /runners  
GET /runners/all  
GET /runners/:id/jobs  
GET /projects/:id/runners  
GET /groups/:id/runners

등록 및 인증 토큰

러너를 GitLab에 연결할 때 두 개의 토큰을 고려해야 합니다.

토큰 설명
등록 토큰 러너 등록에 사용되는 토큰입니다. GitLab을 통해 얻을 수 있습니다.
인증 토큰 러너를 GitLab 인스턴스에 인증하는 데 사용되는 토큰입니다. 이 토큰은 러너를 등록할 때 자동으로 얻거나, 수동으로 러너를 등록하거나 인증 토큰 재설정할 때 Runners API를 통해 얻습니다. POST /user/runners 엔드포인트를 사용하여 토큰을 얻을 수도 있습니다.

다음은 러너 등록 시 두 토큰이 사용되는 예입니다:

  1. 등록 토큰을 사용하여 GitLab API를 통해 러너를 등록하고, 인증 토큰이 반환됩니다.

  2. 이 인증 토큰을 사용하여
    러너의 구성 파일에 추가합니다:

    [[runners]]  
  token = "<authentication_token>"

그 후에 GitLab과 러너가 연결됩니다.

소유한 러너 목록

사용자가 사용할 수 있는 러너 목록을 가져옵니다.

사전 요구 조건:

  • 대상 네임스페이스 또는 프로젝트의 관리자 또는 소유자 역할이어야 합니다.
  • instance_type의 경우, GitLab 인스턴스의 관리자여야 합니다.
GET /runners  
GET /runners?scope=active  
GET /runners?type=project_type  
GET /runners?status=online  
GET /runners?paused=true  
GET /runners?tag_list=tag1,tag2
속성 유형 필수 여부 설명
scope 문자열 아니요 더 이상 사용되지 않습니다: 대신 type 또는 status를 사용하세요. 반환할 러너의 범위 중 하나: active, paused, online 및 offline; 제공하지 않을 경우 모든 러너를 보여줌
type 문자열 아니요 반환할 러너의 유형 중 하나: instance_type, group_type, project_type
status 문자열 아니요 반환할 러너의 상태 중 하나: online, offline, stale 또는 never_contacted.
다른 가능한 값은 더 이상 사용되지 않는 active 및 paused입니다.
offline 러너 요청 시 stale 러너도 반환될 수 있습니다. stale는 offline에 포함됩니다.
paused 부울 아니요 새 작업을 수락하거나 무시하고 있는 러너만 포함할지 여부
tag_list 문자열 배열 아니요 러너 태그 목록
version_prefix 문자열 아니요 반환할 러너의 버전 접두사입니다. 예: 15.0, 14, 16.1.241 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners"
note
status 쿼리 매개변수의 active 및 paused 값은 더 이상 사용되지 않으며
향후 버전의 REST API에서 제거될 예정입니다. paused 쿼리 매개변수로 대체됩니다.
note
응답의 active 속성은 더 이상 사용되지 않으며
향후 버전의 REST API에서 제거될 예정입니다. paused 속성으로 대체됩니다.
note
응답의 ip_address 속성은 GitLab 16.1에서 더 이상 사용되지 않으며
향후 버전의 REST API에서 제거될 예정입니다..
이 속성은 GitLab 17.0에서 빈 문자열을 반환하기 시작합니다. ipAddress 속성은 현재 GraphQL에서만 사용 가능한 해당 러너 관리자의 내부에 있습니다.
CiRunnerManager 타입.

예시 응답:

[  
    {  
        "active": true,  
        "paused": false,  
        "description": "test-1-20150125",  
        "id": 6,  
        "ip_address": "",  
        "is_shared": false,  
        "runner_type": "project_type",  
        "name": null,  
        "online": true,  
        "status": "online"  
    },  
    {  
        "active": true,  
        "paused": false,  
        "description": "test-2-20150125",  
        "id": 8,  
        "ip_address": "",  
        "is_shared": false,  
        "runner_type": "group_type",  
        "name": null,  
        "online": false,  
        "status": "offline"  
    }  
]

모든 러너 목록

Tier: Free, Premium, Ultimate Offering: Self-managed, GitLab Dedicated

GitLab 인스턴스(프로젝트 및 공유)의 모든 러너 목록을 가져옵니다.
접근은 관리자 액세스 권한이 있는 사용자로 제한됩니다.

전제 조건:

  • 대상 네임스페이스 또는 프로젝트의 관리자이거나 소유자 역할을 수행해야 합니다.
  • instance_type의 경우, GitLab 인스턴스의 관리자여야 합니다.
GET /runners/all  
GET /runners/all?scope=online  
GET /runners/all?type=project_type  
GET /runners/all?status=online  
GET /runners/all?paused=true  
GET /runners/all?tag_list=tag1,tag2
속성 유형 필수 설명
scope string no 더 이상 사용되지 않음: 대신 type 또는 status를 사용하세요. 반환할 러너의 범위 중 하나: specific, shared, active, paused, online 및 offline; 제공되지 않을 경우 모든 러너를 표시합니다.
type string no 반환할 러너의 유형 중 하나: instance_type, group_type, project_type
status string no 반환할 러너의 상태 중 하나: online, offline, stale, 또는 never_contacted.
다른 가능한 값은 더 이상 사용되지 않는 active 및 paused입니다.
offline 러너를 요청하면 stale 러너도 반환될 수 있습니다.
paused boolean no 새 작업을 수락하거나 무시하는 러너만 포함할지 여부
tag_list string array no 러너 태그 목록
version_prefix string no 반환할 러너의 버전 접두사. 예: 15.0, 16.1.241 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/all"
note
status 쿼리 매개변수의 active 및 paused 값은 더 이상 사용되지 않으며
향후 버전의 REST API에서 제거될 것입니다. 이는 paused 쿼리 매개변수로 대체됩니다.
note
응답의 active 속성은 더 이상 사용되지 않으며
향후 버전의 REST API에서 제거될 것입니다. 이는 paused 속성으로 대체됩니다.
note
응답의 ip_address 속성은 GitLab 16.1에서 더 이상 사용되지 않으며
향후 버전의 REST API에서 제거될 것입니다.
이 속성은 GitLab 17.0에서 빈 문자열을 반환하기 시작합니다.
ipAddress 속성은 해당 러너 관리자 내부에서 찾을 수 있으며, 현재는 GraphQL
CiRunnerManager 유형을 통해서만 사용할 수 있습니다.

예시 응답:

[  
    {  
        "active": true,  
        "paused": false,  
        "description": "shared-runner-1",  
        "id": 1,  
        "ip_address": "",  
        "is_shared": true,  
        "runner_type": "instance_type",  
        "name": null,  
        "online": true,  
        "status": "online"  
    },  
    {  
        "active": true,  
        "paused": false,  
        "description": "shared-runner-2",  
        "id": 3,  
        "ip_address": "",  
        "is_shared": true,  
        "runner_type": "instance_type",  
        "name": null,  
        "online": false,  
        "status": "offline"  
    },  
    {  
        "active": true,  
        "paused": false,  
        "description": "test-1-20150125",  
        "id": 6,  
        "ip_address": "",  
        "is_shared": false,  
        "runner_type": "project_type",  
        "name": null,  
        "online": true,  
        "status": "paused"  
    },  
    {  
        "active": true,  
        "paused": false,  
        "description": "test-2-20150125",  
        "id": 8,  
        "ip_address": "",  
        "is_shared": false,  
        "runner_type": "group_type",  
        "name": null,  
        "online": false,  
        "status": "offline"  
    }  
]

20개 이상의 러너를 보려면 페이지 매김을 사용하세요.

러너의 세부 정보 조회

러너의 세부 정보를 가져옵니다.

인스턴스 수준의 러너 세부 정보는 이 엔드포인트를 통해 모든 인증된 사용자에게 제공됩니다.

전제 조건:

  • 대상 네임스페이스 또는 프로젝트에 대해 최소한 Developer 역할이 있어야 합니다.
  • manage_runner 스코프 및 적절한 역할이 있는 액세스 토큰.
GET /runners/:id
속성 유형 필요 여부 설명
id 정수 예 러너의 ID 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6"

메모:

응답의 token 속성은 GitLab 12.10에서 더 이상 사용되지 않으며

GitLab 13.0에서 제거되었습니다.

메모:

응답의 active 속성은 더 이상 사용되지 않으며

REST API의 향후 버전에서 제거될 것입니다.

이 속성은 paused 속성으로 대체됩니다.

메모:

응답의 ip_address 속성은 GitLab 16.1에서 더 이상 사용되지 않으며

REST API의 향후 버전에서 제거됩니다.

이 속성은 GitLab 17.0에서 빈 문자열을 반환하기 시작합니다.

ipAddress 속성은 해당 러너 관리자 내부에서 찾을 수 있으며, 현재는 GraphQL을 통해서만 사용할 수 있습니다.

CiRunnerManager 타입.

메모:

응답의 version, revision, platform, 및 architecture 속성은 GitLab 17.0에서 더 이상 사용되지 않으며

REST API의 향후 버전에서 제거됩니다.

이 속성들은 GitLab 18.0에서 빈 문자열을 반환하기 시작합니다.

동일한 속성들은 해당 러너 관리자 내부에서 찾을 수 있으며, 현재는 GraphQL을 통해서만 사용할 수 있습니다.

CiRunnerManager 타입.

예시 응답:

{
    "active": true,
    "paused": false,
    "architecture": null,
    "description": "test-1-20150125",
    "id": 6,
    "ip_address": "",
    "is_shared": false,
    "runner_type": "project_type",
    "contacted_at": "2016-01-25T16:39:48.066Z",
    "maintenance_note": null,
    "name": null,
    "online": true,
    "status": "online",
    "platform": null,
    "projects": [
        {
            "id": 1,
            "name": "GitLab Community Edition",
            "name_with_namespace": "GitLab.org / GitLab Community Edition",
            "path": "gitlab-foss",
            "path_with_namespace": "gitlab-org/gitlab-foss"
        }
    ],
    "revision": null,
    "tag_list": [
        "ruby",
        "mysql"
    ],
    "version": null,
    "access_level": "ref_protected",
    "maximum_timeout": 3600
}

러너의 세부정보 업데이트

러너의 세부정보를 업데이트합니다.

PUT /runners/:id

사전 조건:

  • instance_type의 경우, GitLab 인스턴스의 관리자가 되어야 합니다.
  • group_type의 경우, 대상 네임스페이스에 대해 소유자 역할을 가져야 합니다.
  • project_type의 경우, 대상 프로젝트에 대해 최소한 유지 관리자 역할을 가져야 합니다.
  • manage_runner 범위와 적절한 역할이 있는 액세스 토큰이 필요합니다.
속성 유형 필수 여부 설명
id integer yes 러너의 ID
description string no 러너의 설명
active boolean no 사용 중단됨: 대신 paused를 사용하세요. 러너가 작업을 받을 수 있는지 여부를 나타내는 플래그
paused boolean no 러너가 새 작업을 무시해야 하는지 여부를 지정합니다.
tag_list array no 러너의 태그 목록
run_untagged boolean no 러너가 태그가 없는 작업을 실행할 수 있는지 여부를 지정합니다.
locked boolean no 러너가 잠겨 있는지 여부를 지정합니다.
access_level string no 러너의 접근 수준; not_protected 또는 ref_protected
maximum_timeout integer no 러너가 작업을 실행할 수 있는 최대 시간(초 단위)
maintenance_note string no 러너에 대한 자유 형식의 유지 관리 노트 (1024자) 
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6" \
     --form "description=test-1-20150125-test" --form "tag_list=ruby,mysql,tag1,tag2"

주: 응답의 token 속성은 GitLab 12.10에서 사용 중단되었고 GitLab 13.0에서 제거되었습니다.

주: active 쿼리 매개변수는 사용 중단되었으며 REST API의 향후 버전에서 제거될 예정입니다. paused 속성으로 대체됩니다.

주: 응답의 ip_address 속성은 GitLab 16.1에서 사용 중단되었으며 REST API의 향후 버전에서 제거될 예정입니다. 이 속성은 GitLab 17.0에서 빈 문자열을 반환하기 시작합니다. ipAddress 속성은 해당 러너 관리자 내에서 찾을 수 있으며, 현재는 GraphQL CiRunnerManager 유형을 통해서만 사용할 수 있습니다.

예시 응답:

{
    "active": true,
    "architecture": null,
    "description": "test-1-20150125-test",
    "id": 6,
    "ip_address": "",
    "is_shared": false,
    "runner_type": "group_type",
    "contacted_at": "2016-01-25T16:39:48.066Z",
    "maintenance_note": null,
    "name": null,
    "online": true,
    "status": "online",
    "platform": null,
    "projects": [
        {
            "id": 1,
            "name": "GitLab Community Edition",
            "name_with_namespace": "GitLab.org / GitLab Community Edition",
            "path": "gitlab-foss",
            "path_with_namespace": "gitlab-org/gitlab-foss"
        }
    ],
    "revision": null,
    "tag_list": [
        "ruby",
        "mysql",
        "tag1",
        "tag2"
    ],
    "version": null,
    "access_level": "ref_protected",
    "maximum_timeout": null
}

러너 일시 중지

러너를 일시 중지합니다.

사전 조건:

  • instance_type의 경우, GitLab 인스턴스의 관리자여야 합니다.
  • group_type의 경우, 대상 네임스페이스에 대해 소유자 역할을 가져야 합니다.
  • project_type의 경우, 대상 프로젝트에 대해 최소 유지 관리자 역할을 가져야 합니다.
  • manage_runner 범위와 적절한 역할을 가진 액세스 토큰.
PUT --form "paused=true" /runners/:runner_id

# --or--

# 사용 중단: 16.0에서 제거 계획
PUT --form "active=false" /runners/:runner_id
속성 유형 필수 설명
runner_id 정수 예 러너의 ID 
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
     --form "paused=true"  "https://gitlab.example.com/api/v4/runners/6"

# --or--

# 사용 중단: 16.0에서 제거 계획
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
     --form "active=false"  "https://gitlab.example.com/api/v4/runners/6"

참고: active 폼 속성은 사용 중단되었으며, REST API의 향후 버전에서 제거될 예정입니다. paused 속성으로 대체되었습니다.

러너에 의해 처리된 작업 목록

지정된 러너에 의해 처리 중이거나 처리된 작업 목록을 나열합니다. 작업 목록은 사용자가 최소한 리포터 역할을 가진 프로젝트로 제한됩니다.

GET /runners/:id/jobs
속성 유형 필수 설명
id 정수 예 러너의 ID
system_id 문자열 아니오 러너 관리자가 실행 중인 기계의 시스템 ID
status 문자열 아니오 작업의 상태; running, success, failed, canceled 중 하나
order_by 문자열 아니오 작업을 id로 정렬
sort 문자열 아니오 작업을 asc 또는 desc 순서로 정렬 (기본값: desc). sort가 지정되면 order_by도 지정해야 합니다. 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/1/jobs?status=running"

예제 응답:

[
    {
        "id": 2,
        "status": "running",
        "stage": "test",
        "name": "test",
        "ref": "main",
        "tag": false,
        "coverage": null,
        "created_at": "2017-11-16T08:50:29.000Z",
        "started_at": "2017-11-16T08:51:29.000Z",
        "finished_at": "2017-11-16T08:53:29.000Z",
        "duration": 120,
        "queued_duration": 2,
        "user": {
            "id": 1,
            "name": "John Doe2",
            "username": "user2",
            "state": "active",
            "avatar_url": "http://www.gravatar.com/avatar/c922747a93b40d1ea88262bf1aebee62?s=80&d=identicon",
            "web_url": "http://localhost/user2",
            "created_at": "2017-11-16T18:38:46.000Z",
            "bio": null,
            "location": null,
            "public_email": "",
            "skype": "",
            "linkedin": "",
            "twitter": "",
            "website_url": "",
            "organization": null
        },
        "commit": {
            "id": "97de212e80737a608d939f648d959671fb0a0142",
            "short_id": "97de212e",
            "title": "구성 업데이트\r",
            "created_at": "2017-11-16T08:50:28.000Z",
            "parent_ids": [
                "1b12f15a11fc6e62177bef08f47bc7b5ce50b141",
                "498214de67004b1da3d820901307bed2a68a8ef6"
            ],
            "message": "병합 요청 참조 !123",
            "author_name": "John Doe2",
            "author_email": "user2@example.org",
            "authored_date": "2017-11-16T08:50:27.000Z",
            "committer_name": "John Doe2",
            "committer_email": "user2@example.org",
            "committed_date": "2017-11-16T08:50:27.000Z"
        },
        "pipeline": {
            "id": 2,
            "sha": "97de212e80737a608d939f648d959671fb0a0142",
            "ref": "main",
            "status": "running"
        },
        "project": {
            "id": 1,
            "description": null,
            "name": "project1",
            "name_with_namespace": "John Doe2 / project1",
            "path": "project1",
            "path_with_namespace": "namespace1/project1",
            "created_at": "2017-11-16T18:38:46.620Z"
        }
    }
]

러너 관리자 목록

러너의 모든 관리자를 나열합니다.

GET /runners/:id/managers
속성 타입 필수 설명
id integer 예 러너의 ID 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/1/managers"

예시 응답:

[
    {
      "id": 1,
      "system_id": "s_89e5e9956577",
      "version": "16.11.1",
      "revision": "535ced5f",
      "platform": "linux",
      "architecture": "amd64",
      "created_at": "2024-06-09T11:12:02.507Z",
      "contacted_at": "2024-06-09T06:30:09.355Z",
      "ip_address": "127.0.0.1",
      "status": "offline"
    },
    {
        "id": 2,
        "system_id": "runner-2",
        "version": "16.11.0",
        "revision": "91a27b2a",
        "platform": "linux",
        "architecture": "amd64",
        "created_at": "2024-06-09T09:12:02.507Z",
        "contacted_at": "2024-06-09T06:30:09.355Z",
        "ip_address": "127.0.0.1",
        "status": "offline"
    }
]

프로젝트의 러너 목록

프로젝트에서 사용할 수 있는 모든 러너를 나열합니다. 여기에는 조상 그룹의 러너와 허용된 공유 러너가 포함됩니다.

전제 조건:

  • 대상 프로젝트의 관리자이거나 최소한 유지 관리 역할을 가져야 합니다.
GET /projects/:id/runners
GET /projects/:id/runners?scope=active
GET /projects/:id/runners?type=project_type
GET /projects/:id/runners/all?status=online
GET /projects/:id/runners/all?paused=true
GET /projects/:id/runners?tag_list=tag1,tag2
속성 타입 필수 설명
id integer/string 예 프로젝트의 ID 또는 URL-encoded 경로
scope string 아니요 더 이상 사용되지 않음: 대신 type 또는 status를 사용하십시오. 반환할 러너의 범위: active, paused, online 및 offline 중 하나; 제공되지 않으면 모든 러너 표시
type string 아니요 반환할 러너의 유형: instance_type, group_type, project_type 중 하나
status string 아니요 반환할 러너의 상태: online, offline, stale 또는 never_contacted 중 하나.
기타 가능한 값으로는 더 이상 사용되지 않는 active 및 paused가 있습니다.
offline 러너를 요청하면 stale 러너가 반환될 수도 있습니다. 이 경우 stale가 offline에 포함되기 때문입니다.
paused boolean 아니요 새로운 작업을 수락하거나 무시하는 러너만 포함할지 여부
tag_list string array 아니요 러너 태그의 목록
version_prefix string 아니요 반환할 러너 버전의 접두사. 예: 15.0, 14, 16.1.241 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners"

참고:

active 및 paused 값은 status 쿼리 매개변수에서 더 이상 사용되지 않으며, 향후 버전의 REST API에서 제거됩니다. 이들은 paused 쿼리 매개변수로 대체됩니다.

참고:

응답의 active 속성은 더 이상 사용되지 않으며 향후 버전의 REST API에서 제거됩니다. 이는 paused 속성으로 대체됩니다.

참고:

응답의 ip_address 속성은 GitLab 16.1에서 더 이상 사용되지 않으며, 향후 버전의 REST API에서 제거됩니다. 이 속성은 GitLab 17.0에서 빈 문자열을 반환하기 시작합니다. ipAddress 속성은 현재 GraphQL에서만 사용할 수 있는 해당 러너 관리자 내부에서 찾을 수 있습니다. CiRunnerManager type.

예시 응답:

[
    {
        "active": true,
        "paused": false,
        "description": "test-2-20150125",
        "id": 8,
        "ip_address": "",
        "is_shared": false,
        "runner_type": "project_type",
        "name": null,
        "online": false,
        "status": "offline"
    },
    {
        "active": true,
        "paused": false,
        "description": "development_runner",
        "id": 5,
        "ip_address": "",
        "is_shared": true,
        "runner_type": "instance_type",
        "name": null,
        "online": true,
        "status": "online"
    }
]

프로젝트에서 러너 활성화

프로젝트에서 사용 가능한 프로젝트 러너를 활성화합니다.

사전 조건:

  • instance_type의 경우, GitLab 인스턴스의 관리자가 되어야 합니다.
  • group_type의 경우, 대상 네임스페이스에 대한 소유자 역할이 있어야 합니다.
  • project_type의 경우, 대상 프로젝트에 대해 최소한 유지 관리자 역할이 있어야 합니다.
POST /projects/:id/runners
속성 타입 필수 설명
id 정수/문자열 예 프로젝트의 ID 또는 URL-인코딩 경로
runner_id 정수 예 러너의 ID 
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners" \
     --form "runner_id=9"

메모: 응답의 ip_address 속성은
GitLab 16.1에서 더 이상 사용되지 않으며
REST API의 향후 버전에서 제거될 예정입니다.
이 속성은 GitLab 17.0에서 빈 문자열을 반환하기 시작할 것입니다.
ipAddress 속성은 현재 GraphQL을 통해만 접근 가능한 해당 러너 관리자의 내부에서 찾을 수 있습니다.
CiRunnerManager 타입.

예시 응답:

{
    "active": true,
    "description": "test-2016-02-01",
    "id": 9,
    "ip_address": "",
    "is_shared": false,
    "runner_type": "project_type",
    "name": null,
    "online": true,
    "status": "online"
}

프로젝트에서 러너 비활성화

프로젝트에서 프로젝트 러너를 비활성화합니다. 지정된 러너와 연결된 유일한 프로젝트가 아닌 경우에만 작동합니다. 그렇지 않으면 오류가 반환됩니다. 대신 러너 삭제 호출을 사용하세요.

사전 조건:

  • instance_type의 경우, GitLab 인스턴스의 관리자가 되어야 합니다.
  • group_type의 경우, 대상 네임스페이스에 대한 소유자 역할이 있어야 합니다.
  • project_type의 경우, 대상 프로젝트에 대해 최소한 유지 관리자 역할이 있어야 합니다.
DELETE /projects/:id/runners/:runner_id
속성 타입 필수 설명
id 정수/문자열 예 프로젝트의 ID 또는 URL-인코딩 경로
runner_id 정수 예 러너의 ID 
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners/9"

그룹의 러너 목록

그룹 및 해당 상위 그룹에서 사용 가능한 모든 러너를 나열하며, 허용된 공유 러너를 포함합니다.

사전 조건:

  • 대상 네임스페이스의 관리자이거나 유지 관리자 역할이 있어야 합니다.
GET /groups/:id/runners
GET /groups/:id/runners?type=group_type
GET /groups/:id/runners/all?status=online
GET /groups/:id/runners/all?paused=true
GET /groups/:id/runners?tag_list=tag1,tag2
속성 타입 필수 설명
id 정수 예 그룹의 ID
type 문자열 아니오 반환할 러너의 유형, 다음 중 하나: instance_type, group_type, project_type. project_type 값은 더 이상 사용되지 않음이며 GitLab 15.0에서 제거됩니다.
status 문자열 아니오 반환할 러너의 상태, 다음 중 하나: online, offline, stale, 또는 never_contacted.
기타 가능한 값은 더 이상 사용되지 않는 active와 paused입니다.
offline 러너를 요청할 경우 stale 러너도 반환될 수 있습니다.
paused 부울 아니오 새로운 작업을 수락 또는 무시하는 러너만 포함할지 여부
tag_list 문자열 배열 아니오 러너 태그 목록
version_prefix 문자열 아니오 반환할 러너의 버전 접두사. 예: 15.0, 14, 16.1.241 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/9/runners"

메모: status 쿼리 매개변수에서 active 및 paused 값은 더 이상 사용되지 않으며
REST API의 향후 버전에서 제거될 예정입니다.
이들은 paused 쿼리 매개변수로 대체되었습니다.

메모: 응답의 active 속성은 더 이상 사용되지 않으며
REST API의 향후 버전에서 제거될 예정입니다.
이 속성은 paused 속성으로 대체되었습니다.

메모: 응답의 ip_address 속성은
GitLab 16.1에서 더 이상 사용되지 않으며
REST API의 향후 버전에서 제거될 예정입니다.
이 속성은 GitLab 17.0에서 빈 문자열을 반환하기 시작할 것입니다.
ipAddress 속성은 현재 GraphQL을 통해만 접근 가능한 해당 러너 관리자의 내부에서 찾을 수 있습니다.
CiRunnerManager 타입.

예시 응답:

[
  {
    "id": 3,
    "description": "Shared",
    "ip_address": "",
    "active": true,
    "paused": false,
    "is_shared": true,
    "runner_type": "instance_type",
    "name": "gitlab-runner",
    "online": null,
    "status": "never_contacted"
  },
  {
    "id": 6,
    "description": "Test",
    "ip_address": "",
    "active": true,
    "paused": false,
    "is_shared": true,
    "runner_type": "instance_type",
    "name": "gitlab-runner",
    "online": false,
    "status": "offline"
  },
  {
    "id": 8,
    "description": "Test 2",
    "ip_address": "",
    "active": true,
    "paused": false,
    "is_shared": false,
    "runner_type": "group_type",
    "name": "gitlab-runner",
    "online": null,
    "status": "never_contacted"
  }
]

러너 생성

경고:
이 엔드포인트는 러너 등록 토큰으로 등록하는 것이 프로젝트 또는 그룹 설정에서 비활성화된 경우 HTTP 410 Gone 상태 코드를 반환합니다.
러너 등록 토큰으로 등록하는 것이 비활성화된 경우, POST /user/runners 엔드포인트를 사용하여 러너를 생성하고 등록하세요.

러너 등록 토큰으로 러너를 생성합니다.

POST /runners
속성 유형 필수 설명
token 문자열 예 등록 토큰
description 문자열 아니요 러너에 대한 설명
info 해시 아니요 러너의 메타데이터입니다. name, version, revision, platform, architecture를 포함할 수 있지만, UI의 관리자 영역에서는 version, platform, architecture만 표시됩니다.
active 부울 아니요 사용 중단됨: 대신 paused를 사용하세요. 러너가 새로운 작업을 받을 수 있는지 여부를 지정합니다.
paused 부울 아니요 러너가 새로운 작업을 무시해야 하는지를 지정합니다.
locked 부울 아니요 러너가 현재 프로젝트에 잠겨야 하는지를 지정합니다.
run_untagged 부울 아니요 러너가 태그가 없는 작업을 처리해야 하는지를 지정합니다.
tag_list 문자열 배열 아니요 러너 태그 목록입니다.
access_level 문자열 아니요 러너의 접근 수준; not_protected 또는 ref_protected
maximum_timeout 정수 아니요 러너가 작업을 실행할 수 있는 최대 시간(초)입니다.
maintainer_note 문자열 아니요 사용 중단됨, maintenance_note를 참조하세요.
maintenance_note 문자열 아니요 러너에 대한 자유 형식의 유지 보수 노트(1024자) 
curl --request POST "https://gitlab.example.com/api/v4/runners" \
     --form "token=<registration_token>" --form "description=test-1-20150125-test" \
     --form "tag_list=ruby,mysql,tag1,tag2"

응답:

상태 설명
201 러너가 생성되었습니다.
403 잘못된 러너 등록 토큰입니다.
410 러너 등록이 비활성화되었습니다.

예시 응답:

{
    "id": 12345,
    "token": "6337ff461c94fd3fa32ba3b1ff4125",
    "token_expires_at": "2021-09-27T21:05:03.203Z"
}

러너 삭제

러너를 삭제하는 방법에는 두 가지가 있습니다:

  • 러너 ID로 지정하기.
  • 러너의 인증 토큰으로 지정하기.

ID로 러너 삭제

ID로 러너를 삭제하려면 러너 ID와 함께 액세스 토큰을 사용하세요:

사전 요구 사항:

  • instance_type의 경우, GitLab 인스턴스의 관리자가 되어야 합니다.
  • group_type의 경우, 대상 네임스페이스에 대한 소유자 역할을 가져야 합니다.
  • project_type의 경우, 대상 프로젝트에 대해 최소한 유지 관리자 역할을 가져야 합니다.
  • manage_runner 범위와 적절한 역할이 있는 액세스 토큰.
DELETE /runners/:id
속성 유형 필수 설명
id 정수 예 러너의 ID입니다. ID는 UI의 설정 > CI/CD에서 볼 수 있습니다. 러너를 확장하면 러너 제거 버튼 아래에 샵 기호(#)가 있는 ID가 표시됩니다. 예: #6. 
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6"

인증 토큰으로 러너 삭제

인증 토큰을 사용하여 러너를 삭제합니다:

전제 조건:

  • 대상 네임스페이스 또는 프로젝트의 관리자이거나 소유자 역할을 가져야 합니다.
  • instance_type에 대해 GitLab 인스턴스의 관리자여야 합니다.
DELETE /runners
속성 유형 필수 설명
token 문자열 예 러너의 인증 토큰입니다. 
curl --request DELETE "https://gitlab.example.com/api/v4/runners" \
     --form "token=<authentication_token>"

응답:

상태 설명
204 러너가 삭제되었습니다

등록된 러너에 대한 인증 확인

등록된 러너의 인증 자격 증명을 검증합니다.

POST /runners/verify
속성 유형 필수 설명
token 문자열 예 러너의 인증 토큰입니다.
system_id 문자열 아니오 러너의 시스템 식별자입니다. 이 속성은 token이 glrt-로 시작하는 경우 필수입니다. 
curl --request POST "https://gitlab.example.com/api/v4/runners/verify" \
     --form "token=<authentication_token>"

응답:

상태 설명
200 자격 증명이 유효합니다
403 자격 증명이 잘못되었습니다

예시 응답:

{
    "id": 12345,
    "token": "glrt-6337ff461c94fd3fa32ba3b1ff4125",
    "token_expires_at": "2021-09-27T21:05:03.203Z"
}

인스턴스의 러너 등록 토큰 재설정

경고: 러너 등록 토큰 및 특정 구성 인수에 대한 지원은 GitLab 15.6에서 사용 중단되었으며 GitLab 17.0에서 제거될 예정입니다. GitLab 17.0 이후에는 러너 등록 토큰을 재설정할 수 없으며 reset_registration_token 엔드포인트가 작동하지 않습니다.

GitLab 인스턴스의 러너 등록 토큰을 재설정합니다.

POST /runners/reset_registration_token

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/runners/reset_registration_token"

프로젝트의 러너 등록 토큰 재설정

경고: 러너 등록 토큰 및 특정 구성 인수에 대한 지원은 GitLab 15.6에서 사용 중단되었으며 GitLab 17.0에서 제거될 예정입니다. GitLab 17.0 이후에는 러너 등록 토큰을 재설정할 수 없으며 reset_registration_token 엔드포인트가 작동하지 않습니다.

프로젝트의 러너 등록 토큰을 재설정합니다.

POST /projects/:id/runners/reset_registration_token

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/projects/9/runners/reset_registration_token"

그룹의 러너 등록 토큰 재설정

경고:

러너 등록 토큰과 특정 구성 인수에 대한 지원은 더 이상 지원되지 않음으로 GitLab 15.6에서 제거되며, GitLab 17.0에서 완전히 삭제됩니다. GitLab 17.0 이후에는 러너 등록 토큰을 재설정할 수 없으며 reset_registration_token 엔드포인트는 작동하지 않을 것입니다.

그룹의 러너 등록 토큰을 재설정하세요.

POST /groups/:id/runners/reset_registration_token

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/groups/9/runners/reset_registration_token"

러너 ID를 사용하여 러너의 인증 토큰 재설정

러너 ID를 사용하여 러너의 인증 토큰을 재설정하세요.

사전 조건:

  • instance_type의 경우, GitLab 인스턴스의 관리자여야 합니다.
  • group_type의 경우, 대상 네임스페이스에 대해 소유자 역할을 가져야 합니다.
  • project_type의 경우, 대상 프로젝트에 대해 최소한 유지 관리자 역할을 가져야 합니다.
  • manage_runner 범위와 적절한 역할을 가진 액세스 토큰이 필요합니다.
POST /runners/:id/reset_authentication_token
속성 유형 필수 설명
id 정수 예 러너의 ID 
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/runners/1/reset_authentication_token"

예시 응답:

{
    "token": "6337ff461c94fd3fa32ba3b1ff4125",
    "token_expires_at": "2021-09-27T21:05:03.203Z"
}

현재 토큰을 사용하여 러너의 인증 토큰 재설정

현재 토큰의 값을 입력으로 사용하여 러너의 인증 토큰을 재설정하세요.

POST /runners/reset_authentication_token
속성 유형 필수 설명
token 문자열 예 러너의 인증 토큰 
curl --request POST --form "token=<current token>" \
     "https://gitlab.example.com/api/v4/runners/reset_authentication_token"

예시 응답:

{
    "token": "6337ff461c94fd3fa32ba3b1ff4125",
    "token_expires_at": "2021-09-27T21:05:03.203Z"
}