正式なドキュメントは英語版であり、この日本語訳はAI支援翻訳により作成された参考用のものです。日本語訳の一部の内容は人間によるレビューがまだ行われていないため、翻訳のタイミングにより英語版との間に差異が生じることがあります。最新かつ正確な情報については、英語版をご参照ください。

Runner API

  • プラン: Free、Premium、Ultimate
  • 提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

このAPIを使用して、インスタンスに登録されているRunnerを管理します。

新規のインスタンス、グループ、またはプロジェクトのRunnerを作成するには、POST /user/runnersエンドポイントを使用します。既存のRunnerを管理するには、このAPIを使用します。

ページネーションは、次のAPIエンドポイント（デフォルトでは20個のアイテムを返します）で使用できます。

GET /runners
GET /runners/all
GET /runners/:id/jobs
GET /projects/:id/runners
GET /groups/:id/runners

登録と認証トークン

RunnerをGitLabに接続するには、2つのトークンが必要です。

トークン説明
登録トークン（レガシー）Runnerを登録するために使用するトークン。GitLabを通じて取得できます。
認証トークンGitLabインスタンスでRunnerを認証するために使用するトークン。このトークンは、ユーザーがRunnerを登録すると、自動的に取得されます。つまり、ユーザーが手動でRunnerを登録するか、認証トークンをリセットすると、Runners APIによって自動的に取得されます。POST /user/runnersエンドポイントを使用しても、トークンを取得できます。

次に、Runnerの登録にトークンを使用する方法の例を示します。

  1. GitLab APIと登録トークンを使用してRunnerを登録し、認証トークンを受け取ります。

  2. 認証トークンをRunnerの設定ファイルに追加します。

    [[runners]]
  token = "<authentication_token>"

これで、GitLabとRunnerが接続されます。

利用可能なすべてのRunnerを一覧表示

ユーザーが利用可能なすべてのRunnerを一覧表示します。

前提条件:

  • グループRunnerの場合、オーナーのネームスペースでオーナーロールが必要です。
  • プロジェクトRunnerの場合、Runnerが割り当てられているプロジェクトでセキュリティマネージャー、メンテナー、またはオーナーロールが必要です。
GET /runners
GET /runners?scope=active
GET /runners?type=project_type
GET /runners?status=online
GET /runners?paused=true
GET /runners?tag_list=tag1,tag2
属性型必須説明
scope文字列いいえ非推奨。代わりに、typeまたはstatusを使用してください。返されるRunnerのスコープ（active、paused、online、offlineのいずれか）。指定されていない場合は、すべてのRunnerが表示されます
type文字列いいえ返されるRunnerのタイプ（instance_type、group_type、project_typeのいずれか）
status文字列いいえ返されるRunnerの状態（online、offline、stale、never_contactedのいずれか）。
その他の可能な値は、非推奨のactiveとpausedです。
offline Runnerをリクエストすると、staleがofflineに含まれているため、stale Runnerも返される場合があります。
pausedブール値いいえ新規ジョブを受け入れているRunnerのみを含めるか、無視しているRunnerのみを含めるか
tag_list文字列配列いいえRunnerタグのリスト
version_prefix文字列いいえ返されるRunnerのバージョンのプレフィックス。例: 15.0、14、16.1.241
curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/runners"
  • statusクエリパラメータのactiveとpausedの値は非推奨であり、REST APIの将来のバージョンで削除される予定です。代わりに、pausedクエリパラメータを使用してください。
  • 応答のactive属性は非推奨であり、REST APIの将来のバージョンで削除される予定です。代わりに、paused属性を使用してください。
  • 応答のip_address属性はGitLab 16.1で非推奨となり、REST APIの将来のバージョンで削除される予定です。GitLab 17.0では、この属性は空の文字列を返します。ipAddress属性は、それぞれのRunnerマネージャー内にあります。GraphQL CiRunnerManagerタイプでのみ利用可能です。

レスポンス例:

