GitLab ラベル設計

概要

Issue のステートを GitLab ラベルで管理し、カンバンボード・フィルタリング・自動化の基盤とする。Webhook を活用してステート遷移に連動したラベルの自動付与・削除を行う。

ステート対応ラベル

ラベル一覧

ラベル名	色	対応ステート	説明
`status::draft`	`#6699cc` (青灰)	Draft	内容精査前の下書き
`status::open`	`#428bca` (青)	Open	承認済み・報酬設定待ち
`status::available`	`#2da44e` (緑)	Available	取得可能
`status::in-progress`	`#e9b308` (黄)	In Progress	作業中
`status::in-review`	`#9333ea` (紫)	In Review	レビュー待ち
`status::changes-requested`	`#f97316` (橙)	Changes Requested	修正依頼
`status::approved`	`#16a34a` (濃緑)	Approved	承認済み・マージ待ち
`status::done`	`#6b7280` (灰)	Done	完了
`status::cancelled`	`#dc2626` (赤)	Cancelled	キャンセル

ラベル命名規則

スコープ付きラベル（status:: プレフィックス）を使用
GitLab のスコープ付きラベルは同一スコープ内で排他的（1つの Issue に status:: ラベルは1つだけ）
これにより、ステートの一貫性が自動的に保証される

補助ラベル

ステート以外の分類に使用する補助ラベル。

優先度ラベル

ラベル名	色	説明
`priority::critical`	`#dc2626` (赤)	緊急
`priority::high`	`#f97316` (橙)	高
`priority::medium`	`#e9b308` (黄)	中（デフォルト）
`priority::low`	`#6b7280` (灰)	低

報酬ラベル

ラベル名	色	説明
`reward::small`	`#d1fae5` (薄緑)	~5,000円
`reward::medium`	`#a7f3d0` (緑)	5,000~20,000円
`reward::large`	`#6ee7b7` (濃緑)	20,000~50,000円
`reward::premium`	`#34d399` (鮮緑)	50,000円~

技術カテゴリラベル

ラベル名	色	説明
`tech::frontend`	`#3b82f6` (青)	フロントエンド
`tech::backend`	`#8b5cf6` (紫)	バックエンド
`tech::infra`	`#f59e0b` (黄)	インフラ
`tech::ai`	`#ec4899` (ピンク)	AI/ML
`tech::docs`	`#6b7280` (灰)	ドキュメント

自動ラベル付与の Webhook 設計

Webhook イベントとラベル操作

mermaid

flowchart LR
    subgraph GitLab Events
        A[Issue作成]
        B[Issue更新]
        C[MR作成]
        D[MRレビュー]
        E[MRマージ]
    end

    subgraph Webhook Handler
        F[ラベル自動更新API]
    end

    subgraph Label Operations
        G[status::ラベル付替]
        H[補助ラベル付与]
    end

    A --> F
    B --> F
    C --> F
    D --> F
    E --> F
    F --> G
    F --> H

イベント別の自動ラベル操作

#	トリガーイベント	条件	ラベル操作
1	Issue 作成	-	`status::draft` を付与
2	Issue に `approved` フラグ設定	マネージャーが承認	`status::draft` → `status::open`
3	報酬・見積の設定完了	reward フィールドが入力済み	`status::open` → `status::available`
4	Issue にアサイン設定	エンジニアがアサイン取得	`status::available` → `status::in-progress`
5	MR 作成（Issue 紐付き）	MR の description に `Closes #N`	`status::in-progress` → `status::in-review`
6	MR でレビュアーが修正依頼	MR approval status = changes_requested	`status::in-review` → `status::changes-requested`
7	MR に新規コミット push	Changes Requested 中に push	`status::changes-requested` → `status::in-review`
8	MR でレビュアーが承認	MR approval status = approved	`status::in-review` → `status::approved`
9	MR マージ	MR がマージされた	`status::approved` → `status::done`
10	アサイン解除	エンジニアのアサインが外れた	現在の status → `status::available`
11	Issue クローズ（キャンセル）	マネージャーが close	現在の status → `status::cancelled`

Webhook エンドポイント設計

POST /api/webhooks/gitlab/issue-events
POST /api/webhooks/gitlab/mr-events

リクエスト処理フロー

mermaid

