히스토리

• Free 티어에서 GitLab 18.10에 service_accounts_available_on_free_or_unlicensed 플래그와 함께 도입되었습니다.
• GitLab 18.11에서 Free 티어에서 일반 사용 가능해졌습니다.

이 API를 사용하여 서비스 계정과 상호 작용합니다.

생성할 수 있는 서비스 계정 수는 구독 및 오퍼링에 따라 다릅니다:

• GitLab Premium 및 Ultimate에서는 모든 오퍼링에 대해 무제한으로 서비스 계정을 생성할 수 있습니다.
• GitLab Free에서는 오퍼링별로 제한이 다릅니다:
  • GitLab.com의 경우 각 최상위 그룹에 대해 최대 100개의 서비스 계정을 생성할 수 있습니다. 하위 그룹 또는 프로젝트에서 생성된 서비스 계정도 포함됩니다.
  • GitLab Self-Managed의 경우 인스턴스당 최대 100개의 서비스 계정을 생성할 수 있습니다. 프로비저닝 방법(인스턴스, 그룹 또는 프로젝트 수준)과 관계없이 모든 서비스 계정이 포함됩니다.

사용자 API를 통해서도 서비스 계정과 상호 작용할 수 있습니다. 서비스 계정의 SSH 키를 관리하려면 사용자 SSH 및 GPG 키 API를 사용하세요.

인스턴스 서비스 계정#

인스턴스 서비스 계정은 전체 GitLab 인스턴스에서 사용할 수 있지만, 사람 사용자처럼 여전히 그룹과 프로젝트에 추가해야 합니다.

인스턴스 서비스 계정의 개인 액세스 토큰을 관리하려면 개인 액세스 토큰 API를 사용하세요.

전제 조건:

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

모든 인스턴스 서비스 계정 목록 조회#

히스토리

• GitLab 17.1에서 모든 서비스 계정 나열이 도입되었습니다.

모든 인스턴스 서비스 계정을 나열합니다.

결과를 필터링하려면 page와 per_page 페이지 매김 매개변수를 사용하세요.

GET /service_accounts

지원되는 속성:

요청 예시:

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

응답 예시:

[
  {
    "id": 114,
    "username": "service_account_33",
    "name": "Service account user"
  },
  {
    "id": 137,
    "username": "service_account_34",
    "name": "john doe"
  }
]

인스턴스 서비스 계정 생성#

히스토리

• GitLab 16.1에서 도입되었습니다.
• username 및 name 속성이 GitLab 16.10에서 추가되었습니다.
• email 속성이 GitLab 17.9에서 추가되었습니다.

인스턴스 서비스 계정을 생성합니다.

POST /service_accounts
POST /service_accounts?email=custom_email@gitlab.example.com

지원되는 속성:

요청 예시:

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

응답 예시:

{
  "id": 57,
  "username": "service_account_6018816a18e515214e0c34c2b33523fc",
  "name": "Service account user",
  "email": "service_account_6018816a18e515214e0c34c2b33523fc@noreply.gitlab.example.com"
}

email 속성으로 정의된 이메일 주소가 다른 사용자가 이미 사용 중이면 400 Bad request 오류를 반환합니다.

인스턴스 서비스 계정 업데이트#

히스토리

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

지정된 인스턴스 서비스 계정을 업데이트합니다.

PATCH /service_accounts/:id

매개변수:

요청 예시:

curl --request PATCH --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/service_accounts/57" --data "name=Updated Service Account&email=updated_email@example.com"

응답 예시:

{
  "id": 57,
  "username": "service_account_6018816a18e515214e0c34c2b33523fc",
  "name": "Updated Service Account",
  "email": "service_account_<random_hash>@noreply.gitlab.example.com",
  "unconfirmed_email": "custom_email@example.com"
}

그룹 서비스 계정#

히스토리

• 하위 그룹 서비스 계정이 GitLab 18.10에서 allow_subgroups_to_create_service_accounts 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화.
• 하위 그룹 서비스 계정이 GitLab 18.11에서 일반 사용 가능해졌습니다. 기능 플래그 allow_subgroups_to_create_service_accounts가 제거되었습니다.

