命名規則・検索・バッジ・トピック

Posted at 2025-11-19

命名規則・検索・バッジ・トピック

(トップページはこちら) - (プロジェクトで作業を整理する)

GitLab.comでプロジェクトを効率的に管理するには、プロジェクトの作成から整理、可視化、検索まで、一連の機能を理解する必要があります。本記事では、実務で必要となる4つの重要な機能を、実際の利用シーンに沿って解説します。

1. 命名規則と予約語:プロジェクト作成の第一歩

プロジェクトやグループを作成する際、GitLabの内部ルーティングと競合しないよう、いくつかの命名ルールが設けられています。

1.1 命名ルールの基本

ユーザー名とグループ名:

有効な例:

tanaka_taro
yamada.hanako
suzuki ⭐ ichiro
marketing-team-2024
backend.services

プロジェクト名:

プラス記号(+)も使用可能です。

有効な例:

web-app-v2+features
backend-api-service 🚀
user_management_portal

スラッグ(URL用識別子):

表示名とは別に、URLで使用されるスラッグには厳格な制限があります。

文字、数字、アンダースコア、ドット、ダッシュのみ
連続する特殊文字は不可
.git、.atomで終わることは不可

1.2 予約語:よくある失敗を避ける

プロジェクト名として使用できない主な予約語:

badges, blob, commits, edit, files, new, raw, tree, wikis

トップレベルグループ名として使用できない主な予約語:

admin, api, dashboard, explore, help, search, users

実務上の注意点:

admin-panelは使用可能ですが、adminは使用不可
api-gatewayは使用可能ですが、apiは使用不可
サブグループでは制限が緩和されます

1.3 ベストプラクティス

一貫性のある命名規則を採用する
- 組織全体で統一されたパターンを使用(例: チーム名-プロジェクト種別-機能)
- frontend-web-app、backend-api-serviceのような構造
将来の拡張を考慮する
- バージョン番号を含める場合はv2ではなく-v2のように区切る
- project-v2はprojectの後継であることが明確
機密情報を含めない
- プロジェクト名やグループ名は公開される可能性があります
- 顧客名や内部コードネームの使用は避けましょう

2. プロジェクトトピック:効率的な整理と発見

トピックは、プロジェクトを分類し、関連するプロジェクトを発見しやすくするラベル機能です。現在ベータ版として提供されています。

2.1 トピックの実用例

技術スタック別の整理:

python, django, postgresql
javascript, react, nodejs
go, kubernetes, microservices

プロジェクト種別での分類:

frontend, backend, mobile, infrastructure
library, tool, documentation

用途やイベント別:

hackathon, poc, production
internal-tool, customer-facing

2.2 トピックの割り当て

前提条件: プロジェクトのメンテナーロール以上

手順:

プロジェクトの「設定」>「一般」を開く
「名前、説明、トピック」セクションを展開
「プロジェクトトピック」欄で検索(人気トピックが自動提案されます)
トピックを選択または新規作成
「変更を保存」をクリック

実務上のヒント:

3〜5個程度のトピックが適切です(多すぎると効果が薄れます)
組織内で共通のトピック命名規則を決めておくと効果的です
既存の人気トピックを活用すると、他のプロジェクトとの連携が容易になります

2.3 トピックの探索とフィルタリング

トピックページへのアクセス:

左サイドバーの「検索または移動」を選択
「探索」を選択
「トピック」を選択

フィルタリング機能:

名前: トピック名で検索
言語: プログラミング言語で絞り込み
可視性: Public/Internal/Privateで絞り込み
オーナー: 特定のユーザーやグループが所有するプロジェクト
アーカイブ: アーカイブされたプロジェクトを含めるか

ソート機能:

日付順(最新/最古)
名前順(昇順/降順)
スター数順(人気度)

2.4 トピックの購読:新規プロジェクトを追跡

RSSフィードを使用して、特定のトピックに新しいプロジェクトが追加されたときに通知を受け取れます。

購読方法:

購読したいトピックのページを開く
右上の「新規プロジェクトフィードを購読」(RSSアイコン)をクリック
表示されたAtom形式のURLをフィードリーダーに追加

活用シーン:

社内の特定技術スタックを使用する新規プロジェクトを追跡
ハッカソンやイベント関連の新規プロジェクトを監視
特定チームの活動状況を把握