sequenceDiagram
    participant GL as GitLab
    participant WH as Webhook Handler
    participant DB as データベース
    participant API as GitLab API

    GL->>WH: Webhook Event (JSON)
    WH->>WH: イベント種別判定
    WH->>WH: 遷移ルール評価
    WH->>DB: Issue ステート更新
    WH->>API: ラベル更新 (PUT /projects/:id/issues/:iid)
    API-->>WH: 更新結果
    WH-->>GL: 200 OK

GitLab API によるラベル更新

bash

# ラベル更新の例（status::available → status::in-progress）
curl --request PUT \
  --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  --data "remove_labels=status::available" \
  --data "add_labels=status::in-progress" \
  "https://gitlab.example.com/api/v4/projects/:id/issues/:iid"

Note: スコープ付きラベル（status::xxx）を使用しているため、同一スコープのラベルを新規付与すると旧ラベルは自動的に外れる。ただし明示的な remove も併用し、確実性を担保する。

Webhook シークレット検証

python

import hmac
import hashlib

def verify_gitlab_webhook(request, secret_token):
    """GitLab Webhook のシークレットトークンを検証"""
    token = request.headers.get("X-Gitlab-Token")
    if not token or not hmac.compare_digest(token, secret_token):
        raise PermissionError("Invalid webhook token")

マイルストーンとの連携

マイルストーン設計

マイルストーン	用途	期間
Sprint YYYY-WNN	週次スプリント	1週間（月曜〜日曜）
Monthly YYYY-MM	月次集計	1ヶ月
Q1/Q2/Q3/Q4 YYYY	四半期集計	3ヶ月

マイルストーンの自動設定ルール

Issue が Available になった時点で、直近のスプリントマイルストーンを自動設定
エンジニアがアサイン取得時、期限に基づいてマイルストーンを再設定（期限が次スプリントにまたがる場合）
Done 到達時、実際の完了スプリントにマイルストーンを更新

カンバンボードとマイルストーンの組み合わせ

GitLab Board フィルタ例:
- 全体ボード: マイルストーン指定なし → 全 Issue のステート別表示
- スプリントボード: milestone = "Sprint 2026-W14" → 今週のスプリント
- エンジニア別: assignee = @engineer → 特定エンジニアの担当 Issue

GitLab Board 設定

ボードカラム構成

カラム順	ラベル	カラム名
1	(ラベルなし)	Open (Backlog)
2	`status::available`	Available
3	`status::in-progress`	In Progress
4	`status::in-review`	In Review
5	`status::changes-requested`	Changes Requested
6	`status::approved`	Approved
-	(Closed)	Closed (Done + Cancelled)

ボード作成コマンド

bash

# ボードの作成
curl --request POST \
  --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  --data "name=Issue Kanban" \
  "https://gitlab.example.com/api/v4/projects/:id/boards"

# 各カラム（リスト）の作成
for label in "status::available" "status::in-progress" "status::in-review" "status::changes-requested" "status::approved"; do
  curl --request POST \
    --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
    --data "label_id=$(get_label_id $label)" \
    "https://gitlab.example.com/api/v4/projects/:id/boards/:board_id/lists"
done

GitLab ラベル設計 ​

概要 ​

ステート対応ラベル ​

ラベル一覧 ​

ラベル命名規則 ​

補助ラベル ​

優先度ラベル ​

報酬ラベル ​

技術カテゴリラベル ​

自動ラベル付与の Webhook 設計 ​

Webhook イベントとラベル操作 ​

イベント別の自動ラベル操作 ​

Webhook エンドポイント設計 ​

リクエスト処理フロー ​

GitLab API によるラベル更新 ​

Webhook シークレット検証 ​

マイルストーンとの連携 ​

マイルストーン設計 ​

マイルストーンの自動設定ルール ​

カンバンボードとマイルストーンの組み合わせ ​

GitLab Board 設定 ​

ボードカラム構成 ​

ボード作成コマンド ​

GitLab ラベル設計

概要

ステート対応ラベル

ラベル一覧

ラベル命名規則

補助ラベル

優先度ラベル

報酬ラベル

技術カテゴリラベル

自動ラベル付与の Webhook 設計

Webhook イベントとラベル操作

イベント別の自動ラベル操作

Webhook エンドポイント設計

リクエスト処理フロー

GitLab API によるラベル更新

Webhook シークレット検証

マイルストーンとの連携

マイルストーン設計

マイルストーンの自動設定ルール

カンバンボードとマイルストーンの組み合わせ

GitLab Board 設定

ボードカラム構成

ボード作成コマンド