그룹 서비스 계정은 특정 그룹이 소유하며, 생성된 그룹이나 하위 그룹 또는 프로젝트에 초대할 수 있습니다. 상위 그룹에는 초대할 수 없습니다.

전제 조건:

• GitLab.com에서는 그룹에 대한 Owner 역할이 있어야 합니다.
• GitLab Self-Managed 또는 GitLab Dedicated에서는 다음 중 하나여야 합니다:
  • 인스턴스의 관리자.
  • 그룹에서 Owner 역할이 있고 서비스 계정을 생성할 수 있는 권한이 있어야 합니다.

모든 그룹 서비스 계정 목록 조회#

히스토리

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

지정된 그룹의 모든 서비스 계정을 나열합니다.

결과를 필터링하려면 page와 per_page 페이지 매김 매개변수를 사용하세요.

GET /groups/:id/service_accounts

매개변수:

요청 예시:

curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/345/service_accounts"

응답 예시:

[

  {
    "id": 57,
    "username": "service_account_group_345_<random_hash>",
    "name": "Service account user",
    "email": "service_account_group_345_<random_hash>@noreply.gitlab.example.com"
  },
  {
    "id": 58,
    "username": "service_account_group_345_<random_hash>",
    "name": "Service account user",
    "email": "service_account_group_345_<random_hash>@noreply.gitlab.example.com",
    "unconfirmed_email": "custom_email@example.com"
  }
]

그룹 서비스 계정 생성#

히스토리

• GitLab 16.1에서 도입되었습니다.
• username 및 name 속성이 GitLab 16.10에서 추가되었습니다.
• email 속성이 GitLab 17.9에서 group_service_account_custom_email 플래그와 함께 추가되었습니다.
• email 속성이 GitLab 17.11에서 일반 사용 가능해졌습니다. group_service_account_custom_email 기능 플래그가 제거되었습니다.

지정된 그룹에 서비스 계정을 생성합니다.

POST /groups/:id/service_accounts

지원되는 속성:

요청 예시:

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/345/service_accounts" --data "email=custom_email@example.com"

응답 예시:

{
  "id": 57,
  "username": "service_account_group_345_6018816a18e515214e0c34c2b33523fc",
  "name": "Service account user",
  "email": "custom_email@example.com"
}

그룹 서비스 계정 업데이트#

히스토리

• GitLab 17.10에서 도입되었습니다.
• 커스텀 이메일 주소 추가가 GitLab 18.2에서 도입되었습니다.
• GitLab 18.9에서 컴포짓 아이덴티티가 있는 서비스 계정의 사용자명 제한이 추가되었습니다.

지정된 그룹의 서비스 계정을 업데이트합니다.

PATCH /groups/:id/service_accounts/:user_id

매개변수:

요청 예시:

curl --request PATCH --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/345/service_accounts/57" --data "name=Updated Service Account&email=updated_email@example.com"

응답 예시:

{
  "id": 57,
  "username": "service_account_group_345_6018816a18e515214e0c34c2b33523fc",
  "name": "Updated Service Account",
  "email": "service_account_group_345_<random_hash>@noreply.gitlab.example.com",
  "unconfirmed_email": "custom_email@example.com"
}

그룹 서비스 계정 삭제#

히스토리

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

지정된 그룹에서 서비스 계정을 삭제합니다.

DELETE /groups/:id/service_accounts/:user_id

매개변수:

요청 예시:

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/345/service_accounts/181"

그룹 서비스 계정의 모든 개인 액세스 토큰 목록 조회#

히스토리

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

지정된 그룹의 서비스 계정에 대한 모든 개인 액세스 토큰을 나열합니다.

GET /groups/:id/service_accounts/:user_id/personal_access_tokens

지원되는 속성:

요청 예시:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/187/service_accounts/195/personal_access_tokens?sort=id_desc&search=token2b&created_before=2025-03-27"

응답 예시:

[
    {
        "id": 187,
        "name": "service_accounts_token2b",
        "revoked": false,
        "created_at": "2025-03-26T14:42:51.084Z",
        "description": null,
        "scopes": [
            "api"
        ],
        "user_id": 195,
        "last_used_at": null,
        "active": true,
        "expires_at": null
    }
]

실패 응답 예시:

• 401: Unauthorized
• 404 Group Not Found

