背景

Service accountはGitLab上で使えるアカウントの1種で、人間ではなくマシンユーザーとして利用できるものです。またService accountはPremiumプランから利用できますが、ライセンスシートを消費することなく利用できます。

Service accountの特徴の一つに、有効期限なしのPersonal access tokenを作成できる点があります。Personal access tokenはGitLabが発行するトークンの1つで、トークンの中でも最も多くのリソース種に権限を付与できるものです。例えばPersonal access tokenはGitLab APIも操作可能なため、CI/CDパイプラインからGitLab APIにリクエストを送る必要がある場面では必要となります。

ただし通常のPersonal access tokenでは、最大でも1年の有効期限が設定されます。そのため、気づかないうちにトークンの期限を過ぎ、CI/CDパイプラインが失敗する、という可能性もあるでしょう。Service accountを使うことで、こういった事態を避けられます。

なお、作成できるService accountの個数は、利用するプランによって制限があります。

Freeプラン: 利用できません。
Premiumプラン: 所持する有償シートごとに1つ作成できます。
Ultimateプラン: 作成上限はなく、いくつでも作成できます。

検証

ここからService accountを簡単に検証します。

Service accountを作成するには、GitLab APIから操作する必要があります。以降の操作をするため、事前に api スコープのトークンを作成します。

Service accountを作成するには、以下のようにGitLabの /groups/:id/service_accounts というAPIにPOSTリクエストを投げます。

docs.gitlab.com

# Service accountの作成
$ curl --request POST \
       --header "PRIVATE-TOKEN: <GitLab token>" \
                "https://gitlab.com/api/v4/groups/<Group ID>/service_accounts"

# 整形した結果を載せます
{
    "id": 22049837,
    "username": "service_account_group_<Group ID>_57dc5819b5919ffe034aaedba96a4928",
    "name": "Service account user"
}

# Service accountの確認
$ curl --request GET \
       --header "PRIVATE-TOKEN: <GitLab token>" \
                "https://gitlab.com/api/v4/groups/<Group ID>/service_accounts"

[
    {
        "id": 22049837,
        "username": "service_account_group_<Group ID>_57dc5819b5919ffe034aaedba96a4928",
        "name": "Service account user"
    }
]

次にService accountを使ってPersonal access tokenを発行します。Personal access tokenの作成は /groups/:id/service_accounts/:user_id/personal_access_tokens に対してPOSTリクエストを投げます。

docs.gitlab.com

なおこの時点ではPersonal access tokenの有効期限は設定されており、 expires_at という項目を見ると1年後に設定されています。有効期限のないトークンを作成する方法は後程紹介します。

$ curl --request POST \
       --header "PRIVATE-TOKEN: <GitLab token>" \
                "https://gitlab.com/api/v4/groups/<Group ID>/service_accounts/22049837/personal_access_tokens" \
       --data "scopes[]=api,read_user,read_repository" \
       --data "name=service_accounts_token_20240713"

# 整形した結果を載せます
{
    "id": 10231130,
    "name": "service_accounts_token_20240713",
    "revoked": false,
    "created_at": "2024-07-13T00:22:01.095Z",
    "scopes": [
        "api",
        "read_user",
        "read_repository"
    ],
    "user_id": 22049837,
    "last_used_at": null,
    "active": true,
    "expires_at": "2025-07-13", # 有効期限は作成日から1年後に設定されている
    "token": "<Personal access token 1>"
}

作成したPersonal access tokenを使うには、操作対象のGroupにService accountを追加します。

Service accountをGroupに追加することで、先ほどのPersonal access tokenを使いアクセス可能となります。

# Personal access tokenを使った操作の例
# Group内Projectのイベントを取得
$ curl --request GET \
       --header "PRIVATE-TOKEN: <Personal access token 1>" \
                "https://gitlab.com/api/v4/projects/<Project ID>/events" | jq

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  7268  100  7268    0     0  16518      0 --:--:-- --:--:-- --:--:-- 16555
[
  {
    "id": 3320991404,
    "project_id": <Project ID>,
    "action_name": "closed",
    "target_id": 298226506,
    "target_iid": 1,
    "target_type": "MergeRequest",
    (省略)
    },
    (省略)
]

次に、有効期限のないPersonal access tokenを作成します。はじめにService accountのPersonal access tokenの有効期限を無効化するため、GitLab Groupの 設定 → 一般 に移動し、権限とグループ機能を開きます。

権限とグループ機能からサービスアクセストークンの有効期限まで移動します。デフォルトではチェックマークが埋まっているので、これを外して保存します。

設定変更後、改めてPersonal access tokenを作成します。すると、作成したトークンのexpires_atがnullとなっており、有効期限が設定されていないことを確認できます。

$ curl --request POST \
       --header "PRIVATE-TOKEN: <GitLab token>" \
                "https://gitlab.com/api/v4/groups/<Group ID>/service_accounts/22049837/personal_access_tokens" \
       --data "scopes[]=api,read_user,read_repository" \
       --data "name=service_accounts_token_20240713_no_expiry"

# 整形した結果を載せます
{
    "id": 10231169,
    "name": "service_accounts_token_20240713_no_expiry",
    "revoked": false,
    "created_at": "2024-07-13T00:49:35.795Z",
    "scopes": [
        "api",
        "read_user",
        "read_repository"
    ],
    "user_id": 22049837,
    "last_used_at": null,
    "active": true,
    "expires_at": null, # 有効期限が設定されていない
    "token": "<Personal access token 2>"
}

先に作ったトークンと比較してみます。

$ curl --header "PRIVATE-TOKEN: <Personal access token 1>" \
                "https://gitlab.com/api/v4/personal_access_tokens" | jq

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   503  100   503    0     0   1552      0 --:--:-- --:--:-- --:--:--  1547
[
  {
    "id": 10231130,
    "name": "service_accounts_token_20240713",
    "revoked": false,
    "created_at": "2024-07-13T00:22:01.095Z",
    "scopes": [
      "api",
      "read_user",
      "read_repository"
    ],
    "user_id": 22049837,
    "last_used_at": "2024-07-13T00:53:33.189Z",
    "active": true,
    "expires_at": "2025-07-13" # 有効期限が設定されている
  },
  {
    "id": 10231169,
    "name": "service_accounts_token_20240713_no_expiry",
    "revoked": false,
    "created_at": "2024-07-13T00:49:35.795Z",
    "scopes": [
      "api",
      "read_user",
      "read_repository"
    ],
    "user_id": 22049837,
    "last_used_at": null,
    "active": true,
    "expires_at": null # 有効期限が設定されていない
  }
]

検証後は必要に応じてService account / Personal access tokenの無効化や削除を実施してください。

# Personal access tokenの無効化
$ curl --request DELETE \
       --header "PRIVATE-TOKEN: <無効化対象のトークン>" \
                "https://gitlab.com/api/v4/personal_access_tokens/self"

# Service accountの削除
$ curl --request DELETE \
       --header "PRIVATE-TOKEN: <GitLab token>" \
                "https://gitlab.com/api/v4/groups/<Group ID>/service_accounts/<Service account ID>"