[
    {
        "active": true,
        "paused": false,
        "description": "test-1-20150125",
        "id": 6,
        "ip_address": "",
        "is_shared": false,
        "runner_type": "project_type",
        "name": null,
        "online": true,
        "status": "online",
        "job_execution_status": "idle"
    },
    {
        "active": true,
        "paused": false,
        "description": "test-2-20150125",
        "id": 8,
        "ip_address": "",
        "is_shared": false,
        "runner_type": "group_type",
        "name": null,
        "online": false,
        "status": "offline",
        "job_execution_status": "idle"
    }
]

すべてのRunnerを一覧表示

  • プラン: Free、Premium、Ultimate
  • 提供形態: GitLab Self-Managed、GitLab Dedicated

GitLabインスタンス内のすべてのRunner（プロジェクトと共有）を一覧表示します。

前提条件:

  • 管理者アクセスまたは監査担当者アクセスが必要です。
GET /runners/all
GET /runners/all?scope=online
GET /runners/all?type=project_type
GET /runners/all?status=online
GET /runners/all?paused=true
GET /runners/all?tag_list=tag1,tag2
属性型必須説明
scope文字列いいえ非推奨。代わりに、typeまたはstatusを使用してください。返されるRunnerのスコープ（specific、shared、active、paused、online、offlineのいずれか）指定されていない場合は、すべてのRunnerが表示されます
type文字列いいえ返されるRunnerのタイプ（instance_type、group_type、project_typeのいずれか）
status文字列いいえ返されるRunnerの状態（online、offline、stale、never_contactedのいずれか）。
その他の可能な値は、非推奨のactiveとpausedです。
offline Runnerをリクエストすると、staleがofflineに含まれているため、stale Runnerも返される場合があります。
pausedブール値いいえ新規ジョブを受け入れているRunnerのみを含めるか、無視しているRunnerのみを含めるか
tag_list文字列配列いいえRunnerタグのリスト
version_prefix文字列いいえ返されるRunnerのバージョンのプレフィックス。例: 15.0、16.1.241
curl --header "PRIVATE-TOKEN: <your_access_token>" \
curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/runners/all"

