히스토리

• GitLab 18.10에서 Free 티어에 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>" \
  --url "https://gitlab.example.com/api/v4/service_accounts"

응답 예시:

[
  {
    "id": 114,
    "username": "service_account_33",
    "public_email": "",
    "name": "Service account user",
    "email": "service_account_33@noreply.gitlab.example.com"
  },
  {
    "id": 137,
    "username": "service_account_34",
    "public_email": "",
    "name": "john doe",
    "email": "service_account_34@noreply.gitlab.example.com"
  }
]

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

히스토리

• email 속성이 GitLab 17.9에서 추가됨.
• external 속성이 GitLab 19.5에서 추가됨.

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

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",
  "public_email": "",
  "name": "Service account user",
  "email": "service_account_6018816a18e515214e0c34c2b33523fc@noreply.gitlab.example.com",
  "external": true
}

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

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

히스토리

• GitLab 18.2에서 도입됨.
• external 속성이 GitLab 19.5에서 추가됨.

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

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",
  "public_email": "",
  "name": "Updated Service Account",
  "email": "service_account_<random_hash>@noreply.gitlab.example.com",
  "external": true,
  "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>",
    "public_email": "",
    "name": "Service account user",
    "email": "service_account_group_345_<random_hash>@noreply.gitlab.example.com"
  },
  {
    "id": 58,
    "username": "service_account_group_345_<random_hash>",
    "public_email": "",
    "name": "Service account user",
    "email": "service_account_group_345_<random_hash>@noreply.gitlab.example.com",
    "unconfirmed_email": "custom_email@example.com"
  }
]

그룹 서비스 계정 조회#

지정한 그룹의 서비스 계정 하나를 조회합니다.

GET /groups/:id/service_accounts/:user_id

지원되는 속성:

성공하면 200 OK와 다음 응답 속성을 반환합니다.

그룹에 해당 서비스 계정이 없으면 404 Not Found를 반환하고, 사용자가 그룹에 있지만 서비스 계정이 아니면 400 Bad Request를 반환합니다.

요청 예시:

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

응답 예시:

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

그룹 서비스 계정 생성#

히스토리

• 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",
  "public_email": "",
  "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>" \
  --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",
  "public_email": "",
  "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에서 도입됨.
• 응답의 last_used_ips가 GitLab 19.4에서 도입됨.

지정한 그룹에 있는 서비스 계정의 모든 개인 액세스 토큰 목록을 조회합니다.

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,
        "last_used_ips": [],
        "active": true,
        "expires_at": null
    }
]

실패 응답 예시:

• 401: Unauthorized
• 404 Group Not Found

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

히스토리

• 응답의 last_used_ips가 GitLab 19.4에서 도입됨.

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

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,
  "last_used_ips":[],
  "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 — 액세스 토큰이 존재하지 않는 경우.

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

히스토리

• 응답의 last_used_ips가 GitLab 19.4에서 도입됨.
• 응답의 granular_scopes가 GitLab 19.5에서 도입됨.

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

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,
  "last_used_ips":[],
  "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>",
    "public_email": "",
    "name": "Service account user",
    "email": "service_account_project_345_<random_hash>@noreply.gitlab.example.com"
  },
  {
    "id": 58,
    "username": "service_account_project_345_<random_hash>",
    "public_email": "",
    "name": "Service account user",
    "email": "service_account_project_345_<random_hash>@noreply.gitlab.example.com",
    "unconfirmed_email": "custom_email@example.com"
  }
]

프로젝트 서비스 계정 조회#

지정한 프로젝트의 서비스 계정 하나를 조회합니다.

GET /projects/:id/service_accounts/:user_id

지원되는 속성:

성공하면 200 OK와 다음 응답 속성을 반환합니다.

프로젝트에 해당 서비스 계정이 없으면 404 Not Found를 반환합니다.

요청 예시:

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

응답 예시:

{
  "id": 57,
  "username": "service_account_project_345_6018816a18e515214e0c34c2b33523fc",
  "public_email": "",
  "name": "Service account user",
  "email": "service_account_project_345_6018816a18e515214e0c34c2b33523fc@noreply.gitlab.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",
  "public_email": "",
  "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",
  "public_email": "",
  "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"

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

히스토리

• 응답의 last_used_ips가 GitLab 19.4에서 도입됨.

프로젝트에 있는 서비스 계정의 모든 개인 액세스 토큰 목록을 조회합니다.

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,
        "last_used_ips": [],
        "active": true,
        "expires_at": null
    }
]

실패 응답 예시:

• 401: Unauthorized
• 404 Project Not Found

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

히스토리

• 응답의 last_used_ips가 GitLab 19.4에서 도입됨.

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

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,
  "last_used_ips":[],
  "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 — 액세스 토큰이 존재하지 않는 경우.

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

히스토리

• 응답의 last_used_ips가 GitLab 19.4에서 도입됨.
• 응답의 granular_scopes가 GitLab 19.5에서 도입됨.

지정한 프로젝트에 있는 기존 서비스 계정의 개인 액세스 토큰을 교체합니다. 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,
  "last_used_ips":[],
  "active":true,
  "expires_at":"2023-06-20",
  "token":"<token_value>"
}