ランナーAPI

GitLab 8.5 で導入されました

登録および認証トークン

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

トークン 説明
登録トークン Runnerを登録するためのトークンです。GitLabから取得できます。
認証トークン GitLab インスタンスで Runner を認証するために使用するトークンです。Runner を登録するときに自動的に取得するか、Runners API 経由で Runner を登録するときに手動で取得します。

2つのトークンがランナー登録でどのように使用されるかの例です:

  1. 登録トークンを使って GitLab API 経由で Runner を登録すると、認証トークンが返されます。
  2. その認証トークンを使い、Runnerの設定ファイルに追加します:

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

GitLabとRunnerが接続されます。

所有ランナー一覧

ユーザーが利用できる特定のランナーのリストを取得します。

GET /runners
GET /runners?scope=active
GET /runners?type=project_type
GET /runners?status=active
GET /runners?tag_list=tag1,tag2
属性 タイプ 必須 説明
scope いいえ 非推奨: 代わりにtype またはstatus を使用してください。 表示するランナーの範囲。active,paused,online,offlineのいずれか。
type いいえ 表示するランナーのタイプ。instance_type,group_typeのいずれか、project_type
status いいえ 表示するランナーのステータス。activepausedonlineのいずれか、offline
tag_list 文字列配列 いいえ ランナーのタグ一覧
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners"

回答例

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

すべてのランナーをリストアップ

GitLabインスタンス内の全ランナー(特定および共有)のリストを取得します。 アクセスはadmin 権限を持つユーザーに制限されています。

GET /runners/all
GET /runners/all?scope=online
GET /runners/all?type=project_type
GET /runners/all?status=active
GET /runners/all?tag_list=tag1,tag2
属性 タイプ 必須 説明
scope いいえ 非推奨:type またはstatus を代わりに使用してください。 表示するランナーの範囲。specific,shared,active,paused,online,offlineのいずれか。
type いいえ 表示するランナーのタイプ。instance_type,group_typeのいずれか、project_type
status いいえ 表示するランナーのステータス。activepausedonlineのいずれか、offline
tag_list 文字列配列 いいえ ランナーのタグ一覧
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/all"

回答例

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

ランナーの詳細情報

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

GET /runners/:id
属性 タイプ 必須 説明
id 整数 はい ランナーのID
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6"
: レスポンスのtoken 属性はGitLab 12.10 で非推奨となり、GitLab 13.0で削除されました。

回答例

{
    "active": true,
    "architecture": null,
    "description": "test-1-20150125",
    "id": 6,
    "ip_address": "127.0.0.1",
    "is_shared": false,
    "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 整数 はい ランナーのID
description いいえ ランナーの説明
active ブーリアン いいえ ランナーの状態。true またはfalse
tag_list アレイ いいえ 最終的にランナーに割り当てられるタグの配列。
run_untagged ブーリアン いいえ ランナーがタグなしジョブを実行できることを示すフラグ
locked ブーリアン いいえ ランナーがロックされていることを示すフラグ
access_level いいえ ランナーのaccess_level。not_protected またはref_protected
maximum_timeout 整数 いいえ Runnerがジョブを処理する際に設定される最大タイムアウト時間
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"
: レスポンスのtoken 属性はGitLab 12.10 で非推奨となり、GitLab 13.0で削除されました。

回答例

{
    "active": true,
    "architecture": null,
    "description": "test-1-20150125-test",
    "id": 6,
    "ip_address": "127.0.0.1",
    "is_shared": false,
    "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
}

ランナーの取り外し

ランナーを取り外します。

DELETE /runners/:id
属性 タイプ 必須 説明
id 整数 はい ランナーのID
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6"

リストランナーのジョブ

GitLab 10.3から導入されました

指定されたランナーによって処理中または処理されたジョブをリストします。

GET /runners/:id/jobs
属性 タイプ 必須 説明
id 整数 はい ランナーのID
status いいえ ジョブのステータス。running,success,failedのいずれか、canceled
order_by いいえ idでジョブを注文します。
sort いいえ ジョブをasc またはdesc 順番に desc並べ替えますdesc (デフォルト: desc)
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"
        }
    }
]