2.5 重要な注意事項

プライバシーに関する考慮:

プロジェクトに割り当てられたトピックは、そのプロジェクトにアクセスできるユーザーのみが閲覧可能
しかし、GitLab.com上のトピック一覧は未認証ユーザーを含む全員が閲覧可能
トピック名に機密情報や顧客名を含めないでください

3. バッジ:プロジェクトの状態を可視化

バッジは、プロジェクトの状態や品質指標を視覚的に表示する機能です。プロジェクト概要ページやREADMEに表示され、一目でプロジェクトの健全性を把握できます。

3.1 バッジの種類と用途

3.2 パイプラインステータスバッジ

最も一般的に使用されるバッジで、CI/CDパイプラインの状態を表示します。

ステータスの種類:

ステータス	意味	表示色
`passed`	パイプライン成功	緑
`failed`	パイプライン失敗	赤
`running`	実行中	青
`pending`	待機中	オレンジ
`skipped`	スキップ	グレー
`canceled`	キャンセル	グレー
`manual`	手動実行待ち	青

基本的なURL:

https://gitlab.com/<namespace>/<project>/badges/<branch>/pipeline.svg

スキップを無視する場合:

https://gitlab.com/<namespace>/<project>/badges/<branch>/pipeline.svg?ignore_skipped=true

これにより、スキップされたパイプラインを除外し、最後の実際に実行されたパイプラインのステータスを表示します。

実務での活用:

READMEの先頭に配置して、プロジェクトの健全性を即座に伝える
mainブランチとdevelopブランチの両方のバッジを表示して、開発状況を可視化
外部ドキュメントやダッシュボードに埋め込む

3.3 テストカバレッジバッジ

コードのテストカバレッジ率を表示し、コード品質の指標として機能します。

基本的なURL:

https://gitlab.com/<namespace>/<project>/badges/<branch>/coverage.svg

特定のジョブのカバレッジを表示:

https://gitlab.com/<namespace>/<project>/badges/<branch>/coverage.svg?job=coverage

複数のカバレッジジョブがある場合(フロントエンド/バックエンド等)に有用です。

カバレッジ率と色の関係:

