ランナーAPI

ページネーションは以下のAPIエンドポイントで利用可能です（デフォルトでは20個のアイテムを返します）：

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

登録および認証トークン

GitLab と Runner を接続する際に考慮すべきトークンが 2 つあります。

トークン説明
登録トークン ランナーの登録に使用するトークン。GitLab から取得できます。
認証トークンGitLab インスタンスでランナーを認証するために使用するトークン。ランナーを登録するときに自動的に取得されるか、手動でランナーを登録するときや認証トークンをリセットするときに Runner API によって取得されます。また、Create a runnerAPI メソッドを使用して認証トークンを取得することもできます。

以下は、ランナー登録で二つのトークンがどのように使われるかの例です：

  1. 登録トークンを使って GitLab API から Runner を登録すると、認証トークンが返されます。

  2. その認証トークンを使ってRunner の設定ファイルに追加します：

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

GitLab と 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 を使用してください。返すランナーの範囲：active paused,online andoffline; ランナーがない場合はすべてのランナーを表示します。
type文字列です。いいえ返すランナーのタイプ：instance_type group_type 、project_type
status文字列です。いいえ返すランナーのステータス：online offline,stale,never_contacted.active とpaused も指定可能な値ですが、GitLab 14.8 で非推奨となり、GitLab 16.0 で削除される予定です。
pausedbooleanいいえ新しいジョブを受け入れているランナーのみを含めるか、無視しているランナーのみを含めるか。
tag_list文字列配列いいえランナータグのリスト
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners"
note
status クエリパラメータのactive とpaused の値はGitLab 14.8 で非推奨となり、GitLab 16.0で削除される予定です。これらはpaused クエリパラメータで置き換えられます。
note
レスポンスのactive 属性はGitLab 14.8で非推奨となり、GitLab 16.0で削除される予定です。paused 属性に置き換えられます。

応答例

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

全ランナーのリスト

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 を使用してください。返すランナーの範囲：specific shared,active,paused,online andoffline; もし指定がなければ、すべてのランナーを表示します。
type文字列です。いいえ返すランナーのタイプ：instance_type group_type 、project_type
status文字列です。いいえ返すランナーのステータス：online offline,stale,never_contacted.active とpaused も指定可能な値ですが、GitLab 14.8 で非推奨となり、GitLab 16.0 で削除される予定です。
pausedbooleanいいえ新しいジョブを受け入れているランナーのみを含めるか、無視しているランナーのみを含めるか。
tag_list文字列配列いいえランナータグのリスト
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/all"
note
status クエリパラメータのactive とpaused の値はGitLab 14.8 で非推奨となり、GitLab 16.0で削除される予定です。これらはpaused クエリパラメータで置き換えられます。
note
レスポンスのactive 属性はGitLab 14.8で非推奨となり、GitLab 16.0で削除される予定です。paused 属性に置き換えられます。

応答例

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

最初の20人以上のランナーを表示するには、ページネーションを使用してください。

ランナーの詳細を見る

ランナーの詳細を取得します。

プロジェクトおよびグループレベルでランナーの詳細を取得するには、少なくともメンテナーのロールが必要です。

このエンドポイントを介したインスタンスレベルのランナーの詳細は、認証されたすべてのユーザーが利用できます。

GET /runners/:id
属性種類必須説明
id整数。yesランナーのID
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6"
note
レスポンスのtoken 属性はGitLab 12.10 で非推奨となり、GitLab 13.0 で削除されました。
note
レスポンスのactive 属性はGitLab 14.8で非推奨となり、GitLab 16.0で削除される予定です。paused 属性に置き換えられます。

応答例

{
    "active": true,
    "paused": false,
    "architecture": null,
    "description": "test-1-20150125",
    "id": 6,
    "ip_address": "127.0.0.1",
    "is_shared": false,
    "runner_type": "project_type",
    "contacted_at": "2016-01-25T16:39:48.066Z",
    "name": null,
    "online": true,
    "status": "online",
    "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
}

ランナーの詳細の更新

ランナーの詳細を更新します。

PUT /runners/:id
属性種類必須説明
id整数。yesランナーのID
description文字列です。いいえランナーの説明
activebooleanいいえ非推奨：代わりにpaused を使用してください。ランナーがジョブを受け取ることを許可されているかどうかを示すフラグ
pausedbooleanいいえランナーが新しいジョブを無視するかどうかを指定します。
tag_listアレイいいえランナーのタグのリスト
run_untaggedbooleanいいえランナーがタグなしジョブを実行できるかどうかを指定します。
lockedbooleanいいえランナーがロックされているかどうかを指定します。
access_level文字列です。いいえランナーのアクセスレベル。not_protected またはref_protected
maximum_timeout整数。いいえランナーがジョブを実行できる時間（秒）を制限する最大タイムアウト
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6" \
     --form "description=test-1-20150125-test" --form "tag_list=ruby,mysql,tag1,tag2"