그룹 서비스 계정의 개인 액세스 토큰 생성#

히스토리

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

지정된 그룹의 기존 서비스 계정에 대한 개인 액세스 토큰을 생성합니다.

POST /groups/:id/service_accounts/:user_id/personal_access_tokens

매개변수:

요청 예시:

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/35/service_accounts/71/personal_access_tokens" --data "scopes[]=api,read_user,read_repository" --data "name=service_accounts_token"

응답 예시:

{
  "id":6,
  "name":"service_accounts_token",
  "revoked":false,
  "created_at":"2023-06-13T07:47:13.900Z",
  "scopes":["api"],
  "user_id":71,
  "last_used_at":null,
  "active":true,
  "expires_at":"2024-06-12",
  "token":"<token_value>"
}

그룹 서비스 계정의 개인 액세스 토큰 취소#

히스토리

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

그룹의 기존 서비스 계정에 대한 지정된 개인 액세스 토큰을 취소합니다.

DELETE /groups/:id/service_accounts/:user_id/personal_access_tokens/:token_id

매개변수:

요청 예시:

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/35/service_accounts/71/personal_access_tokens/6"

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

기타 가능한 응답:

• 400: Bad Request (성공적으로 취소되지 않은 경우)
• 401: Unauthorized (요청이 승인되지 않은 경우)
• 403: Forbidden (요청이 허용되지 않는 경우)
• 404: Not Found (액세스 토큰이 존재하지 않는 경우)

그룹 서비스 계정의 개인 액세스 토큰 교체#

히스토리

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

지정된 그룹의 기존 서비스 계정에 대한 지정된 개인 액세스 토큰을 교체합니다. 이 작업은 기존 토큰을 취소하고 동일한 이름, 설명, 스코프로 새 토큰을 생성합니다.

POST /groups/:id/service_accounts/:user_id/personal_access_tokens/:token_id/rotate

매개변수:

요청 예시:

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/35/service_accounts/71/personal_access_tokens/6/rotate"

응답 예시:

{
  "id":7,
  "name":"service_accounts_token",
  "revoked":false,
  "created_at":"2023-06-13T07:54:49.962Z",
  "scopes":["api"],
  "user_id":71,
  "last_used_at":null,
  "active":true,
  "expires_at":"2023-06-20",
  "token":"<token_value>"
}

프로젝트 서비스 계정#

히스토리

• GitLab 18.9에서 allow_projects_to_create_service_accounts 플래그와 함께 도입되었습니다. 기본적으로 비활성화.
• 프로젝트 서비스 계정이 GitLab 18.11에서 일반 사용 가능해졌습니다. 기능 플래그 allow_projects_to_create_service_accounts가 제거되었습니다.

프로젝트 서비스 계정은 특정 프로젝트가 소유하며 연결된 프로젝트에서만 사용할 수 있습니다.

전제 조건:

• GitLab.com에서는 프로젝트에 대한 Maintainer 또는 Owner 역할이 있어야 합니다.
• GitLab Self-Managed 또는 GitLab Dedicated에서는 다음 중 하나여야 합니다:
  • 인스턴스의 관리자.
  • 프로젝트에서 Maintainer 또는 Owner 역할이 있어야 합니다.

모든 프로젝트 서비스 계정 목록 조회#

지정된 프로젝트의 모든 서비스 계정을 나열합니다.

결과를 필터링하려면 page와 per_page 페이지 매김 매개변수를 사용하세요.

GET /projects/:id/service_accounts

매개변수:

요청 예시:

curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/345/service_accounts"

응답 예시:

[

  {
    "id": 57,
    "username": "service_account_project_345_<random_hash>",
    "name": "Service account user",
    "email": "service_account_project_345_<random_hash>@noreply.gitlab.example.com"
  },
  {
    "id": 58,
    "username": "service_account_project_345_<random_hash>",
    "name": "Service account user",
    "email": "service_account_project_345_<random_hash>@noreply.gitlab.example.com",
    "unconfirmed_email": "custom_email@example.com"
  }
]

프로젝트 서비스 계정 생성#

지정된 프로젝트에 서비스 계정을 생성합니다.

POST /projects/:id/service_accounts

지원되는 속성:

요청 예시:

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/345/service_accounts" --data "email=custom_email@example.com"

응답 예시:

{
  "id": 57,
  "username": "service_account_project_345_6018816a18e515214e0c34c2b33523fc",
  "name": "Service account user",
  "email": "custom_email@example.com"
}

프로젝트 서비스 계정 업데이트#

지정된 프로젝트의 서비스 계정을 업데이트합니다.

PATCH /projects/:id/service_accounts/:user_id

매개변수:

요청 예시:

curl --request PATCH --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/345/service_accounts/57" --data "name=Updated Service Account&email=updated_email@example.com"

응답 예시:

{
  "id": 57,
  "username": "service_account_project_345_6018816a18e515214e0c34c2b33523fc",
  "name": "Updated Service Account",
  "email": "service_account_project_345_<random_hash>@noreply.gitlab.example.com",
  "unconfirmed_email": "custom_email@example.com"
}

프로젝트 서비스 계정 삭제#

지정된 프로젝트에서 서비스 계정을 삭제합니다.

DELETE /projects/:id/service_accounts/:user_id

매개변수:

요청 예시:

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/345/service_accounts/181"

프로젝트 서비스 계정의 모든 개인 액세스 토큰 목록 조회#

프로젝트의 서비스 계정에 대한 모든 개인 액세스 토큰을 나열합니다.

GET /projects/:id/service_accounts/:user_id/personal_access_tokens

지원되는 속성:

요청 예시:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/187/service_accounts/195/personal_access_tokens?sort=id_desc&search=token2b&created_before=2025-03-27"

응답 예시:

[
    {
        "id": 187,
        "name": "service_accounts_token2b",
        "revoked": false,
        "created_at": "2025-03-26T14:42:51.084Z",
        "description": null,
        "scopes": [
            "api"
        ],
        "user_id": 195,
        "last_used_at": null,
        "active": true,
        "expires_at": null
    }
]

실패 응답 예시:

• 401: Unauthorized
• 404 Project Not Found

프로젝트 서비스 계정의 개인 액세스 토큰 생성#

지정된 프로젝트의 기존 서비스 계정에 대한 개인 액세스 토큰을 생성합니다.

POST /projects/:id/service_accounts/:user_id/personal_access_tokens

매개변수:

요청 예시:

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/35/service_accounts/71/personal_access_tokens" --data "scopes[]=api,read_user,read_repository" --data "name=service_accounts_token"

응답 예시:

{
  "id":6,
  "name":"service_accounts_token",
  "revoked":false,
  "created_at":"2023-06-13T07:47:13.900Z",
  "scopes":["api"],
  "user_id":71,
  "last_used_at":null,
  "active":true,
  "expires_at":"2024-06-12",
  "token":"<token_value>"
}

프로젝트 서비스 계정의 개인 액세스 토큰 취소#

지정된 프로젝트의 기존 서비스 계정에 대한 개인 액세스 토큰을 취소합니다.

DELETE /projects/:id/service_accounts/:user_id/personal_access_tokens/:token_id

매개변수:

요청 예시:

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/35/service_accounts/71/personal_access_tokens/6"

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

기타 가능한 응답:

• 400: Bad Request (성공적으로 취소되지 않은 경우)
• 401: Unauthorized (요청이 승인되지 않은 경우)
• 403: Forbidden (요청이 허용되지 않는 경우)
• 404: Not Found (액세스 토큰이 존재하지 않는 경우)

프로젝트 서비스 계정의 개인 액세스 토큰 교체#

지정된 프로젝트의 기존 서비스 계정에 대한 개인 액세스 토큰을 교체합니다. 이 작업은 1주 동안 유효한 새 토큰을 생성하고 기존 토큰을 모두 취소합니다.

POST /projects/:id/service_accounts/:user_id/personal_access_tokens/:token_id/rotate

매개변수:

요청 예시:

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/35/service_accounts/71/personal_access_tokens/6/rotate"

응답 예시:

{
  "id":7,
  "name":"service_accounts_token",
  "revoked":false,
  "created_at":"2023-06-13T07:54:49.962Z",
  "scopes":["api"],
  "user_id":71,
  "last_used_at":null,
  "active":true,
  "expires_at":"2023-06-20",
  "token":"<token_value>"
}