カバレッジ率	範囲	色	評価
良好	95%〜100%	緑(#4c1)	優秀
許容範囲	90%〜95%	黄緑(#a3c51c)	良好
中程度	75%〜90%	黄色(#dfb317)	改善推奨
低い	0%〜75%	赤(#e05d44)	要改善
不明	データなし	グレー(#9f9f9f)	未設定

閾値のカスタマイズ:

組織の基準に合わせて閾値を変更できます。

https://gitlab.com/<namespace>/<project>/badges/<branch>/coverage.svg?min_good=98&min_acceptable=85&min_medium=70

実務での活用:

プロジェクトごとに異なる品質基準を設定
フロントエンドとバックエンドで別々のカバレッジバッジを表示
カバレッジ向上の進捗を視覚的に追跡

3.4 最新リリースバッジ

プロジェクトの最新リリースバージョンを表示します。

基本的なURL:

https://gitlab.com/<namespace>/<project>/-/badges/release.svg

ソート順の指定:

https://gitlab.com/<namespace>/<project>/-/badges/release.svg?order_by=released_at

バッジ幅のカスタマイズ:

バージョン名が長い場合に調整できます(1〜200、デフォルト54)。

https://gitlab.com/<namespace>/<project>/-/badges/release.svg?value_width=100

3.5 カスタムバッジ:独自の情報を表示

カスタムバッジを使用すると、任意のテキストと色で独自のバッジを作成できます。

基本的なURL:

https://gitlab.com/%{project_path}/badges/custom.svg

完全なカスタマイズ例:

https://gitlab.com/%{project_path}/badges/custom.svg?key_text=最新タグ&value_text=%{latest_tag}&key_color=white&value_color=7bc043

カスタマイズ可能な要素:

パラメータ	説明	例
`key_text`	左側のテキスト	`ビルド状態`
`value_text`	右側のテキスト	`安定版`
`key_color`	左側の背景色	`blue`、`fff`
`value_color`	右側の背景色	`green`、`7bc043`
`key_width`	左側の幅	`130`
`value_width`	右側の幅	`100`

実用例:

# 環境ステータス
https://gitlab.com/%{project_path}/badges/custom.svg?key_text=本番環境&value_text=稼働中&key_color=2c3e50&value_color=27ae60

# デプロイ頻度
https://gitlab.com/%{project_path}/badges/custom.svg?key_text=デプロイ&value_text=週3回&key_color=34495e&value_color=3498db

# チーム情報
https://gitlab.com/%{project_path}/badges/custom.svg?key_text=担当チーム&value_text=バックエンド&key_color=555&value_color=orange

3.6 バッジのスタイルカスタマイズ

すべてのバッジで共通して使用できるスタイルオプションです。

スタイルの種類:

フラット(デフォルト):
```
?style=flat
```
グラデーションのあるモダンなスタイル
フラットスクエア:
```
?style=flat-square
```
角が直角のシンプルなスタイル

キーテキストのカスタマイズ:

左側のテキストを変更して、複数の同種バッジを区別できます。

https://gitlab.com/gitlab-org/gitlab/badges/main/coverage.svg?job=frontend&key_text=フロントエンド+カバレッジ&key_width=150

3.7 プレースホルダー:動的なバッジ作成

プレースホルダーを使用すると、プロジェクト情報を動的にバッジに反映できます。

利用可能なプレースホルダー:

プレースホルダー	説明	例
`%{project_path}`	プロジェクトパス	`gitlab-org/gitlab`
`%{project_name}`	プロジェクト名	`gitlab`
`%{project_title}`	プロジェクトタイトル	`GitLab`
`%{default_branch}`	デフォルトブランチ	`main`
`%{commit_sha}`	最新コミットSHA	`a1b2c3d4...`
`%{latest_tag}`	最新タグ	`v1.2.3`
`%{gitlab_server}`	サーバーURL	`gitlab.com`

実用例:

# 最新コミットを表示
https://gitlab.com/%{project_path}/badges/custom.svg?key_text=最新コミット&value_text=%{commit_sha}

# デフォルトブランチ名を表示
https://gitlab.com/%{project_path}/badges/custom.svg?key_text=メインブランチ&value_text=%{default_branch}

セキュリティ上の注意:

プレースホルダーは、プライベートリポジトリの情報(ブランチ名、コミットSHA等)を公開する可能性があります。これは意図的な動作ですが、機密性の高い情報を含む場合は使用を避けてください。

3.8 バッジの追加・編集・削除

プロジェクトバッジの追加:

プロジェクトの「設定」>「一般」を開く
「バッジ」セクションを展開
「バッジを追加」をクリック
以下を入力:
- 名前: バッジの識別名(例: パイプラインステータス)
- リンク: クリック時の遷移先URL
- バッジ画像URL: バッジのSVG画像URL
「バッジを追加」をクリック

グループバッジ:

グループレベルで追加すると、そのグループ内のすべてのプロジェクトに自動的に表示されます。ただし、プロジェクトレベルでは編集・削除できません。

バッジの編集:

「設定」>「一般」>「バッジ」を開く
編集したいバッジの横の「編集」アイコンをクリック
内容を変更して「変更を保存」

バッジの削除:

「設定」>「一般」>「バッジ」を開く
削除したいバッジの横の「削除」アイコンをクリック
確認ダイアログで「バッジを削除」をクリック

3.9 バッジURLの確認方法

パイプライン関連のバッジURLは専用の場所で確認できます。

プロジェクトの「設定」>「CI/CD」を開く
「一般パイプライン」セクションを展開
「パイプラインステータス」「カバレッジレポート」「最新リリース」セクションでURLを確認

このURLをコピーして、READMEやドキュメントに埋め込むことができます。

4. 検索機能:必要な情報を素早く発見

GitLab.comは、成長するコードベースから必要な情報を効率的に見つけるための強力な検索機能を提供しています。

4.1 検索タイプの理解

GitLabは3種類の検索タイプを提供しており、自動的に最適なものが選択されます。

検索タイプの優先順位:

完全一致コード検索(Exact Code Search): 利用可能な場合に最優先
高度な検索(Advanced Search): 完全一致が利用できない場合
基本検索(Basic Search): 上記が利用できない場合、または非デフォルトブランチを検索する場合

検索タイプの明示的指定:

URLパラメータで検索タイプを指定できます。

?search_type=zoekt    # 完全一致コード検索
?search_type=advanced # 高度な検索
?search_type=basic    # 基本検索

4.2 検索スコープ:何を検索できるか

基本検索で利用可能なスコープを理解することが重要です。

スコープ別の利用可能範囲:

スコープ	グローバル	グループ	プロジェクト	用途
コード	✗	✗	✓	ソースコード検索
コメント	✗	✗	✓	イシュー・MRのコメント
コミット	✗	✗	✓	コミットメッセージ
イシュー	✓	✓	✓	課題管理
マージリクエスト	✓	✓	✓	コードレビュー
マイルストーン	✓	✓	✓	進捗管理
プロジェクト	✓	✓	✗	プロジェクト発見
ユーザー	✓	✓	✓	メンバー検索
Wiki	✗	✗	✓	ドキュメント検索

実務上のポイント:

コード検索はプロジェクト内のみ可能(グループ横断検索には高度な検索が必要)
イシューとマージリクエストはグローバル検索可能
Wikiはプロジェクト内のみ検索可能

4.3 基本的な検索方法

全体検索:

左サイドバーの「検索または移動」フィールドをクリック
検索キーワードを入力(最低2文字)
Enterキーを押すか、候補から選択
左サイドバーのフィルタで結果を絞り込み

プロジェクト内検索:

「検索または移動」でプロジェクトを選択
再度「検索または移動」で検索キーワードを入力
Enterキーで検索実行

フルパス検索:

名前空間を含む完全なパスで直接プロジェクトを検索できます。

gitlab-org/gitlab
gitlab-org/

後者はgitlab-org名前空間内のプロジェクトの候補を表示します。

4.4 コード検索の構文

基本検索では、以下の構文を使用して検索を絞り込めます。

基本構文:

構文	説明	マッチング
`filename:`	ファイル名	部分一致・ワイルドカード可
`path:`	ディレクトリパス	部分一致
`extension:`	ファイル拡張子	完全一致のみ

実用的な検索例:

# gemfile.lock以外でrailsを検索
rails -filename:gemfile.lock

# YMLとJS以外でhelperを検索
helper -extension:yml -extension:js

# lib/gitパス内でhelperを検索
helper path:lib/git

# specファイルでauthenticationを検索
authentication filename:*spec.rb

# workersディレクトリ内のRubyファイルでjobを検索
job path:app/workers/ extension:rb

除外検索:

マイナス記号(-)を使用して、特定の条件を除外できます。

# configディレクトリを除外
database -path:config/

# テストファイルを除外
function -filename:*test* -filename:*spec*

4.5 高度な検索機能

言語フィルタ:

コード検索結果を特定のプログラミング言語で絞り込めます。

コード検索を実行
左サイドバーで言語を選択(複数選択可)
「適用」をクリック

アーカイブプロジェクトを含める:

デフォルトではアーカイブされたプロジェクトは除外されます。

検索結果ページの左サイドバーで「アーカイブを含む」をチェック
「適用」をクリック

Git blameの表示:

コード検索結果から、その行を最後に変更した人を確認できます。

コード検索結果で行番号にカーソルを合わせる
左側に表示される「blameを表示」をクリック

4.6 コミットSHA検索

コミットSHAで直接検索すると、該当するコミットに即座にジャンプできます。

プロジェクト内で「検索または移動」を選択
コミットSHA(完全または部分)を入力
Enterキーを押す

単一の結果が見つかった場合、GitLabは自動的にそのコミットページにリダイレクトします。

4.7 オートコンプリート機能

検索ボックスに入力すると、以下の候補が自動的に表示されます。

表示される候補:

プロジェクトとグループ
認可されたプロジェクト・グループのユーザー
ヘルプページ
プロジェクト機能(マイルストーン等)
設定ページ
最近閲覧したマージリクエスト
最近閲覧したイシューとエピック
GitLab Flavored Markdown参照(例: #123)

実務での活用:

プロジェクト名の一部を入力して素早くアクセス
イシュー番号(#123)で直接ジャンプ
ユーザー名で関連するコンテンツを検索

4.8 検索の制限事項

GitLabは、パフォーマンスとセキュリティのため、いくつかの検索制限を設けています。

無視される検索:

2文字未満の検索語
100文字を超える用語(URL検索は200文字まで)
ストップワードのみ(the、and、if、or等)
不正なscopeパラメータ
数値以外のgroup_idやproject_id
Gitの命名規則に違反するrepository_ref

エラーとなる検索:

4096文字を超える検索クエリ
64個を超える検索用語

部分一致の制限:

イシュー検索では部分一致がサポートされていません。

playで検索してもdisplayはヒットしません
ただし、play、plays、playing等の変形はヒットします

4.9 検索のベストプラクティス

1. 適切なスコープを選択する

検索対象を絞り込むことで、より関連性の高い結果が得られます。

# イシューのみを検索
スコープ: イシュー

# 特定のマイルストーンに絞り込み
スコープ: イシュー + マイルストーンフィルタ

2. 検索構文を活用する

ファイル名やパスを指定することで、ノイズを削減できます。

# モデルファイルのみを検索
User path:app/models/

# コントローラーを除外
authentication -path:app/controllers/

3. 段階的に絞り込む

最初は広く検索し、結果を見ながら徐々に条件を追加します。

# ステップ1: 広く検索
authentication

# ステップ2: ファイルタイプを絞る
authentication extension:rb

# ステップ3: パスを絞る
authentication extension:rb path:app/services/

4. プロジェクトパスを活用する

複数のプロジェクトを管理している場合、フルパス検索が効率的です。

team-name/project-name

5. 実践的な活用シーン

これまで説明した機能を組み合わせた実践的な活用例を紹介します。

5.1 新規プロジェクトのセットアップ

手順:

命名: backend-user-api(予約語apiは含まれていないのでOK)
トピック: python, django, rest-api, backend
バッジ: パイプラインステータス、カバレッジ、最新リリース
README: バッジを先頭に配置

5.2 既存プロジェクトの整理

シナリオ: 100個以上のプロジェクトがあり、整理が必要

アプローチ:

トピックの標準化
- 技術スタック用: python, javascript, go
- レイヤー用: frontend, backend, infrastructure
- ステータス用: production, deprecated, archived
バッジの統一
- すべてのプロジェクトにパイプラインステータスバッジを追加
- カバレッジ目標を設定(例: 80%以上)
- グループバッジで組織全体の基準を適用
検索の最適化
- トピックで技術スタック別にフィルタ
- アーカイブプロジェクトを除外
- 最終更新日でソート

5.3 コードレビューの効率化

シナリオ: 特定の機能に関連するコードを横断的に確認したい

検索戦略:

# 認証関連のコードを検索
authentication path:app/services/ extension:rb

# テストコードを確認
authentication path:spec/ filename:*service*

# 設定ファイルを確認
authentication path:config/ extension:yml

バッジの活用:

マージリクエストのパイプラインステータスを確認
カバレッジバッジで新規コードのテスト状況を把握

5.4 技術スタックの可視化

シナリオ: 組織全体でどの技術が使われているか把握したい

トピックの活用:

「探索」>「トピック」でpythonを選択
プロジェクト数とアクティビティを確認
RSSフィードで新規プロジェクトを追跡

バッジの活用:

カスタムバッジで技術スタックを明示
最新リリースバッジでバージョン管理状況を把握

6. まとめ

GitLab.comのプロジェクト管理機能を効果的に活用するには、以下の4つの要素を理解し、組み合わせることが重要です。

1. 命名規則と予約語

一貫性のある命名でプロジェクトの発見性を向上
予約語を避けてエラーを防止
将来の拡張を考慮した命名

2. トピック

プロジェクトを分類して整理
関連プロジェクトの発見を容易に
RSSフィードで新規プロジェクトを追跡

3. バッジ

プロジェクトの状態を視覚的に表示
CI/CD、品質、バージョンを一目で把握
カスタムバッジで独自の情報を追加

4. 検索

強力な検索構文で必要な情報を素早く発見
スコープとフィルタで結果を絞り込み
オートコンプリートで効率的にナビゲート

これらの機能を組み合わせることで、大規模な組織でも効率的にプロジェクトを管理し、チーム間のコラボレーションを促進できます。特に、トピックによる分類とバッジによる可視化は、プロジェクトの透明性を高め、新規メンバーのオンボーディングを加速させる強力なツールとなります。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up