RunnerコントローラートークンAPI

プラン: Ultimate
提供形態: GitLab Self-Managed、GitLab Dedicated
ステータス: 実験的機能

RunnerコントローラートークンAPIを使用すると、Runnerコントローラーの認証トークンを管理できます。Runnerコントローラーはこれらのトークンを使用して、GitLabインスタンスで認証を行い、Runnerを管理します。このAPIは、トークンを作成、一覧表示、ローテーション、失効するためのエンドポイントを提供します。

前提条件:

GitLabインスタンスへの管理者アクセス権が必要です。

すべてのRunnerコントローラートークンを一覧表示する

すべてのRunnerコントローラートークンを一覧表示します。

GET /runner_controllers/:id/tokens

パラメータは以下のとおりです。

属性	型	必須	説明
`id`	整数	はい	RunnerコントローラーのID。

応答:

成功した場合、200 OKと次のレスポンス属性を返します:

属性	型	説明
`id`	整数	Runnerコントローラートークンの固有識別子。
`runner_controller_id`	整数	関連付けられたRunnerコントローラーのID。
`description`	文字列	トークンの説明。
`created_at`	日時	トークンが作成された日時。
`updated_at`	日時	トークンが最後に更新された日時。

リクエスト例:

curl --request GET \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/runner_controllers/:id/tokens"

レスポンス例:

[
    {
        "id": 1,
        "runner_controller_id": 1,
        "description": "Token for runner controller",
        "created_at": "2026-01-01T00:00:00Z",
        "updated_at": "2026-01-02T00:00:00Z"
    },
    {
        "id": 2,
        "runner_controller_id": 1,
        "description": "Another token for runner controller",
        "created_at": "2026-01-03T00:00:00Z",
        "updated_at": "2026-01-04T00:00:00Z"
    }
]

単一のRunnerコントローラートークンを取得する

IDで特定のRunnerコントローラートークンの詳細を取得します。

GET /runner_controllers/:id/tokens/:token_id

パラメータは以下のとおりです。

属性	型	必須	説明
`id`	整数	はい	RunnerコントローラーのID。
`token_id`	整数	はい	RunnerコントローラートークンのID。

応答:

成功した場合、次のフィールドを含む200 OKを返します:

属性	型	説明
`id`	整数	Runnerコントローラートークンの固有識別子。
`runner_controller_id`	整数	関連付けられたRunnerコントローラーのID。
`description`	文字列	トークンの説明。
`created_at`	日時	トークンが作成された日時。
`updated_at`	日時	トークンが最後に更新された日時。

リクエスト例:

curl --request GET \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/runner_controllers/:id/tokens/:token_id"

レスポンス例:

{
    "id": 1,
    "runner_controller_id": 1,
    "description": "Token for runner controller",
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-02T00:00:00Z"
}

Runnerコントローラートークンを作成する

新しいRunnerコントローラートークンを作成します。

POST /runner_controllers/:id/tokens

パラメータは以下のとおりです。

属性	型	必須	説明
`id`	整数	はい	RunnerコントローラーのID。

サポートされている属性:

属性	型	必須	説明
`description`	文字列	はい	トークンの説明。

応答:

成功した場合、次の属性を持つ201 Createdを返します:

属性	型	説明
`id`	整数	Runnerコントローラートークンの固有識別子。
`runner_controller_id`	整数	関連付けられたRunnerコントローラーのID。
`description`	文字列	トークンの説明。
`created_at`	日時	トークンが作成された日時。
`updated_at`	日時	トークンが最後に更新された日時。
`token`	文字列	認証に使用される実際のトークン値。

リクエスト例:

curl --request POST \
    --header "PRIVATE-TOKEN: <your_access_token>" \
    --header "Content-Type: application/json" \
    --data '{"description": "Token for runner controller"}' \
    --url "https://gitlab.example.com/api/v4/runner_controllers/:id/tokens"

レスポンス例:

{
    "id": 1,
    "runner_controller_id": 1,
    "description": "Token for runner controller",
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z",
    "token": "glrct-<token>"
}

Runnerコントローラートークンを失効させる

既存のRunnerコントローラートークンを失効させます。

DELETE /runner_controllers/:id/tokens/:token_id

パラメータは以下のとおりです。

属性	型	必須	説明
`id`	整数	はい	RunnerコントローラーのID。
`token_id`	整数	はい	RunnerコントローラートークンのID。

成功した場合は、204 No Contentを返します。

curl --request DELETE \
    --header "PRIVATE-TOKEN: <your_access_token>" \
    --url "https://gitlab.example.com/api/v4/runner_controllers/:id/tokens/:token_id"

Runnerコントローラートークンをローテーションする

既存のRunnerコントローラートークンをローテーションします。

POST /runner_controllers/:id/tokens/:token_id/rotate

パラメータは以下のとおりです。

属性	型	必須	説明
`id`	整数	はい	RunnerコントローラーのID。
`token_id`	整数	はい	RunnerコントローラートークンのID。

応答:

成功した場合、次の属性を持つ200 OKを返します:

属性	型	説明
`id`	整数	Runnerコントローラートークンの固有識別子。
`runner_controller_id`	整数	関連付けられたRunnerコントローラーのID。
`description`	文字列	トークンの説明。
`created_at`	日時	トークンが作成された日時。
`updated_at`	日時	トークンが最後に更新された日時。
`token`	文字列	認証に使用される実際のトークン値。

リクエスト例:

curl --request POST \
    --header "PRIVATE-TOKEN: <your_access_token>" \
    --url "https://gitlab.example.com/api/v4/runner_controllers/:id/tokens/:token_id/rotate"

レスポンス例:

{
    "id": 1,
    "runner_controller_id": 1,
    "description": "Token for runner controller",
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z",
    "token": "glrct-<token>"
}