이 API를 사용하여 인스턴스에 등록된 러너를 관리합니다.

새 인스턴스, 그룹 또는 프로젝트 러너를 만들려면 POST /user/runners 엔드포인트를 사용합니다. 기존 러너는 이 API로 관리합니다.

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

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

등록 및 인증 토큰#

러너를 GitLab에 연결하려면 두 개의 토큰이 필요합니다.

러너 등록에 토큰을 사용하는 방법의 예시는 다음과 같습니다.

1. 등록 토큰과 함께 GitLab API를 사용하여 러너를 등록하면 인증 토큰을 받습니다.

2. 인증 토큰을 러너의 구성 파일에 추가합니다.

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

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

사용 가능한 모든 러너 목록#

사용자가 사용할 수 있는 모든 러너를 나열합니다.

사전 요구 사항:

• 그룹 러너의 경우 소유자 네임스페이스에서 Owner 권한이 있어야 합니다.
• 프로젝트 러너의 경우 러너에 할당된 프로젝트에서 Security Manager, Maintainer 또는 Owner 권한이 있어야 합니다.

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

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

응답 예시:

[
    {
        "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",
        "job_execution_status": "idle"
    },
    {
        "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",
        "job_execution_status": "idle"
    }
]

모든 러너 목록#

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

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

응답 예시:

[
    {
        "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",
        "job_execution_status": "idle"
    },
    {
        "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",
        "job_execution_status": "idle"
    },
    {
        "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",
        "job_execution_status": "idle"
    },
    {
        "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",
        "job_execution_status": "idle"
    }
]

처음 20개를 넘는 러너를 보려면 페이지네이션을 사용합니다.

러너의 세부 정보 조회#

러너의 세부 정보를 조회합니다.

인스턴스 러너의 세부 정보는 이 엔드포인트를 통해 인증된 모든 사용자가 확인할 수 있습니다.

사전 요구 사항:

• 사용자 액세스: 다음 중 하나를 충족해야 합니다.
  • 그룹 러너의 경우: 소유자 네임스페이스에서 Maintainer 또는 Owner 권한.
  • 프로젝트 러너의 경우: 러너를 소유한 프로젝트에서 Security Manager, Maintainer 또는 Owner 권한.
  • 해당 그룹 또는 프로젝트에서 admin_runners 권한이 있는 사용자 지정 역할.
• manage_runner 스코프와 그에 맞는 권한을 가진 액세스 토큰.

GET /runners/:id

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

응답 예시:

{
    "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",
    "job_execution_status": "idle",
    "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,
    "token_expires_at": "2025-01-01T00:00:00.000Z"
}

token_expires_at은 러너의 민감한 데이터를 볼 수 있는 사용자에게만 반환됩니다. 인스턴스 러너의 경우 Admin Mode가 활성화된 관리자가 해당합니다. 러너 토큰에 만료일이 없으면 값은 null입니다.

러너의 세부 정보 업데이트#

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

PUT /runners/:id

사전 요구 사항:

• 사용자 액세스: 다음 중 하나를 충족해야 합니다.
  • 인스턴스 러너의 경우: GitLab 인스턴스에 대한 관리자 액세스 권한.
  • 그룹 러너의 경우: 소유자 네임스페이스에서 Owner 권한.
  • 프로젝트 러너의 경우: 러너에 할당된 프로젝트에서 Maintainer 또는 Owner 권한.
  • 해당 그룹 또는 프로젝트에서 admin_runners 권한이 있는 사용자 지정 역할.
• manage_runner 스코프와 그에 맞는 권한을 가진 액세스 토큰.

curl --request PUT \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/runners/6" \
     --form "description=test-1-20150125-test" \
     --form "tag_list=ruby,mysql,tag1,tag2"

응답 예시:

{
    "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",
    "job_execution_status": "idle",
    "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
}

러너 일시 중지#

러너를 일시 중지합니다.

사전 요구 사항:

• 사용자 액세스: 다음 중 하나를 충족해야 합니다.
  • 인스턴스 러너의 경우: GitLab 인스턴스에 대한 관리자 액세스 권한.
  • 그룹 러너의 경우: 소유자 네임스페이스에서 Owner 권한.
  • 프로젝트 러너의 경우: 러너에 할당된 프로젝트에서 Maintainer 또는 Owner 권한.
  • 해당 그룹 또는 프로젝트에서 admin_runners 권한이 있는 사용자 지정 역할.
