ランナーAPI

登録および認証トークン
所有ランナー一覧
すべてのランナーをリストアップ
ランナーの詳細情報
ランナー詳細の更新
ランナーの取り外し
リストランナーのジョブ
プロジェクトのランナー一覧
プロジェクトでランナーを有効にします。
プロジェクトからランナーを無効にします。
グループのランナーをリストアップ
新規ランナーの登録
登録ランナーの削除
登録ランナーの認証確認

ランナー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"

注: レスポンスの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`	列	いいえ	表示するランナーのステータス。`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	認証情報が無効です

クリエーションラインについて

私たちクリエーションラインは、日本で最も古く2017年にGitLabサービスの提供を開始し、2022年には「Asia-Pacific Partner of the Year」も獲得。GitLabのサブスクリプション販売やテクニカルサポートだけでなく、GitLab Enterpriseの導入支援やGitLabトレーニングなど多様なサービスを提供し、エンタープライズを中心に豊富な実績を誇ります。GitLabに関するお悩みがありましたら、ぜひお気軽にお問い合わせください。日本で唯一、3度にわたるMVPを獲得したGitLabエバンジェリストをはじめとしたエキスパートチームが、あなたの課題解決をご支援します。