ラベル API

注：description_html -はGitLab 12.7でレスポンスJSONに追加されました。

リストラベル

指定したプロジェクトのすべてのラベルを取得します。

デフォルトでは、APIの結果はページ分割されているため、このリクエストは一度に20件の結果を返します。 

GET /projects/:id/labels
属性 タイプ 必須 説明
id 整数/文字列 はい 認証されたユーザーが所有するプロジェクトのIDまたはURLエンコードされたパス
with_counts ブーリアン いいえ イシューとマージリクエストのカウントを含めるかどうか。デフォルトはfalse。(GitLab 12.2 で導入)
include_ancestor_groups ブーリアン いいえ 祖先グループを含めます。 デフォルトはtrueです。 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels?with_counts=true"

回答例 

[
  {
    "id" : 1,
    "name" : "bug",
    "color" : "#d9534f",
    "text_color" : "#FFFFFF",
    "description": "Bug reported by user",
    "description_html": "Bug reported by user",
    "open_issues_count": 1,
    "closed_issues_count": 0,
    "open_merge_requests_count": 1,
    "subscribed": false,
    "priority": 10,
    "is_project_label": true
  },
  {
    "id" : 4,
    "color" : "#d9534f",
    "text_color" : "#FFFFFF",
    "name" : "confirmed",
    "description": "Confirmed issue",
    "description_html": "Confirmed issue",
    "open_issues_count": 2,
    "closed_issues_count": 5,
    "open_merge_requests_count": 0,
    "subscribed": false,
    "priority": null,
    "is_project_label": true
  },
  {
    "id" : 7,
    "name" : "critical",
    "color" : "#d9534f",
    "text_color" : "#FFFFFF",
    "description": "Critical issue. Need fix ASAP",
    "description_html": "Critical issue. Need fix ASAP",
    "open_issues_count": 1,
    "closed_issues_count": 3,
    "open_merge_requests_count": 1,
    "subscribed": false,
    "priority": null,
    "is_project_label": true
  },
  {
    "id" : 8,
    "name" : "documentation",
    "color" : "#f0ad4e",
    "text_color" : "#FFFFFF",
    "description": "Issue about documentation",
    "description_html": "Issue about documentation",
    "open_issues_count": 1,
    "closed_issues_count": 0,
    "open_merge_requests_count": 2,
    "subscribed": false,
    "priority": null,
    "is_project_label": false
  },
  {
    "id" : 9,
    "color" : "#5cb85c",
    "text_color" : "#FFFFFF",
    "name" : "enhancement",
    "description": "Enhancement proposal",
    "description_html": "Enhancement proposal",
    "open_issues_count": 1,
    "closed_issues_count": 0,
    "open_merge_requests_count": 1,
    "subscribed": true,
    "priority": null,
    "is_project_label": true
  }
]

プロジェクトラベルの取得

指定されたプロジェクトの単一のラベルを取得します。 

GET /projects/:id/labels/:label_id
属性 タイプ 必須 説明
id 整数/文字列 はい 認証されたユーザーが所有するプロジェクトのIDまたはURLエンコードされたパス
label_id 整数または文字列 はい プロジェクトのラベルのIDまたはタイトル。
include_ancestor_groups ブーリアン いいえ 祖先グループを含めます。 デフォルトはtrueです。 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels/bug"

回答例 

{
  "id" : 1,
  "name" : "bug",
  "color" : "#d9534f",
  "text_color" : "#FFFFFF",
  "description": "Bug reported by user",
  "description_html": "Bug reported by user",
  "open_issues_count": 1,
  "closed_issues_count": 0,
  "open_merge_requests_count": 1,
  "subscribed": false,
  "priority": 10,
  "is_project_label": true
}

新しいラベルの作成

指定された名前と色で、指定されたリポジトリの新しいラベルを作成します。 