note
レスポンスのtoken 属性は GitLab 12.10 で非推奨となり、GitLab 13.0 で削除されました。
note
active クエリパラメータはGitLab 14.8 で非推奨となり、GitLab 16.0 で削除される予定です。paused 属性に置き換えられます。

応答例

{
    "active": true,
    "architecture": null,
    "description": "test-1-20150125-test",
    "id": 6,
    "ip_address": "127.0.0.1",
    "is_shared": false,
    "runner_type": "group_type",
    "contacted_at": "2016-01-25T16:39:48.066Z",
    "name": null,
    "online": true,
    "status": "online",
    "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
}

ランナーの一時停止

ランナーを一時停止します。

PUT --form "paused=true" /runners/:runner_id

# --or--

# Deprecated: removal planned in 16.0
PUT --form "active=false" /runners/:runner_id
属性種類必須説明
runner_id整数。yesランナーのID
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
     --form "paused=true"  "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"  "https://gitlab.example.com/api/v4/runners/6"
note
active form属性はGitLab 14.8で非推奨となり、GitLab 16.0で削除される予定です。paused 属性に置き換えられます。

ランナーのジョブ一覧

GitLab 10.3から導入されました。

指定されたランナーによって処理中または処理されたジョブをリストします。ジョブのリストは、ユーザーが少なくともレポーターロールを持っているプロジェクトに限定されます。

GET /runners/:id/jobs
属性種類必須説明
id整数。yesランナーのID
status文字列です。いいえジョブのステータス：running,success,failed 、canceled
order_by文字列です。いいえジョブの順序id
sort文字列です。いいえジョブをasc またはdesc 順序で desc並べ替えますdesc (デフォルト: desc)。id を含め、order_by も指定してください。
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/1/jobs?status=running"

応答例