• manage_runner 스코프와 그에 맞는 권한을 가진 액세스 토큰.

PUT --form "paused=true" /runners/:runner_id

# --or--

# Deprecated: removal planned in 16.0
PUT --form "active=false" /runners/:runner_id

curl --request PUT \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --form "paused=true"  \
     --url "https://gitlab.example.com/api/v4/runners/6"

# --or--

# Deprecated: removal planned in 16.0
curl --request PUT \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --form "active=false"  \
     --url "https://gitlab.example.com/api/v4/runners/6"

러너가 처리한 모든 job 목록#

히스토리

• 오름차순 keyset 페이지네이션이 GitLab 19.4에 도입되었습니다.

지정된 러너가 처리 중이거나 처리했던 모든 job을 나열합니다. job 목록은 사용자가 Reporter, Developer, Maintainer, 또는 Owner 권한을 가진 프로젝트로 제한됩니다.

GET /runners/:id/jobs

이 엔드포인트는 keyset 페이지네이션도 지원하며, 이 방식이 권장되는 페이지네이션 방법입니다. keyset 페이지네이션은 id 기준 오름차순 또는 내림차순 정렬을 지원하며, X-Total 또는 X-Total-Pages 헤더를 반환하지 않습니다.

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/runners/1/jobs?status=success&pagination=keyset&per_page=20&order_by=id&sort=desc"

다음 페이지를 가져오려면 rel="next"가 포함된 Link 응답 헤더를 따라갑니다.

curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "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": "",
            "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

curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "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",
      "job_execution_status": "idle"
    },
    {
      "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",
      "job_execution_status": "idle"
    }
]

프로젝트의 모든 러너 목록#

상위 그룹의 러너와 허용된 인스턴스 러너를 포함해 프로젝트에서 사용할 수 있는 모든 러너를 나열합니다.

사전 요구 사항:

• GitLab 인스턴스의 관리자이거나 대상 프로젝트에 대해 최소한 Maintainer 또는 Auditor 권한이 있어야 합니다.

GET /projects/:id/runners
GET /projects/:id/runners?scope=active
GET /projects/:id/runners?type=project_type
GET /projects/:id/runners?status=online
GET /projects/:id/runners?paused=true
GET /projects/:id/runners?tag_list=tag1,tag2

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

응답 예시:

[
    {
        "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",
        "job_execution_status": "idle"
    },
    {
        "active": true,
        "paused": false,
        "description": "development_runner",
        "id": 5,
        "ip_address": "",
        "is_shared": true,
        "runner_type": "instance_type",
        "name": null,
        "online": true,
        "status": "online",
        "job_execution_status": "idle"
    }
]

프로젝트에 러너 할당#

사용 가능한 프로젝트 러너를 프로젝트에 할당합니다.

사전 요구 사항:

• 사용자 접근: 다음 중 하나가 있어야 합니다.

  • 러너를 소유한 프로젝트와 대상 프로젝트에 대한 Maintainer 또는 Owner 권한.
  • 관련 그룹 또는 프로젝트에서 admin_runners 권한을 가진 사용자 지정 역할.

POST /projects/:id/runners

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

응답 예시:

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

프로젝트에서 러너 할당 해제#

프로젝트에서 프로젝트 러너의 할당을 해제합니다. 소유자 프로젝트에서는 러너를 할당 해제할 수 없습니다. 이 작업을 시도하면 오류가 발생합니다. 대신 러너 삭제 호출을 사용합니다.

사전 요구 사항:

• 관리자가 아니라면 러너를 잠그지 않아야 합니다.
• 사용자 접근: 다음 중 하나가 있어야 합니다.
  • 할당을 해제하려는 프로젝트에 대한 Maintainer 또는 Owner 권한.
  • 관련 그룹 또는 프로젝트에서 admin_runners 권한을 가진 사용자 지정 역할.
• manage_runner 범위와 적절한 역할을 가진 액세스 토큰.

DELETE /projects/:id/runners/:runner_id

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

그룹의 모든 러너 목록#

허용된 인스턴스 러너를 포함해 그룹과 그 상위 그룹에서 사용할 수 있는 모든 러너를 나열합니다.

사전 요구 사항:

• 사용자 접근: 다음 중 하나가 있어야 합니다.
  • GitLab 인스턴스에 대한 관리자 접근.
  • 그룹에 대한 Owner 또는 Auditor 권한.
  • 그룹에서 admin_runners 권한을 가진 사용자 지정 역할.