プロジェクトのランナー一覧

プロジェクトで使用可能なすべてのランナー(特定のランナーと共有ランナー)をリストします。 共有ランナーは、少なくとも1つの共有ランナーが定義されている場合にリストされます。

GET /projects/:id/runners
GET /projects/:id/runners?scope=active
GET /projects/:id/runners?type=project_type
GET /projects/:id/runners?status=active
GET /projects/:id/runners?tag_list=tag1,tag2
属性 タイプ 必須 説明
id 整数/文字列 はい 認証されたユーザーが所有するプロジェクトのIDまたはURLエンコードされたパス
scope いいえ 非推奨: 代わりにtype またはstatus を使用してください。 表示するランナーの範囲。active,paused,online,offlineのいずれか。
type いいえ 表示するランナーのタイプ。instance_type,group_typeのいずれか、project_type
status いいえ 表示するランナーのステータス。activepausedonlineのいずれか、offline
tag_list 文字列配列 いいえ ランナーのタグ一覧
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners"

回答例

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

プロジェクトでランナーを有効にします。

プロジェクトで使用可能な特定のランナーを有効にします。

POST /projects/:id/runners
属性 タイプ 必須 説明
id 整数/文字列 はい 認証されたユーザーが所有するプロジェクトのIDまたはURLエンコードされたパス
runner_id 整数 はい ランナーの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,
    "name": null,
    "online": true,
    "status": "online"
}

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

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

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

グループのランナーをリストアップ

グループとその祖先グループで使用可能なすべてのランナー(特定および共有)をリストします。 共有ランナーは、少なくとも1つの共有ランナーが定義されている場合にリストされます。

GET /groups/:id/runners
GET /groups/:id/runners?type=group_type
GET /groups/:id/runners?status=active
GET /groups/:id/runners?tag_list=tag1,tag2
属性 タイプ 必須 説明
id 整数 はい 認証されたユーザーが所有するグループのID
type いいえ 表示するランナーのタイプ。instance_type,group_typeのいずれか、project_type
status いいえ 表示するランナーのステータス。activepausedonlineのいずれか、offline
tag_list 文字列配列 いいえ ランナーのタグ一覧
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/9/runners"

回答例

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

新規ランナーの登録

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

POST /runners
属性 タイプ 必須 説明
token はい 登録トークン
description いいえ ランナーの説明
info ハッシュ いいえ ランナーのメタデータ
active ブーリアン いいえ ランナーがアクティビティかどうか
locked ブーリアン いいえ 現在のプロジェクトでRunnerをロックするかどうか
run_untagged ブーリアン いいえ Runnerがタグなしジョブを処理するかどうか
tag_list 文字列配列 いいえ ランナーのタグ一覧
access_level いいえ ランナーのaccess_level。not_protected またはref_protected
maximum_timeout 整数 いいえ Runnerがジョブを処理する際に設定される最大タイムアウト時間
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 ランナーが誕生

回答例

{
    "id": "12345",
    "token": "6337ff461c94fd3fa32ba3b1ff4125"
}

登録ランナーの削除

登録されているランナーを削除します。

DELETE /runners
属性 タイプ 必須 説明
token はい runnerの認証トークン
curl --request DELETE "https://gitlab.example.com/api/v4/runners" --form "token=<authentication_token>"

応答してください:

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

登録ランナーの認証確認

登録された Runner の認証情報を検証します。

POST /runners/verify
属性 タイプ 必須 説明
token はい runnerの認証トークン
curl --request POST "https://gitlab.example.com/api/v4/runners/verify" --form "token=<authentication_token>"

応答してください:

ステータス 説明
200 クレデンシャルは有効です。
403 認証情報が無効です