2026.11.13 開発

GitLabのIssue：テンプレート・ラベル・ボードの設定例とAPIでの一括登録【2026年11月】

GitLabのIssueは、作るだけなら誰でもすぐに使える機能です。ただし書き方が人ごとにばらつき、ラベルが増え続け、ボードの列と実際の状態がずれ始めると、Issue一覧は誰も見なくなります。この記事で扱う内容は、.gitlab/issue_templatesに置くテンプレートの具体例、ラベルの命名とイシューボードの列の組み方、MRのマージでIssueを自動で閉じる条件、機密Issueの閲覧範囲、Issues APIとcurlでの一括登録までの一連の設定手順です。FreeとPremiumで使える機能の差も、2026年11月時点の公式ドキュメントにもとづいて示します。

まとめ：GitLabのIssueはテンプレート・ラベル・ボードの順に決めて回す

Issue運用の設定は、テンプレート、ラベル、ボードの順に決めると手戻りが出ません。テンプレートで起票時の項目を揃え、ラベルで種別と状態を表し、ボードの列はそのラベルをそのまま並べます。ボードの列はラベルの付け外しで動く仕組みなので、ラベルの設計が先に固まっていないとボードは作り直しになります。

Freeでもテンプレート、ラベル、プロジェクトの複数ボード、自動クローズ、機密Issue、APIは使えます。状態を1つに保つスコープ付きラベル、担当者別やマイルストーン別の列、ブロック関係はPremium以上です。Issueの作成やクイックアクションの基本操作はGitLabの使い方（プロジェクト作成からIssue・MR・CI/CDまで）で扱っているので、この記事は運用ルールの設定に絞ります。

GitLabのIssueで使える機能とFree・Premiumで変わる範囲の整理

Issueはプロジェクトに属するタスクの単位で、バグ報告、機能要望、作業タスクをまとめて追跡します。設定を始める前に、どの機能がどのプランで動くかを押さえておくと、Premium前提の設計をFreeのプロジェクトに持ち込む失敗を防げます。

IssueはWork items画面に統合されPlanner以上のロールで編集する

2026年11月時点の公式ドキュメント「Manage issues」では、Issueの一覧は左メニューの Plan > Work items から Type を Issue に絞って開く案内になっています。Issue、Task、Epicなどが「作業項目」という共通の枠に寄せられている途中で、古い解説記事の画面名と一致しないことがあります。

操作できるロールも以前とは異なる仕様です。GitLab 17.7でIssueの一括編集や移動に必要なロールがReporterからPlannerへ変わり、企画やPMのメンバーにはコードを触らせずにIssueだけを管理させられます。ロールごとの操作範囲はGitLabの権限（ロール）の操作範囲と設定手順で一覧にしています。

FreeとPremiumで差が出るスコープ付きラベル・担当者リスト・ブロック関係

Issue運用で使う機能のうち、プランで差が出るものを公式ドキュメントの記載から抜き出すと次のとおりです。

機能	Free	Premium・Ultimate
Issue用の説明テンプレート	使える	使える＋グループ共有・設定画面で既定を指定
ラベル・ラベルの優先度	使える	使える
スコープ付きラベル（key::value）	使えない	使える
ボードのラベルリスト	使える	使える
ボードの担当者・マイルストーンリスト	使えない	使える
グループボードの数	1つ	複数
リンク済みIssue（relates to）	使える	使える
blocks・is blocked by の関係	使えない	使える

出典はLabels、Issue boards、Linked issuesの各ページです。Freeで運用する場合、状態の管理はスコープ付きでない通常のラベルとラベルリストの組み合わせで組みます。

Issueテンプレートの配置先と起票内容を揃えるためのファイル作成手順

テンプレートはリポジトリにMarkdownファイルを置くだけで有効になります。起票画面のテンプレート選択に並ぶのは、デフォルトブランチにコミット済みのファイルだけです。

バグ報告テンプレートのMarkdown例とクイックアクションでの自動ラベル付与

Description templatesの仕様では、Issue用は.gitlab/issue_templates/に拡張子.mdで置き、1ファイルが1テンプレートになります。末尾にクイックアクションを書くと、テンプレートを選んで保存した時点でラベルなどが付きます。

# ファイル: .gitlab/issue_templates/Bug.md
## 発生した事象
（画面・API・バッチのどこで何が起きたかを1〜2文で）

## 再現手順
1.
2.
3.

## 期待した動作

## 実際の動作（エラーメッセージ・ログはコードブロックで貼る）

## 環境
- ブランチまたはコミット:
- ブラウザ・OS:
- 発生日時:

/label ~bug ~needs-triage
/cc @qa-lead