• manage_runner 범위와 적절한 역할을 가진 액세스 토큰.

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

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

응답 예시:

[
  {
    "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",
    "job_execution_status": "idle"
  },
  {
    "id": 6,
    "description": "Test",
    "ip_address": "",
    "active": true,
    "paused": false,
    "is_shared": true,
    "runner_type": "instance_type",
    "name": "gitlab-runner",
    "online": false,
    "status": "offline",
    "job_execution_status": "idle"
  },
  {
    "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",
    "job_execution_status": "idle"
  }
]

러너 만들기#

러너 등록 토큰으로 러너를 만듭니다.

프로젝트 또는 그룹 설정에서 러너 등록 토큰을 사용한 등록이 비활성화되어 있으면 이 엔드포인트는 HTTP 410 Gone 상태 코드를 반환합니다. 러너 등록 토큰을 사용한 등록이 비활성화된 경우에는 대신 POST /user/runners 엔드포인트를 사용하여 러너를 만들고 등록합니다.

POST /runners

curl --request POST \
     --url "https://gitlab.example.com/api/v4/runners" \
     --form "token=<registration_token>" --form "description=test-1-20150125-test" \
     --form "tag_list=ruby,mysql,tag1,tag2"

응답:

응답 예시:

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

러너 삭제#

다음을 지정하여 러너를 삭제할 수 있습니다.

• 러너 ID
• 러너의 인증 토큰

ID로 러너 삭제#

러너를 ID로 삭제하려면 액세스 토큰과 러너의 ID를 사용합니다.

사전 요구 사항:

• 사용자 접근: 다음 중 하나가 있어야 합니다.
  • 인스턴스 러너의 경우: GitLab 인스턴스에 대한 관리자 접근.
  • 그룹 러너의 경우: 소유자 네임스페이스에 대한 Owner 권한.
  • 프로젝트 러너의 경우: 러너를 소유한 프로젝트에 대한 Maintainer 또는 Owner 권한.
  • 관련 그룹 또는 프로젝트에서 admin_runners 권한을 가진 사용자 지정 역할.
• manage_runner 범위와 적절한 역할을 가진 액세스 토큰.

DELETE /runners/:id

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

인증 토큰으로 러너 삭제#

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

DELETE /runners

curl --request DELETE \
     --url "https://gitlab.example.com/api/v4/runners" \
     --form "token=<authentication_token>"

응답:

등록된 러너의 인증 확인#

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

POST /runners/verify

curl --request POST \
     --url "https://gitlab.example.com/api/v4/runners/verify" \
     --form "token=<authentication_token>"

응답:

응답 예시:

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

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

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

POST /runners/reset_registration_token

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

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

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

POST /projects/:id/runners/reset_registration_token

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

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

그룹의 러너 등록 토큰을 재설정합니다.

POST /groups/:id/runners/reset_registration_token

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

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

러너 ID를 사용하여 러너의 인증 토큰을 재설정합니다.

사전 요구 사항:

• 사용자 접근: 다음 중 하나가 있어야 합니다.
  • 인스턴스 러너의 경우: GitLab 인스턴스에 대한 관리자 접근.
  • 그룹 러너의 경우: 소유자 네임스페이스에 대한 Owner 권한.
  • 프로젝트 러너의 경우: 러너에 할당된 프로젝트에 대한 Maintainer 또는 Owner 권한.
  • 관련 그룹 또는 프로젝트에서 admin_runners 권한을 가진 사용자 지정 역할.
• manage_runner 범위와 적절한 역할을 가진 액세스 토큰.

POST /runners/:id/reset_authentication_token

curl --request POST \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "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

curl --request POST \
     --form "token=<current token>" \
     --url "https://gitlab.example.com/api/v4/runners/reset_authentication_token"

응답 예시:

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

Job Router 정보 검색#

히스토리

• GitLab 18.7에 job_router 및 job_router_instance_runners 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.

러너의 Job Router 검색 정보를 조회합니다.

사전 요구 사항:

• 유효한 러너 인증 토큰을 제공해야 합니다.

GET /runners/router/discovery

curl --header "Runner-Token: <runner_authentication_token>" \
     --url "https://gitlab.example.com/api/v4/runners/router/discovery"

응답:

응답에는 다음 필드가 포함됩니다.

응답은 다음 상태 코드 중 하나를 반환합니다.

응답 예시:

{
    "server_url": "wss://kas.example.com"
}