히스토리

• GitLab 18.10에서 Free 티어에 service_accounts_available_on_free_or_unlicensed 플래그와 함께 도입됨.

기본적으로 비활성화됨.

• GitLab 18.11에서 Free 티어에 일반적으로 사용 가능해짐. 기능 플래그 service_accounts_available_on_free_or_unlicensed 제거됨.

서비스 계정 API#

이 API를 사용하여 서비스 계정과 상호 작용할 수 있습니다.

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

• GitLab Premium 및 Ultimate에서는 모든 오퍼링에 대해 무제한으로 서비스 계정을 생성할 수 있습니다.

• GitLab Free에서는 오퍼링에 따라 제한이 다릅니다:

GitLab.com의 경우, 각 최상위 그룹당 최대 100개의 서비스 계정을 생성할 수 있습니다. 여기에는 하위 그룹이나 프로젝트에서 생성된 서비스 계정도 포함됩니다.

• GitLab Self-Managed의 경우, 인스턴스당 최대 100개의 서비스 계정을 생성할 수 있습니다. 여기에는 프로비저닝 방식(인스턴스, 그룹, 프로젝트 수준)에 관계없이 모든 서비스 계정이 포함됩니다.

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

인스턴스 서비스 계정#

DETAILS: Offering: GitLab Self-Managed, GitLab Dedicated

인스턴스 서비스 계정은 전체 GitLab 인스턴스에서 사용할 수 있지만, 일반 사용자처럼 그룹 및 프로젝트에 추가되어야 합니다.

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

사전 요구 사항:

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

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

히스토리

• GitLab 17.1에서 모든 서비스 계정 목록 조회 기능이 도입됨.

지정된 인스턴스의 모든 서비스 계정 목록을 반환합니다.

page 및 per_page 페이지네이션 파라미터를 사용하여 결과를 필터링할 수 있습니다.

GET /service_accounts

지원되는 속성:

요청 예시:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "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>" \
  --url "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>" \
  --url "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>" \
  --url "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>" \
  --url "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에서 복합 ID를 가진 서비스 계정의 사용자 이름 제한이 추가됨.

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

• 복합 ID와 연결된 서비스 계정의 사용자 이름은 업데이트할 수 없습니다.

PATCH /groups/:id/service_accounts/:user_id

파라미터:

요청 예시:

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