> [!warning]
> Deprecations:
>
> - The `active` and `paused` values in the `status` query parameter are deprecated
>   and scheduled for removal in [a future version of the REST API](https://gitlab.com/gitlab-org/gitlab/-/issues/351109).
>   Use the `paused` query parameter instead.
> - The `active` attribute in the response is deprecated
>   and is scheduled for removal in [a future version of the REST API](https://gitlab.com/gitlab-org/gitlab/-/issues/351109).
>   Use the `paused` attribute instead.
> - The `ip_address` attribute in the response is deprecated
>   [in GitLab 16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/415159) and is scheduled for removal in
>   [a future version of the REST API](https://gitlab.com/gitlab-org/gitlab/-/issues/351109).
>   In GitLab 17.0, this attribute returns an empty string.
>   The `ipAddress` attribute can be found inside the respective runner manager.
>   It is only available through the GraphQL
>   [`CiRunnerManager` type](graphql/reference/_index.md#cirunnermanager).

Example response:

```json
[
    {
        "active": true,
        "paused": false,
        "description": "shared-runner-1",
        "id": 1,
        "ip_address": "",
        "is_shared": true,
        "runner_type": "instance_type",
        "name": null,
        "online": true,
        "status": "online",
        "job_execution_status": "idle"
    },
    {
        "active": true,
        "paused": false,
        "description": "shared-runner-2",
        "id": 3,
        "ip_address": "",
        "is_shared": true,
        "runner_type": "instance_type",
        "name": null,
        "online": false,
        "status": "offline",
        "job_execution_status": "idle"
    },
    {
        "active": true,
        "paused": false,
        "description": "test-1-20150125",
        "id": 6,
        "ip_address": "",
        "is_shared": false,
        "runner_type": "project_type",
        "name": null,
        "online": true,
        "status": "paused",
        "job_execution_status": "idle"
    },
    {
        "active": true,
        "paused": false,
        "description": "test-2-20150125",
        "id": 8,
        "ip_address": "",
        "is_shared": false,
        "runner_type": "group_type",
        "name": null,
        "online": false,
        "status": "offline",
        "job_execution_status": "idle"
    }
]

最初の20個よりも多くのRunnerを表示するには、ページネーションを使用してください。

Runnerの詳細を取得する

Runnerの詳細を取得します。

インスタンスRunnerの詳細は、このエンドポイントを介してすべての認証済みユーザーが利用できます。

前提条件:

  • ユーザーアクセス: 次のいずれかが必要です:
    • グループRunnerの場合: オーナーのネームスペースでメンテナーまたはオーナーロール。
    • プロジェクトRunnerの場合: Runnerを所有するプロジェクトでセキュリティマネージャー、メンテナー、またはオーナーロール。
    • 関連するグループまたはプロジェクトでadmin_runnersパーミッションを持つカスタムロール。
  • manage_runnerスコープと適切なロールを持つアクセストークン。
GET /runners/:id
属性型必須説明
id整数はいRunnerのID
curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/runners/6"

レスポンス例:

{
    "active": true,
    "paused": false,
    "architecture": null,
    "description": "test-1-20150125",
    "id": 6,
    "ip_address": "",
    "is_shared": false,
    "runner_type": "project_type",
    "contacted_at": "2016-01-25T16:39:48.066Z",
    "maintenance_note": null,
    "name": null,
    "online": true,
    "status": "online",
    "job_execution_status": "idle",
    "platform": null,
    "projects": [
        {
            "id": 1,
            "name": "GitLab Community Edition",
            "name_with_namespace": "GitLab.org / GitLab Community Edition",
            "path": "gitlab-foss",
            "path_with_namespace": "gitlab-org/gitlab-foss"
        }
    ],
    "revision": null,
    "tag_list": [
        "ruby",
        "mysql"
    ],
    "version": null,
    "access_level": "ref_protected",
    "maximum_timeout": 3600
}

Runnerの詳細を更新

Runnerの詳細を更新します。

PUT /runners/:id

前提条件:

  • ユーザーアクセス: 次のいずれかが必要です:
    • インスタンスRunnerの場合: GitLabインスタンスへの管理者アクセス。
    • グループRunnerの場合: オーナーのネームスペースでオーナーロール。
    • プロジェクトRunnerの場合: Runnerが割り当てられているプロジェクトでメンテナーまたはオーナーロール。
    • 関連するグループまたはプロジェクトでadmin_runnersパーミッションを持つカスタムロール。
  • manage_runnerスコープと適切なロールを持つアクセストークン。
属性型必須説明
id整数はいRunnerのID
description文字列いいえRunnerの説明
activeブール値いいえ非推奨。代わりに、pausedを使用してください。Runnerがジョブの受信を許可されているかどうかを示すフラグ
pausedブール値いいえRunnerが新規ジョブを無視する必要があるかどうかを指定します
tag_list配列いいえRunnerのタグのリスト
run_untaggedブール値いいえタグ付けされていないジョブをRunnerが実行できるかどうかを指定します
lockedブール値いいえRunnerがロックされるかどうかを指定します
access_level文字列いいえRunnerのアクセスレベル（not_protectedまたはref_protected）
maximum_timeout整数いいえRunnerがジョブを実行できる時間（秒単位）を制限する最大タイムアウト
maintenance_note文字列いいえRunnerの自由形式のメンテナンスノート（1024文字）
curl --request PUT \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/runners/6" \
     --form "description=test-1-20150125-test" \
     --form "tag_list=ruby,mysql,tag1,tag2"

レスポンス例:

{
    "active": true,
    "architecture": null,
    "description": "test-1-20150125-test",
    "id": 6,
    "ip_address": "",
    "is_shared": false,
    "runner_type": "group_type",
    "contacted_at": "2016-01-25T16:39:48.066Z",
    "maintenance_note": null,
    "name": null,
    "online": true,
    "status": "online",
    "job_execution_status": "idle",
    "platform": null,
    "projects": [
        {
            "id": 1,
            "name": "GitLab Community Edition",
            "name_with_namespace": "GitLab.org / GitLab Community Edition",
            "path": "gitlab-foss",
            "path_with_namespace": "gitlab-org/gitlab-foss"
        }
    ],
    "revision": null,
    "tag_list": [
        "ruby",
        "mysql",
        "tag1",
        "tag2"
    ],
    "version": null,
    "access_level": "ref_protected",
    "maximum_timeout": null
}

Runnerを一時停止する

Runnerを一時停止します。

前提条件:

  • ユーザーアクセス: 次のいずれかが必要です:
    • インスタンスRunnerの場合: GitLabインスタンスへの管理者アクセス。
    • グループRunnerの場合: オーナーのネームスペースでオーナーロール。
    • プロジェクトRunnerの場合: Runnerが割り当てられているプロジェクトでメンテナーまたはオーナーロール。
    • 関連するグループまたはプロジェクトでadmin_runnersパーミッションを持つカスタムロール。
  • manage_runnerスコープと適切なロールを持つアクセストークン。
PUT --form "paused=true" /runners/:runner_id

# --or--

# Deprecated: removal planned in 16.0
PUT --form "active=false" /runners/:runner_id
属性型必須説明
runner_id整数はいRunnerのID
curl --request PUT \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --form "paused=true"  \
     --url "https://gitlab.example.com/api/v4/runners/6"

# --or--

# Deprecated: removal planned in 16.0
curl --request PUT \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --form "active=false"  \
     --url "https://gitlab.example.com/api/v4/runners/6"

Runnerが処理したすべてのジョブを一覧表示

指定されたRunnerによって処理中または処理済みであったすべてのジョブを一覧表示します。ジョブのリストは、ユーザーがレポーター、デベロッパー、メンテナー、またはオーナーロールを持っているプロジェクトに限定されます。

GET /runners/:id/jobs
属性型必須説明
id整数はいRunnerのID
system_id文字列いいえRunnerマネージャーが実行されているマシンのシステムID
status文字列いいえジョブの状態（running、success、failed、canceledのいずれか）
order_by文字列いいえidでジョブを順序付けます
sort文字列いいえascまたはdesc順にジョブを並べ替えます（デフォルト: desc）。sortが指定されている場合は、order_byも指定する必要があります
curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/runners/1/jobs?status=running"

レスポンス例:

[
    {
        "id": 2,
        "status": "running",
        "stage": "test",
        "name": "test",
        "ref": "main",
        "tag": false,
        "coverage": null,
        "created_at": "2017-11-16T08:50:29.000Z",
        "started_at": "2017-11-16T08:51:29.000Z",
        "finished_at": "2017-11-16T08:53:29.000Z",
        "duration": 120,
        "queued_duration": 2,
        "user": {
            "id": 1,
            "name": "John Doe2",
            "username": "user2",
            "state": "active",
            "avatar_url": "http://www.gravatar.com/avatar/c922747a93b40d1ea88262bf1aebee62?s=80&d=identicon",
            "web_url": "http://localhost/user2",
            "created_at": "2017-11-16T18:38:46.000Z",
            "bio": null,
            "location": null,
            "public_email": "",
            "linkedin": "",
            "twitter": "",
            "website_url": "",
            "organization": null
        },
        "commit": {
            "id": "97de212e80737a608d939f648d959671fb0a0142",
            "short_id": "97de212e",
            "title": "Update configuration\r",
            "created_at": "2017-11-16T08:50:28.000Z",
            "parent_ids": [
                "1b12f15a11fc6e62177bef08f47bc7b5ce50b141",
                "498214de67004b1da3d820901307bed2a68a8ef6"
            ],
            "message": "See merge request !123",
            "author_name": "John Doe2",
            "author_email": "user2@example.org",
            "authored_date": "2017-11-16T08:50:27.000Z",
            "committer_name": "John Doe2",
            "committer_email": "user2@example.org",
            "committed_date": "2017-11-16T08:50:27.000Z"
        },
        "pipeline": {
            "id": 2,
            "sha": "97de212e80737a608d939f648d959671fb0a0142",
            "ref": "main",
            "status": "running"
        },
        "project": {
            "id": 1,
            "description": null,
            "name": "project1",
            "name_with_namespace": "John Doe2 / project1",
            "path": "project1",
            "path_with_namespace": "namespace1/project1",
            "created_at": "2017-11-16T18:38:46.620Z"
        }
    }
]

すべてのRunnerのマネージャーを一覧表示

Runnerのすべてのマネージャーを一覧表示します。

GET /runners/:id/managers
属性型必須説明
id整数はいRunnerのID
curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/runners/1/managers"

レスポンス例:

[
    {
      "id": 1,
      "system_id": "s_89e5e9956577",
      "version": "16.11.1",
      "revision": "535ced5f",
      "platform": "linux",
      "architecture": "amd64",
      "created_at": "2024-06-09T11:12:02.507Z",
      "contacted_at": "2024-06-09T06:30:09.355Z",
      "ip_address": "127.0.0.1",
      "status": "offline",
      "job_execution_status": "idle"
    },
    {
      "id": 2,
      "system_id": "runner-2",
      "version": "16.11.0",
      "revision": "91a27b2a",
      "platform": "linux",
      "architecture": "amd64",
      "created_at": "2024-06-09T09:12:02.507Z",
      "contacted_at": "2024-06-09T06:30:09.355Z",
      "ip_address": "127.0.0.1",
      "status": "offline",
      "job_execution_status": "idle"
    }
]

プロジェクトのすべてのRunnerを一覧表示

プロジェクトで利用可能なすべてのRunnerを、祖先グループや許可されているインスタンスRunnerを含めて一覧表示します。

前提条件:

  • GitLabインスタンスの管理者であるか、ターゲットプロジェクトでメンテナーまたは監査担当者ロール以上を持っている必要があります。
GET /projects/:id/runners
GET /projects/:id/runners?scope=active
GET /projects/:id/runners?type=project_type
GET /projects/:id/runners?status=online
GET /projects/:id/runners?paused=true
GET /projects/:id/runners?tag_list=tag1,tag2
属性型必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス
scope文字列いいえ非推奨。代わりに、typeまたはstatusを使用してください。返されるRunnerのスコープ（active、paused、online、offlineのいずれか）。指定されていない場合は、すべてのRunnerが表示されます
type文字列いいえ返されるRunnerのタイプ（instance_type、group_type、project_typeのいずれか）
status文字列いいえ返されるRunnerの状態（online、offline、stale、never_contactedのいずれか）。
その他の可能な値は、非推奨のactiveとpausedです。
offline Runnerをリクエストすると、staleがofflineに含まれているため、stale Runnerも返される場合があります。
pausedブール値いいえ新規ジョブを受け入れているRunnerのみを含めるか、無視しているRunnerのみを含めるか
tag_list文字列配列いいえRunnerタグのリスト
version_prefix文字列いいえ返されるRunnerのバージョンのプレフィックス。例: 15.0、14、16.1.241
curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/projects/9/runners"
  • statusクエリパラメータのactiveとpausedの値は非推奨であり、REST APIの将来のバージョンで削除される予定です。代わりに、pausedクエリパラメータを使用してください。
  • 応答のactive属性は非推奨であり、REST APIの将来のバージョンで削除される予定です。代わりに、paused属性を使用してください。
  • 応答のip_address属性はGitLab 16.1で非推奨となり、REST APIの将来のバージョンで削除される予定です。GitLab 17.0では、この属性は空の文字列を返します。ipAddress属性は、それぞれのRunnerマネージャー内にあります。GraphQL CiRunnerManagerタイプでのみ利用可能です。

レスポンス例:

[
    {
        "active": true,
        "paused": false,
        "description": "test-2-20150125",
        "id": 8,
        "ip_address": "",
        "is_shared": false,
        "runner_type": "project_type",
        "name": null,
        "online": false,
        "status": "offline",
        "job_execution_status": "idle"
    },
    {
        "active": true,
        "paused": false,
        "description": "development_runner",
        "id": 5,
        "ip_address": "",
        "is_shared": true,
        "runner_type": "instance_type",
        "name": null,
        "online": true,
        "status": "online",
        "job_execution_status": "idle"
    }
]

Runnerをプロジェクトに割り当てる

利用可能なプロジェクトRunnerをプロジェクトに割り当てます。

前提条件:

  • ユーザーアクセス: 次のいずれかが必要です:

    • Runnerを所有するプロジェクトおよびターゲットプロジェクトでメンテナーまたはオーナーロール。
    • 関連するグループまたはプロジェクトでadmin_runnersパーミッションを持つカスタムロール。
POST /projects/:id/runners
属性型必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス
runner_id整数はいRunnerのID
curl --request POST \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/projects/9/runners" \
     --form "runner_id=9"

レスポンス例:

{
    "active": true,
    "description": "test-2016-02-01",
    "id": 9,
    "ip_address": "",
    "is_shared": false,
    "runner_type": "project_type",
    "name": null,
    "online": true,
    "status": "online",
    "job_execution_status": "idle"
}

プロジェクトからRunnerの割り当てを解除

プロジェクトからプロジェクトRunnerの割り当てを解除します。オーナープロジェクトからRunnerの割り当てを解除することはできません。このアクションを試みると、エラーが発生します。代わりに、Runnerの削除への呼び出しを使用します。

前提条件:

  • 管理者でない限り、Runnerをロックしてはいけません。
  • ユーザーアクセス: 次のいずれかが必要です:
    • 割り当てを解除したいプロジェクトでメンテナーまたはオーナーロール。
    • 関連するグループまたはプロジェクトでadmin_runnersパーミッションを持つカスタムロール。
  • manage_runnerスコープと適切なロールを持つアクセストークン。
DELETE /projects/:id/runners/:runner_id
属性型必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス
runner_id整数はいRunnerのID
curl --request DELETE \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/projects/9/runners/9"

グループのすべてのRunnerを一覧表示

グループおよびその祖先グループで利用可能なすべてのRunnerを、許可されているインスタンスRunnerを含めて一覧表示します。

前提条件:

  • ユーザーアクセス: 次のいずれかが必要です:
    • GitLabインスタンスへの管理者アクセス。
    • グループでオーナーまたは監査担当者ロール。
    • グループでadmin_runnersパーミッションを持つカスタムロール。
  • manage_runnerスコープと適切なロールを持つアクセストークン。
GET /groups/:id/runners
GET /groups/:id/runners?type=group_type
GET /groups/:id/runners/all?status=online
GET /groups/:id/runners/all?paused=true
GET /groups/:id/runners?tag_list=tag1,tag2
属性型必須説明
id整数はいグループのID
type文字列いいえ返されるRunnerのタイプ（instance_type、group_type、project_typeのいずれか）。project_type値は非推奨であり、GitLab 15.0で削除される予定です
status文字列いいえ返されるRunnerの状態（online、offline、stale、never_contactedのいずれか）。
その他の可能な値は、非推奨のactiveとpausedです。
offline Runnerをリクエストすると、staleがofflineに含まれているため、stale Runnerも返される場合があります。
pausedブール値いいえ新規ジョブを受け入れているRunnerのみを含めるか、無視しているRunnerのみを含めるか
tag_list文字列配列いいえRunnerタグのリスト
version_prefix文字列いいえ返されるRunnerのバージョンのプレフィックス。例: 15.0、14、16.1.241
  • statusクエリパラメータのactiveとpausedの値は非推奨であり、REST APIの将来のバージョンで削除される予定です。代わりに、pausedクエリパラメータを使用してください。
  • 応答のactive属性は非推奨であり、REST APIの将来のバージョンで削除される予定です。代わりに、paused属性を使用してください。
curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/groups/9/runners"

レスポンス例:

[
  {
    "id": 3,
    "description": "Shared",
    "ip_address": "",
    "active": true,
    "paused": false,
    "is_shared": true,
    "runner_type": "instance_type",
    "name": "gitlab-runner",
    "online": null,
    "status": "never_contacted",
    "job_execution_status": "idle"
  },
  {
    "id": 6,
    "description": "Test",
    "ip_address": "",
    "active": true,
    "paused": false,
    "is_shared": true,
    "runner_type": "instance_type",
    "name": "gitlab-runner",
    "online": false,
    "status": "offline",
    "job_execution_status": "idle"
  },
  {
    "id": 8,
    "description": "Test 2",
    "ip_address": "",
    "active": true,
    "paused": false,
    "is_shared": false,
    "runner_type": "group_type",
    "name": "gitlab-runner",
    "online": null,
    "status": "never_contacted",
    "job_execution_status": "idle"
  }
]

Runnerを作成する

Runner登録トークンを使用してRunnerを作成します。

このエンドポイントは、Runner登録トークンを使用した登録がプロジェクト設定またはグループ設定で無効になっている場合、HTTP 410 Gone状態コードを返します。Runner登録トークンを使用した登録が無効になっている場合は、POST /user/runnersエンドポイントを使用して、Runnerを作成して登録します。

POST /runners
属性型必須説明
token文字列はい登録トークン
description文字列いいえRunnerの説明
infoハッシュいいえRunnerのメタデータ。name、version、revision、platform、architectureを含めることができますが、UIの管理者エリアには、version、platform、architectureのみが表示されます
activeブール値いいえ非推奨。代わりに、pausedを使用してください。Runnerに新規ジョブの受信を許可するかどうかを指定します
pausedブール値いいえRunnerが新規ジョブを無視する必要があるかどうかを指定します
lockedブール値いいえ現在のプロジェクトに対してRunnerをロックする必要があるかどうかを指定します
run_untaggedブール値いいえタグ付けされていないジョブをRunnerが処理する必要があるかどうかを指定します
tag_list文字列配列いいえRunnerタグのリスト
access_level文字列いいえRunnerのアクセスレベル（not_protectedまたはref_protected）
maximum_timeout整数いいえRunnerがジョブを実行できる時間（秒単位）を制限する最大タイムアウト
maintainer_note文字列いいえ非推奨。maintenance_noteを参照してください
maintenance_note文字列いいえRunnerの自由形式のメンテナンスノート（1024文字）
curl --request POST \
     --url "https://gitlab.example.com/api/v4/runners" \
     --form "token=<registration_token>" --form "description=test-1-20150125-test" \
     --form "tag_list=ruby,mysql,tag1,tag2"

応答:

状態説明
201Runnerが作成されました
403無効なRunner登録トークン
410Runner登録が無効になっています

レスポンス例:

{
    "id": 12345,
    "token": "6337ff461c94fd3fa32ba3b1ff4125",
    "token_expires_at": "2021-09-27T21:05:03.203Z"
}

Runnerを削除する

次の要素を指定して、Runnerを削除できます。

  • RunnerのID
  • Runnerの認証トークン

IDでRunnerを削除

IDでRunnerを削除するには、アクセストークンとRunnerのIDを使用します。

前提条件:

  • ユーザーアクセス: 次のいずれかが必要です:
    • インスタンスRunnerの場合: GitLabインスタンスへの管理者アクセス。
    • グループRunnerの場合: オーナーのネームスペースでオーナーロール。
    • プロジェクトRunnerの場合: Runnerを所有するプロジェクトでメンテナーまたはオーナーロール。
    • 関連するグループまたはプロジェクトでadmin_runnersパーミッションを持つカスタムロール。
  • manage_runnerスコープと適切なロールを持つアクセストークン。
DELETE /runners/:id
属性型必須説明
id整数はいRunnerのID。IDはUIの設定 > CI/CDで確認できます。Runnersを展開すると、Runnerの削除の下にポンド記号で始まるIDが表示されます（例: #6）。
curl --request DELETE \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/runners/6"

認証トークンでRunnerを削除

Runnerの認証トークンを使用してRunnerを削除します。

DELETE /runners
属性型必須説明
token文字列はいRunnerの認証トークン。
curl --request DELETE \
     --url "https://gitlab.example.com/api/v4/runners" \
     --form "token=<authentication_token>"

応答:

状態説明
204Runnerが削除されました

登録済みのランナーの認証を検証

登録済みRunnerの認証情報を検証します。

POST /runners/verify
属性型必須説明
token文字列はいRunnerの認証トークン。
system_id文字列いいえRunnerのシステム識別子。この属性は、tokenがglrt-で始まる場合に必須です。
curl --request POST \
     --url "https://gitlab.example.com/api/v4/runners/verify" \
     --form "token=<authentication_token>"

応答:

状態説明
200認証情報が有効です
403認証情報が無効です

レスポンス例:

{
    "id": 12345,
    "token": "glrt-6337ff461c94fd3fa32ba3b1ff4125",
    "token_expires_at": "2021-09-27T21:05:03.203Z"
}

インスタンスのRunner登録トークンをリセット

詳細については、新しいRunner登録ワークフローに移行するを参照してください。

GitLabインスタンスのRunner登録トークンをリセットします。

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

プロジェクトのRunner登録トークンをリセット

プロジェクトのRunner登録トークンをリセットします。

POST /projects/:id/runners/reset_registration_token
curl --request POST \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/projects/9/runners/reset_registration_token"

グループのRunner登録トークンをリセット

グループのRunner登録トークンをリセットします。

POST /groups/:id/runners/reset_registration_token
curl --request POST \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/groups/9/runners/reset_registration_token"

Runner IDを使用してRunnerのRunner認証トークンをリセット

Runner IDを使用して、Runnerの認証トークンをリセットします。

前提条件:

  • ユーザーアクセス: 次のいずれかが必要です:
    • インスタンスRunnerの場合: GitLabインスタンスへの管理者アクセス。
    • グループRunnerの場合: オーナーのネームスペースでオーナーロール。
    • プロジェクトRunnerの場合: Runnerが割り当てられているプロジェクトでメンテナーまたはオーナーロール。
    • 関連するグループまたはプロジェクトでadmin_runnersパーミッションを持つカスタムロール。
  • manage_runnerスコープと適切なロールを持つアクセストークン。
POST /runners/:id/reset_authentication_token
属性型必須説明
id整数はいRunnerのID
curl --request POST \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/runners/1/reset_authentication_token"

レスポンス例:

{
    "token": "6337ff461c94fd3fa32ba3b1ff4125",
    "token_expires_at": "2021-09-27T21:05:03.203Z"
}

現在のトークンを使用してRunnerの認証トークンをリセット

現在のトークンの値をインプットとして使用して、Runnerの認証トークンをリセットします。

POST /runners/reset_authentication_token
属性型必須説明
token文字列はいRunnerの認証トークン
curl --request POST \
     --form "token=<current token>" \
     --url "https://gitlab.example.com/api/v4/runners/reset_authentication_token"

レスポンス例:

{
    "token": "6337ff461c94fd3fa32ba3b1ff4125",
    "token_expires_at": "2021-09-27T21:05:03.203Z"
}

Job Router情報を検出

RunnerのJob Router検出情報を取得します。

前提条件:

  • 有効なRunner認証トークンを指定する必要があります。
GET /runners/router/discovery
curl --header "Runner-Token: <runner_authentication_token>" \
     --url "https://gitlab.example.com/api/v4/runners/router/discovery"

応答:

レスポンスには次のフィールドが含まれます:

属性型説明
server_url文字列Job RouterへのURL

レスポンスは次のいずれかのステータスコードを返します:

状態説明
200Job Router情報が正常に取得されました
403禁止
501Job Routerは利用できません

レスポンス例:

{
    "server_url": "wss://kas.example.com"
}