RunnerコントローラーAPI

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

RunnerコントローラーAPIを使用すると、GitLab Runnerジョブのオーケストレーションとアドミッションコントロール用のRunnerコントローラーを管理できます。このAPIは、Runnerコントローラーを作成、読み取り、更新、削除するためのエンドポイントを提供します。

前提条件:

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

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

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

GET /runner_controllers

応答:

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

属性	型	説明
`id`	整数	Runnerコントローラーの固有識別子。
`description`	文字列	Runnerコントローラーの説明。
`state`	文字列	Runnerコントローラーの状態。有効な値は、`disabled`（デフォルト）、`enabled`、または`dry_run`です。
`created_at`	日時	Runnerコントローラーが作成された日時。
`updated_at`	日時	Runnerコントローラーが最後に更新された日時。

リクエスト例:

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

レスポンス例:

[
    {
        "id": 1,
        "description": "Runner controller",
        "state": "enabled",
        "created_at": "2026-01-01T00:00:00Z",
        "updated_at": "2026-01-02T00:00:00Z"
    },
    {
        "id": 2,
        "description": "Another runner controller",
        "state": "disabled",
        "created_at": "2026-01-03T00:00:00Z",
        "updated_at": "2026-01-04T00:00:00Z"
    }
]

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

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

GET /runner_controllers/:id

応答:

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

属性	型	説明
`id`	整数	Runnerコントローラーの固有識別子。
`description`	文字列	Runnerコントローラーの説明。
`state`	文字列	Runnerコントローラーの状態。有効な値は、`disabled`（デフォルト）、`enabled`、または`dry_run`です。
`created_at`	日時	Runnerコントローラーが作成された日時。
`updated_at`	日時	Runnerコントローラーが最後に更新された日時。

リクエスト例:

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

レスポンス例:

{
    "id": 1,
    "description": "Runner controller",
    "state": "enabled",
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-02T00:00:00Z"
}

Runnerコントローラーを登録

新しいRunnerコントローラーを登録します。

POST /runner_controllers

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

属性	型	必須	説明
`description`	文字列	いいえ	Runnerコントローラーの説明。
`state`	文字列	いいえ	Runnerコントローラーの状態。有効な値は、`disabled`（デフォルト）、`enabled`、または`dry_run`です。

応答:

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

属性	型	説明
`id`	整数	Runnerコントローラーの固有識別子。
`description`	文字列	Runnerコントローラーの説明。
`state`	文字列	Runnerコントローラーの状態。有効な値は、`disabled`（デフォルト）、`enabled`、または`dry_run`です。
`created_at`	日時	Runnerコントローラーが作成された日時。
`updated_at`	日時	Runnerコントローラーが最後に更新された日時。

リクエスト例:

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

レスポンス例:

{
    "id": 3,
    "description": "New runner controller",
    "state": "dry_run",
    "created_at": "2026-01-05T00:00:00Z",
    "updated_at": "2026-01-05T00:00:00Z"
}

Runnerコントローラーを更新

IDで既存のRunnerコントローラーの詳細を更新します。

PUT /runner_controllers/:id

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

属性	型	必須	説明
`description`	文字列	いいえ	Runnerコントローラーの説明。
`state`	文字列	いいえ	Runnerコントローラーの状態。有効な値は、`disabled`（デフォルト）、`enabled`、または`dry_run`です。

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

属性	型	説明
`id`	整数	Runnerコントローラーの固有識別子。
`description`	文字列	Runnerコントローラーの説明。
`state`	文字列	Runnerコントローラーの状態。有効な値は、`disabled`（デフォルト）、`enabled`、または`dry_run`です。
`created_at`	日時	Runnerコントローラーが作成された日時。
`updated_at`	日時	Runnerコントローラーが最後に更新された日時。

リクエスト例:

curl --request PUT \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --data '{"description": "Updated runner controller", "state": "enabled"}' \
     --url "https://gitlab.example.com/api/v4/runner_controllers/3"

レスポンス例:

{
    "id": 3,
    "description": "Updated runner controller",
    "state": "enabled",
    "created_at": "2026-01-05T00:00:00Z",
    "updated_at": "2026-01-06T00:00:00Z"
}

Runnerコントローラーを削除

IDで特定のRunnerコントローラーを削除します。

DELETE /runner_controllers/:id

成功すると、204 No Contentを返します。

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