見出しで項目を固定しておくと、再現手順の抜けた報告が減ります。クイックアクションは起票した人の権限で実行されるため、ラベルを付けられないロールの人が使うと、その行は効きません。ラベル名にスペースを含む場合は~"high priority"のように二重引用符で囲みます。機能要望用のFeature.md、作業依頼用のTask.mdを並べ、種別ごとに付くラベルを変えるのが基本の形です。

Default.mdで既定テンプレートを決めるときの優先順位とグループ共有の条件

Freeでも.gitlab/issue_templates/Default.mdという名前のファイルを置けば、新規Issueの説明欄に最初から入ります。大文字小文字は区別されません。

既定のテンプレートが複数の場所にあるときは、プロジェクト設定で指定したもの、親グループのDefault.md、プロジェクトリポジトリのDefault.mdの順で優先されます。グループ配下の全プロジェクトで同じテンプレートを使うグループレベルのテンプレートはPremium以上で、グループのOwnerロールが必要です。テンプレートを置くプロジェクトはグループ直下の子プロジェクトに限られます。Freeで複数プロジェクトに揃えたいときは、各リポジトリへ同じファイルをコミットするしかありません。

ラベル設計とイシューボードの列でチームのワークフローを表す設定例

ラベルは自由に作れる分、運用ルールが無いと数か月で数十個に増えます。1つのIssueに付けられるラベルは最大100個という上限はありますが、実際に困るのは上限ではなく、似た意味のラベルが並んで誰も正しく付けられなくなる状態です。

種別・優先度・状態の3系統で分けるラベル命名とPrioritized Labelsの並び

ラベルの接頭辞は、系統ごとに揃えるのが基本です。種別はbug・feature・chore、優先度はP1〜P3、状態はneeds-triage・doing・reviewのように分け、系統ごとに色を統一すると一覧で判別できます。複数プロジェクトで同じラベルを使うなら、グループで作成します。グループラベルは配下の全プロジェクトのIssueとMRに付けられ、プロジェクトラベルは作ったプロジェクトの中でしか使えません。

優先度ラベルは、プロジェクトのラベル一覧で星アイコンを押すと「Prioritized Labels」に入り、ドラッグで順位を決められます。Issue一覧を優先度順に並べると、各Issueに付いた中で最も順位の高いラベルだけが並びを決める基準です。P1とP3が両方付いたIssueはP1として扱われるので、優先度ラベルは1つだけ付ける運用にします。

スコープ付きラベルworkflow::で状態を1つに保つPremiumの仕組み

Premium以上では、workflow::doingのようにkey::value形式で書いたラベルがスコープ付きラベルになります。同じキーのラベルは1つのIssueに1つしか付かず、workflow::reviewを追加するとworkflow::doingは自動で外れます。

ネストも可能です。最後の::より前がスコープになるため、workflow::backend::reviewとworkflow::backend::developmentは同時に付きませんが、workflow::frontend::reviewとは併用できます。Freeでは::を含む名前のラベルを作っても排他にはならないため、状態ラベルが2つ付いたIssueが出ないよう、ボードのドラッグで状態を動かす運用に寄せます。

ボードのリスト間ドラッグで付け外しされるラベルとClosedへの移動の挙動

イシューボードは、左端のOpenと右端のClosedの間に、ラベルごとのリストを並べる仕組みです。公式ドキュメントでは、リスト間でIssueを動かすと移動元のラベルが外れ、移動先のラベルが付くと説明されています。

Openからdoingのリストへ：doingが付く
doingからreviewのリストへ：doingが外れ、reviewが付く
reviewからClosedへ：Issueがクローズされる
ClosedからラベルのリストへIssueを戻す：再オープンされ、そのラベルが付く

列はラベルの付け外しそのものなので、ボードに置くのは状態系のラベルだけにします。種別や優先度のラベルで列を作ると、ドラッグのたびに種別が外れる挙動になるためです。プロジェクトのボードはFreeでも複数作れるため、開発チーム用の状態ボードと、トリアージ用にneeds-triageだけを並べるボードを分ける構成も取れます。WIP制限（列ごとの上限件数）はPremium以上の機能です。

MRとの連携と機密Issue：Closesでの自動クローズと閲覧範囲の設定

Issueはマージリクエストと結び付けて初めて、作業の完了と同期します。逆に、脆弱性の報告のように全員に見せてはいけないIssueもあり、どちらも設定の前提を知らないと事故になります。

Closes #12の書き方でデフォルトブランチへのマージ時にIssueを閉じる条件

MRの説明文やコミットメッセージにCloses #12と書くと、そのMRがデフォルトブランチへマージされた時点で#12が閉じます。使えるキーワードはClose・Fix・Resolve・Implementの4系統で、それぞれCloses・Fixed・Resolvingのような語形の変化も認識の対象です。Closes #4, #6, Related to #5と書いた場合、閉じるのは#4と#6だけで、#5は関連付けにとどまります。

