- 登録および認証トークン
- 所有ランナー一覧
- すべてのランナーをリストアップ
- ランナーの詳細情報
- ランナー詳細の更新
- ランナーの取り外し
- リストランナーのジョブ
- プロジェクトのランナー一覧
- プロジェクトでランナーを有効にします。
- プロジェクトからランナーを無効にします。
- グループのランナーをリストアップ
- 新規ランナーの登録
- 登録ランナーの削除
- 登録ランナーの認証確認
ランナーAPI
GitLab 8.5 で導入されました。
登録および認証トークン
RunnerとGitLabを接続する際に考慮すべきトークンは2つあります。
トークン | 説明 |
---|---|
登録トークン | Runnerを登録するためのトークンです。GitLabから取得できます。 |
認証トークン | GitLab インスタンスで Runner を認証するために使用するトークンです。Runner を登録するときに自動的に取得するか、Runners API 経由で Runner を登録するときに手動で取得します。 |
2つのトークンがランナー登録でどのように使用されるかの例です:
- 登録トークンを使って GitLab API 経由で Runner を登録すると、認証トークンが返されます。
-
その認証トークンを使い、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
| 列 | いいえ | 表示するランナーのステータス。active 、paused 、online のいずれか、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
| 列 | いいえ | 表示するランナーのステータス。active 、paused 、online のいずれか、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"
回答例
{
"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"
回答例
{
"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
| 列 | いいえ | 表示するランナーのステータス。active 、paused 、online のいずれか、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
| 列 | いいえ | 表示するランナーのステータス。active 、paused 、online のいずれか、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 | 認証情報が無効です |