Runners API

Tier: Free, Premium, Ultimate Offering: GitLab.com, 자체 관리, GitLab 전용

이 페이지에서는 인스턴스에 등록된 러너에 대한 엔드포인트에 대해 설명합니다. 현재 사용자와 연결된 러너를 만들려면 러너 만들기를 참조하십시오.

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

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

등록 및 인증 토큰

GitLab과 러너를 연결할 때 고려해야 할 두 가지 토큰이 있습니다.

토큰 설명
등록 토큰 러너를 등록하는 데 사용되는 토큰입니다. GitLab을 통해 얻을 수 있습니다.
인증 토큰 러너가 GitLab 인스턴스와 인증하는 데 사용되는 토큰입니다. 이 토큰은 러너를 등록하거나 러너 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 string 아니요 사용 중인 러너의 범위입니다. 빈 값이면 모든 러너를 표시합니다. 러너 반환 범주 중 하나인 active, paused, online, offline입니다.
type string 아니요 반환할 러너의 유형입니다. instance_type, group_type, project_type 중 하나입니다.
status string 아니요 반환할 러너의 상태입니다. online, offline, stale, never_contacted 중 하나입니다.
기존 active 및 paused도 가능하지만, stale은 offline에 포함되므로 offline 러너를 요청하면 stale 러너도 반환될 수 있습니다.
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/runners"

참고: status 쿼리 매개변수의 active 및 paused 값은 REST API의 향후 버전에서 삭제될 예정입니다. paused 쿼리 매개변수로 대체됩니다.

참고: 응답의 active 속성은 REST API의 향후 버전에서 삭제될 예정입니다. paused 속성으로 대체됩니다.

참고: 응답의 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: 자체 관리, GitLab 전용

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 아니요 사용 중인 러너의 범위입니다. 빈 값이면 모든 러너를 표시합니다. 러너 반환 범주 중 하나인 specific, shared, active, paused, online, offline입니다.
type string 아니요 반환할 러너의 유형입니다. instance_type, group_type, project_type 중 하나입니다.
status string 아니요 반환할 러너의 상태입니다. online, offline, stale, never_contacted 중 하나입니다.
기존 active 및 paused도 가능하지만, stale은 offline에 포함되므로 offline 러너를 요청하면 stale 러너도 반환될 수 있습니다.
paused boolean 아니요 새 작업을 수락하거나 무시하는 러너만 포함할지 여부입니다.
tag_list string array 아니요 러너 태그 목록입니다.
version_prefix string 아니요 반환할 러너 버전의 접두사입니다. 예: 15.0, 16.1.241 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/all"

참고: status 쿼리 매개변수의 active 및 paused 값은 REST API의 향후 버전에서 삭제될 예정입니다. paused 쿼리 매개변수로 대체됩니다.

참고: 응답의 active 속성은 REST API의 향후 버전에서 삭제될 예정입니다. paused 속성으로 대체됩니다.

참고: 응답의 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 유형을 통해서만 사용할 수 있습니다(GraphQL 참조).

참고: 응답의 version, revision, platform, 그리고 architecture 속성은 GitLab 17.0에서 비추천되었으며 REST API의 향후 버전에서 제거될 예정입니다. 이러한 속성은 GitLab 18.0에서 빈 문자열을 반환하기 시작합니다. 같은 속성은 현재 GraphQL의 CiRunnerManager 유형을 통해서만 사용할 수 있습니다(GraphQL 참조).

예시 응답: 