閉じない典型は2つあります。developなどデフォルトブランチ以外へのマージと、リポジトリへの最初のpushです。後者を対象外とする理由は、公式ドキュメントによればパフォーマンス上の事情です。リリースブランチ運用で自動クローズが邪魔なら、Maintainer以上が Settings > Repository > Branch defaults の「Auto-close referenced issues on default branch」を外します。この設定の適用対象は、変更後のMRとコミットだけです。MR側の作成手順や承認ルールはGitLabのマージリクエストの作成と承認ルール設定にまとめています。

機密Issueを見られるのはPlanner以上のロールと担当者だけという閲覧範囲

Confidential issuesによると、機密Issueを閲覧できるのはプロジェクトのPlanner・Reporter・Developer・Maintainer・Ownerです。Guestは自分が作った機密Issueだけを見られます。GuestやメンバーでないユーザーもIssueの担当者に設定されている間は読めますが、担当を外すと読めなくなります。

機密にする方法は、作成画面の「Turn on confidentiality」のチェック、既存Issueのメニュー、/confidentialのクイックアクションの3通りです。権限の無いユーザーには一覧にも検索結果にも出ません。外部の協力会社にGuestで入ってもらっているプロジェクトでは、障害報告やセキュリティ関連のテンプレートに/confidentialを最初から書いておくと、機密化の付け忘れを防げます。

Issues APIとcurlでIssueを一括登録しラベルを付け替えるスクリプト例

移行や棚卸しで数十件のIssueをまとめて作る場面では、画面から1件ずつ起票するよりAPIのほうが確実です。書き込みには、apiスコープを持つアクセストークンを使います。トークンの種類と認証の詳細はGitLab APIのトークン認証とcurl例で扱っています。

Issues APIのPOSTでタブ区切りファイルからIssueを一括作成するシェル例

Issues APIの作成エンドポイントはtitleだけが必須で、labelsはカンマ区切り、due_dateはYYYY-MM-DD形式です。次の例は、タイトル・ラベル・期日をタブで区切ったファイルを1行ずつIssueにします。

# 前提: GITLAB_TOKEN は api スコープのトークン、PID は対象プロジェクトのID
# issues.tsv の各行は「タイトル[TAB]ラベル（カンマ区切り）[TAB]期日 YYYY-MM-DD」
GITLAB=https://gitlab.example.com/api/v4
PID=123

while IFS=$'\t' read -r title labels due; do
  curl --silent --request POST \
    --header "PRIVATE-TOKEN: ${GITLAB_TOKEN}" \
    --data-urlencode "title=${title}" \
    --data-urlencode "labels=${labels}" \
    --data-urlencode "due_date=${due}" \
    "${GITLAB}/projects/${PID}/issues" | jq -r '"#\(.iid) \(.title)"'
  sleep 1
done < issues.tsv

# 作成されたラベルを確かめる（綴り違いのラベルが増えていないか）
curl --silent --header "PRIVATE-TOKEN: ${GITLAB_TOKEN}" \
  "${GITLAB}/projects/${PID}/labels?per_page=100" | jq -r '.[].name'

このAPIは、指定したラベルが存在しなければ新しく作成する仕様です。bugのつもりでbguと書いた行があると、そのままラベルが1つ増えるため、登録後にラベル一覧を確認する2つ目のコマンドを入れています。担当者の指定はFreeがassignee_id（1人）、Premium以上がassignee_ids（配列）と、プランでパラメータ名が違う点にも注意が要ります。

add_labelsとstate_eventで状態を変えるときの1分600回の更新上限

既存Issueの更新はPUT /projects/:id/issues/:issue_iidです。labelsを渡すと付いているラベルが丸ごと置き換わるため、状態だけを変えるならadd_labelsとremove_labelsを使います。

# Issue #85 から needs-triage を外して doing を付ける
curl --silent --request PUT --header "PRIVATE-TOKEN: ${GITLAB_TOKEN}" \
  --data "add_labels=doing&remove_labels=needs-triage" \
  "${GITLAB}/projects/${PID}/issues/85"

# needs-triage が付いたまま開いている Issue を一覧する
curl --silent --header "PRIVATE-TOKEN: ${GITLAB_TOKEN}" \
  "${GITLAB}/projects/${PID}/issues?state=opened&labels=needs-triage&per_page=100" \
  | jq -r '.[] | "#\(.iid) \(.title)"'

# Issue #85 をクローズする（再オープンは state_event=reopen）
curl --silent --request PUT --header "PRIVATE-TOKEN: ${GITLAB_TOKEN}" \
  --data "state_event=close" \
  "${GITLAB}/projects/${PID}/issues/85"