[
    {
        "id": 2,
        "ip_address": "127.0.0.1",
        "status": "running",
        "stage": "test",
        "name": "test",
        "ref": "master",
        "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,
        "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": "",
            "skype": "",
            "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": "master",
            "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 をリストアップします。

祖先グループと許可された共有ランナーを含む、プロジェクトで利用可能なすべてのランナーをリストします。

GET /projects/:id/runners
GET /projects/:id/runners?scope=active
GET /projects/:id/runners?type=project_type
GET /projects/:id/runners/all?status=online
GET /projects/:id/runners/all?paused=true
GET /projects/:id/runners?tag_list=tag1,tag2
属性種類必須説明
id整数/文字列yes認証ユーザーが所有するプロジェクトのIDまたはURLエンコードされたパス
scope文字列です。いいえ非推奨：代わりにtype またはstatus を使用してください。返すランナーの範囲：active paused,online andoffline; ランナーがない場合はすべてのランナーを表示します。
type文字列です。いいえ返すランナーのタイプ：instance_type group_type 、project_type
status文字列です。いいえ返すランナーのステータス：online offline,stale,never_contacted.active とpaused も指定可能な値ですが、GitLab 14.8 で非推奨となり、GitLab 16.0 で削除される予定です。
pausedbooleanいいえ新しいジョブを受け入れているランナーのみを含めるか、無視しているランナーのみを含めるか。
tag_list文字列配列いいえランナータグのリスト
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners"
note
status クエリパラメータのactive とpaused の値はGitLab 14.8 で非推奨となり、GitLab 16.0で削除される予定です。これらはpaused クエリパラメータで置き換えられます。
note
レスポンスのactive 属性はGitLab 14.8で非推奨となり、GitLab 16.0で削除される予定です。paused 属性に置き換えられます。

応答例

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

プロジェクトの Runner を有効にします。

プロジェクトで利用可能なプロジェクトRunnerを有効にします。

POST /projects/:id/runners
属性種類必須説明
id整数/文字列yes認証ユーザーが所有するプロジェクトのIDまたはURLエンコードされたパス
runner_id整数。yesランナーのID
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners" \
     --form "runner_id=9"

応答例

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

プロジェクトからランナーを無効にします。

プロジェクトからランナーを無効にします。プロジェクトが指定されたランナーに関連付けられている唯一のプロジェクトでない場合にのみ機能します。その場合はエラーが返されます。代わりにランナーを削除するコールを使用してください。

DELETE /projects/:id/runners/:runner_id
属性種類必須説明
id整数/文字列yes認証ユーザーが所有するプロジェクトのIDまたはURLエンコードされたパス
runner_id整数。yesランナーのID
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners/9"

グループのランナー一覧

グループとその祖先グループで使用可能なすべてのRunnerを、許可された共有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整数。yes認証ユーザーが所有するグループのID
type文字列です。いいえ返すランナーのタイプ：instance_type group_type,project_type.この project_type値は非推奨で、GitLab 15.0 で削除される予定です。
status文字列です。いいえ返すランナーのステータス：online offline,stale,never_contacted.active とpaused も指定可能な値ですが、GitLab 14.8 で非推奨となり、GitLab 16.0 で削除される予定です。
pausedbooleanいいえ新しいジョブを受け入れているランナーのみを含めるか、無視しているランナーのみを含めるか。
tag_list文字列配列いいえランナータグのリスト
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/9/runners"
note
status クエリパラメータのactive とpaused の値はGitLab 14.8 で非推奨となり、GitLab 16.0で削除される予定です。これらはpaused クエリパラメータで置き換えられます。
note
レスポンスのactive 属性はGitLab 14.8で非推奨となり、GitLab 16.0で削除される予定です。paused 属性に置き換えられます。

応答例

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

新しいランナーの登録

インスタンスに新しい Runner を登録します。

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

レスポンス

ステータス説明
201ランナー誕生
403無効なランナー登録トークン
410ランナー登録が無効です。

応答例

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

ランナーの削除

ランナーを削除するには、2つの方法があります：

  • ランナーIDを指定する方法。
  • ランナーの認証トークンを指定します。

IDによるランナーの削除

IDでランナーを削除するには、アクセストークンとランナーのIDを使用してください：

DELETE /runners/:id
属性種類必須説明
id整数。yesランナーのID。IDは、UIの[設定] > [CI/CD]に表示されます。Runners を展開し、Remove Runnerボタンの下に、例えば、#6のように、パウンド記号が先行する ID が表示されます。
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6"

認証トークンによるランナーの削除

認証トークンを使用してランナーを削除します：

DELETE /runners
属性種類必須説明
token文字列です。yesランナーの認証トークン。
curl --request DELETE "https://gitlab.example.com/api/v4/runners" \
     --form "token=<authentication_token>"

レスポンス

ステータス説明
204ランナーが削除されました。

登録されたランナーの認証の確認

登録されたランナーの認証情報を検証します。

POST /runners/verify
属性種類必須説明
token文字列です。yesランナーの認証トークン。
system_id文字列です。いいえランナーのシステム識別子。token がglrt-で始まる場合、この属性は必須です。
curl --request POST "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"
}

インスタンスのランナー登録トークンのリセット

GitLab 14.3で導入されました。

caution
ランナー登録トークンと特定の設定引数のサポートはGitLab 15.6で非推奨となり、GitLab 17.0で削除される予定です。GitLab 17.0以降、ランナー登録トークンをリセットすることはできなくなり、reset_registration_token エンドポイントは機能しなくなります。

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

POST /runners/reset_registration_token

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

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

GitLab 14.3で導入されました。

caution
ランナー登録トークンと特定の設定引数のサポートはGitLab 15.6で非推奨となり、GitLab 17.0で削除される予定です。GitLab 17.0以降、ランナー登録トークンをリセットすることはできなくなり、](https://gitlab.com/gitlab-org/gitlab/-/issues/380872) エンドポイントは機能しなくなります。

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

POST /projects/:id/runners/reset_registration_token

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

グループのランナー登録トークンのリセット

GitLab 14.3で導入されました。

caution
ランナー登録トークンと特定の設定引数のサポートはGitLab 15.6で非推奨となり、GitLab 17.0で削除される予定です。GitLab 17.0以降、ランナー登録トークンをリセットすることはできなくなり、reset_registration_token エンドポイントは機能しなくなります。

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

POST /groups/:id/runners/reset_registration_token

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

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

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

POST /runners/:id/reset_authentication_token
属性種類必須説明
id整数。yesランナーのID
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/runners/1/reset_authentication_token"

応答例

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

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

現在のトークンの値を入力として、ランナーの認証トークンをリセットします。

POST /runners/reset_authentication_token
属性種類必須説明
token文字列です。yesランナーの認証トークン
curl --request POST --form "token=<current token>" \
     "https://gitlab.example.com/api/v4/runners/reset_authentication_token"

応答例

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