{
    "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의 경우 대상 네임스페이스에 대한 Owner 역할이 있어야 합니다.
  • project_type의 경우 대상 프로젝트에 대한 최소한의 Maintainer 역할이 있어야 합니다.
  • manage_runner 스코프 및 적절한 역할을 가진 엑세스 토큰이 있어야 합니다.
속성 타입 필수 설명
id 정수 예 러너의 ID
description 문자열 아니오 러너의 설명
active 부울 아니오 비추천됨: 대신 paused 사용. 러너가 작업을 수신할 수 있는지를 나타내는 플래그
paused 부울 아니오 러너가 새 작업을 무시해야 하는지를 지정함
tag_list 배열 아니오 러너의 태그 목록
run_untagged 부울 아니오 러너가 태그되지 않은 작업을 실행할 수 있는지를 지정함
locked 부울 아니오 러너가 잠겨 있는지를 지정함
access_level 문자열 아니오 러너의 액세스 레벨; not_protected 또는 ref_protected
maximum_timeout 정수 아니오 러너가 작업을 실행할 수 있는 시간(초)을 제한하는 최대 시간
maintenance_note 문자열 아니오 러너에 대한 자유 형식의 유지보수 노트(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 유형을 통해서만 사용할 수 있습니다(GraphQL 참조).

예시 응답: 

{
    "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의 경우 대상 프로젝트의 최소한 Maintainer 역할이 있어야 합니다.
  • manage_runner 스코프와 적절한 역할을 갖춘 액세스 토큰이 있어야 합니다. 
PUT --form "paused=true" /runners/:runner_id

# --or--

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

# --or--

# Deprecated: 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 속성으로 대체됩니다.

러너가 처리한 작업 목록

지정된 러너에 의해 처리되고 있는 또는 처리된 작업 목록을 나열합니다. 사용자가 적어도 Reporter 역할을 갖춘 프로젝트로 제한됩니다. 

GET /runners/:id/jobs
속성 유형 필수 여부 설명
id integer 예 러너의 ID
system_id string 아니오 러너 관리자가 실행 중인 기계의 시스템 ID
status string 아니오 작업 상태; running, success, failed, canceled 중 하나
order_by string 아니오 작업을 id로 정렬
sort string 아니오 작업을 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": "Update configuration\r",
            "created_at": "2017-11-16T08:50:28.000Z",
            "parent_ids": [
                "1b12f15a11fc6e62177bef08f47bc7b5ce50b141",
                "498214de67004b1da3d820901307bed2a68a8ef6"
            ],
            "message": "See merge request !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",

    }
]

프로젝트의 러너 목록

프로젝트에 사용 가능한 모든 러너를 나열하며, 조상 그룹 및 허용된 공유 러너를 포함합니다.

전제 조건:

  • 대상 프로젝트의 관리자이거나 적어도 Maintainer 역할이 있어야 합니다. 
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 인코딩된 경로
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"

참고: status 쿼리 매개변수의 active 및 paused 값이 사용되지 않음 그리고 REST API의 향후 버전에서 제거됩니다. 이 값들은 paused 쿼리 매개변수로 대체됩니다.

참고: 응답의 active 속성이 사용되지 않음 그리고 REST API의 향후 버전에서 제거됩니다. paused 속성으로 대체됩니다.

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

예시 응답: 

[
    {
        "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의 경우, 대상 프로젝트의 적어도 Maintainer 역할이 있어야 합니다. 
POST /projects/:id/runners
속성 유형 필수 여부 설명
id integer/string 예 프로젝트의 ID 또는 URL-인코딩된 경로
runner_id integer 예 러너의 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의 경우, 대상 프로젝트의 적어도 Maintainer 역할이 있어야 합니다. 
DELETE /projects/:id/runners/:runner_id
속성 유형 필수 여부 설명
id integer/string 예 프로젝트의 ID 또는 URL-encoded path of the project
runner_id integer 예 러너의 ID 
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners/9"

그룹의 러너 목록

그룹 및 조상 그룹에 있는 모든 러너와 허용된 공유 러너를 모두 나열합니다.

전제 조건:

  • 대상 네임스페이스의 관리자거나 Maintainer 역할이어야 합니다. 
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 값은 deprecated되었으며 GitLab 15.0에서 제거될 예정입니다.
status 문자열 아니요 반환할 러너의 상태 중 하나인 online, offline, stale, never_contacted 중 하나입니다.
기존의 active 및 paused 역시 deprecated되었으며 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 값은 deprecated되었으며 REST API의 향후 버전에서 제거됩니다. 이들은 paused 쿼리 매개변수로 대체됩니다.

참고: 응답 내의 active 속성은 deprecated되었으며 REST API의 향후 버전에서 제거됩니다. 이는 paused 속성으로 대체됩니다.

참고: 응답 내의 ip_address 속성은 GitLab 16.1에서 deprecated되었으며 REST API의 향후 버전에서 제거될 예정입니다. 이 속성은 GitLab 17.0에서 빈 문자열을 반환하기 시작할 것입니다. ipAddress 속성은 현재 GraphQL의 CiRunnerManager 타입을 통해서만 사용할 수 있습니다.

응답 예시: 

[
  {
    "id": 3,
    "description": "공유됨",
    "ip_address": "",
    "active": true,
    "paused": false,
    "is_shared": true,
    "runner_type": "instance_type",
    "name": "gitlab-runner",
    "online": null,
    "status": "never_contacted"
  },
  {
    "id": 6,
    "description": "테스트",
    "ip_address": "",
    "active": true,
    "paused": false,
    "is_shared": true,
    "runner_type": "instance_type",
    "name": "gitlab-runner",
    "online": false,
    "status": "offline"
  },
  {
    "id": 8,
    "description": "테스트 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를 포함할 수 있지만 Admin 영역의 UI에 표시되는 것은 version, platform, architecture만입니다.
active 부울 아니요 Deprecated: 대신 paused 사용. 러너가 새 작업을 수락할 수 있는지 여부를 지정합니다.
paused 부울 아니요 러너가 새 작업을 무시해야 하는지 여부를 지정합니다.
locked 부울 아니요 현재 프로젝트에서 러너를 잠그도록 지정합니다.
run_untagged 부울 아니요 러너가 태그되지 않은 작업을 처리해야 하는지 여부를 지정합니다.
tag_list 문자열 배열 아니요 러너 태그 목록입니다.
access_level 문자열 아니요 런너의 액세스 레벨; not_protected 또는 ref_protected
maximum_timeout 정수 아니요 러너가 작업을 실행하는데 허용되는 시간(초)을 제한하는 최대 제한 시간입니다.
maintainer_note 문자열 아니요 Deprecated, maintenance_note 참조
maintenance_note 문자열 아니요 러너에 대한 자유 형식의 유지 관리 노트(1024자) 
curl --request POST "https://gitlab.example.com/api/v4/runners" \
     --form "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의 경우 대상 프로젝트의 적어도 Maintainer 역할이어야 합니다.
  • 러너를 관리하는 범위와 적절한 역할을 가진 액세스 토큰이 있어야 합니다. 
DELETE /runners/:id
속성 유형 필요 여부 설명
id integer yes 러너 ID. UI의 Settings > CI/CD에서 ID가 표시됩니다. Runners를 확장하고 Remove Runner 버튼 아래에는 예를 들어 #6로 시작하는 ID가 있습니다. 
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6"

인증 토큰별 러너 삭제

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

전제 조건:

  • 대상 네임스페이스나 프로젝트의 관리자이거나 소유자 역할이어야 합니다.
  • instance_type의 경우 GitLab 인스턴스의 관리자여야 합니다. 
DELETE /runners
속성 유형 필요 여부 설명
token string yes 러너의 인증 토큰. 
curl --request DELETE "https://gitlab.example.com/api/v4/runners" \
     --form "token=<authentication_token>"

응답:

상태 설명
204 러너가 삭제됨

등록된 러너의 인증 확인

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

POST /runners/verify
속성 유형 필요 여부 설명
token string yes 러너의 인증 토큰.
system_id string no 러너의 시스템 식별자입니다. 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의 경우 대상 프로젝트의 적어도 Maintainer 역할이어야 합니다.
  • 러너를 관리하는 범위와 적절한 역할을 가진 액세스 토큰이 있어야 합니다. 
POST /runners/:id/reset_authentication_token
속성 유형 필요 여부 설명
id integer yes 러너 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 string yes 러너의 인증 토큰 
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"
}