更新にはユーザーごとに既定で1分あたり600リクエストの上限があり、画面、REST API、GraphQLからの更新で共有されます。超えると429 Too Many Requestsが返るので、数百件を一度に書き換えるスクリプトでは1件ごとに待ちを入れます。一覧の取得は既定で20件ずつ返るため、件数の多いプロジェクトではper_pageとページ送りの処理が必要です。

Issueで管理を完結させる条件と別のタスク管理ツールへ分ける判断基準

ここまでの設定はどのチームでも組めます。ただ、すべての案件管理をGitLabのIssueに寄せるのが正解とは限りません。判断は「誰が起票し、誰が消化するか」で決まります。

Issueに寄せるべき条件は開発者が起票と消化の両方を担うチームの場合

起票する人と作業する人の大半が開発者で、作業の完了がMRのマージとほぼ一致するなら、Issueに寄せます。Closesによる自動クローズでボードの更新漏れが起きず、コードの変更履歴からIssueへ、Issueから議論へと1か所でたどれるためです。マイルストーンと期日で進捗を追う設定はGitLabのスケジュール管理（マイルストーン・期日・ロードマップ）で扱っています。

Freeでもこの形は成り立ちます。状態ラベルをボードのドラッグだけで動かし、テンプレートで起票の項目を揃えれば、スコープ付きラベルが無くても状態の重複はほぼ起きません。

Issueだけで回すのを見送る場面は非開発者の起票が多い場合などの2つ

見送る場面ははっきりしています。1つ目は、営業や顧客サポートなど開発者でないメンバーの起票が多いチームです。GitLabのアカウントとMarkdownの書き方が前提になり、起票の段階で問い合わせ管理ツールとの二重入力が生まれます。この場合は問い合わせを別ツールで受け、開発に渡す時点でIssueを作る2段構えにします。

2つ目は、Issue同士の依存関係で工程を管理したいのにFreeを使い続ける場合です。blocksの関係もガントチャート相当の表示もPremium以上なので、依存の多い案件をFreeのIssueだけで管理すると、順序の管理が担当者の頭の中に戻ります。プランの変更か専用ツールの併用かを決めずにIssueへ寄せるのは避けるべきです。テンプレート・ラベル・CI/CDまで含めた開発フローの設計を外部に相談したい場合は、DevOps・CI/CD導入支援で現状の運用からの組み替えを支援しています。

よくある質問

GitLabのIssueの設定と運用で、つまずきやすい点をまとめました。

Issueテンプレートを置いたのに選択肢に出てこないのはなぜですか？

多いのは、テンプレートをデフォルトブランチ以外のブランチにだけコミットしている場合です。起票画面に並ぶのはデフォルトブランチにあるファイルだけなので、作業ブランチのままではMRをマージするまで表示されません。次に多いのが置き場所と拡張子の誤りで、Issue用は.gitlab/issue_templates/、拡張子は.mdです。MR用の.gitlab/merge_request_templates/に置いたファイルはIssueの選択肢には出ません。

GitLabのIssueとマージリクエストは何が違いますか？

Issueは「何をするか」を記録する作業の単位で、コードを含みません。マージリクエストは「どう変えたか」をブランチの差分としてレビューし、取り込むための単位です。通常はIssueを先に作り、作業ブランチからMRを出し、MRの説明にCloses #番号を書いて結び付けます。マージした時点でIssueが閉じるため、Issueの状態とコードの状態がずれません。

GitHubのIssue Formsのような入力フォームはGitLabで作れますか？

GitLabの説明テンプレートの公式ドキュメントに記載されているのは、Markdownファイルによるテンプレートだけです。GitHubのIssue FormsのようにYAMLで必須項目や選択肢を定義する仕組みは、2026年11月時点のこのページには書かれていません。入力の抜けを防ぐには、見出しで項目を固定し、トリアージ担当がneeds-triageのIssueを確認して差し戻す運用で補います。両者の機能差はGitHubとGitLabの違いで比較しています。

Issueを別のプロジェクトへ移動するとどうなりますか？

移動すると、元のIssueはクローズされたうえで残り、移動先のプロジェクトにコピーが作られます。両方のIssueにシステムノートが付き、移動元と移動先が記録されます。コメントは内部メモも含めてコピーされるため、移動先で見えるメンバーの範囲を事前に確認してください。添付ファイルは新しいURLでコピーされ、元の添付ファイルへの直接リンクは404になります。/move group/projectのクイックアクションでも移動できます。

Issueに付けられるラベルの数に上限はありますか？

公式ドキュメントでは、1つの作業項目（Issue、エピック、タスクなど）に付けられるラベルは最大100個とされています。実務で上限に届くことはまずありません。問題になるのは数より種類の重なりで、同じ系統のラベルが複数付くと、ボードの列や優先度順の並びが崩れます。種別・優先度・状態の各系統で1つずつ付ける運用にし、Premium以上なら状態をスコープ付きラベルにして排他にします。