POST /projects/:id/labels
属性 タイプ 必須 説明
id 整数/文字列 はい 認証されたユーザーが所有するプロジェクトのIDまたはURLエンコードされたパス
name 列 はい ラベルの名前
color 列 はい ラベルの色を、先頭に’#’記号を付けた6桁の16進数表記（例：#FFAABB）、またはCSSカラー名のいずれかで指定します。
description 列 いいえ ラベルの説明
priority 整数 いいえ ラベルの優先度。 0 以上でなければなりません。優先度を削除するにはnull を指定します。 
curl --data "name=feature&color=#5843AD" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels"

回答例 

{
  "id" : 10,
  "name" : "feature",
  "color" : "#5843AD",
  "text_color" : "#FFFFFF",
  "description":null,
  "description_html":null,
  "open_issues_count": 0,
  "closed_issues_count": 0,
  "open_merge_requests_count": 0,
  "subscribed": false,
  "priority": null,
    "is_project_label": true
}

ラベルの削除

指定された名前のラベルを削除します。 

DELETE /projects/:id/labels/:label_id
属性 タイプ 必須 説明
id 整数/文字列 はい 認証されたユーザーが所有するプロジェクトのIDまたはURLエンコードされたパス
label_id 整数または文字列 はい グループのラベルのIDまたはタイトル。 
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels/bug"
注意：パラメータにname を使った古いエンドポイントDELETE /projects/:id/labels もまだ利用可能ですが、非推奨です。

既存のラベルの編集

既存のラベルを新しい名前または新しい色で更新します。 ラベルを更新するには、少なくとも1つのパラメータが必要です。 

PUT /projects/:id/labels/:label_id
属性 タイプ 必須 説明
id 整数/文字列 はい 認証されたユーザーが所有するプロジェクトのIDまたはURLエンコードされたパス
label_id 整数または文字列 はい グループのラベルのIDまたはタイトル。
new_name 列 はいcolor が提供されない場合 ラベルの新しい名前
color 列 はいnew_name が提供されない場合 ラベルの色を、先頭に’#’記号を付けた6桁の16進数表記（例：#FFAABB）、またはCSSカラー名のいずれかで指定します。
description 列 いいえ ラベルの新しい説明
priority 整数 いいえ ラベルの新しい優先度。 0 以上である必要があり、優先度を削除するにはnull を指定します。 
curl --request PUT --data "new_name=docs&color=#8E44AD&description=Documentation" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels/documentation"

回答例 

{
  "id" : 8,
  "name" : "docs",
  "color" : "#8E44AD",
  "text_color" : "#FFFFFF",
  "description": "Documentation",
  "description_html": "Documentation",
  "open_issues_count": 1,
  "closed_issues_count": 0,
  "open_merge_requests_count": 2,
  "subscribed": false,
  "priority": null,
  "is_project_label": true
}
注：パラメータにname またはlabel_id を含む古いエンドポイントPUT /projects/:id/labels はまだ利用可能ですが、非推奨です。

プロジェクトラベルをグループラベルに昇格

GitLab 12.3 で導入されました。

プロジェクトラベルをグループラベルに昇格します。 

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

回答例 

{
  "id" : 8,
  "name" : "documentation",
  "color" : "#8E44AD",
  "description": "Documentation",
  "description_html": "Documentation",
  "open_issues_count": 1,
  "closed_issues_count": 0,
  "open_merge_requests_count": 2,
  "subscribed": false
}
注意：パラメータにname を使った古いエンドポイントPUT /projects/:id/labels/promote もまだ利用可能ですが、非推奨です。

レーベルに登録

認証済みユーザをラベルに登録し、通知を受け取ります。 ユーザが既にラベルに登録されている場合は、ステータスコード304が返されます。 

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

回答例 

{
  "id" : 1,
  "name" : "bug",
  "color" : "#d9534f",
  "text_color" : "#FFFFFF",
  "description": "Bug reported by user",
  "description_html": "Bug reported by user",
  "open_issues_count": 1,
  "closed_issues_count": 0,
  "open_merge_requests_count": 1,
  "subscribed": true,
  "priority": null,
  "is_project_label": true
}

ラベルからの退会

認証済みユーザがラベルからの通知を受け取らないように、ラベルからの登録を解除します。 ユーザがラベルに登録されていない場合は、ステータスコード304 が返されます。 

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