プロジェクトで作業を整理する

(トップページはこちら)

チュートリアル : GitLabで実現する堅牢なコードレビューワークフロー

GitLab.comのプロジェクトは、開発チームが協働するための中核となる単位です。単なるGitリポジトリではなく、コード管理、イシュー追跡、CI/CDパイプライン、デプロイメントまでを統合した開発環境を提供します。本記事では、プロジェクトの作成から運用まで、実務で必要となる設定と機能を順を追って解説します。

1. プロジェクトの作成と初期設定

新しいプロジェクトを作成する際、開発フローに合わせて以下の設定を構成します。後から変更できますが、初期段階で適切に設定しておくことで、チームの混乱を避けられます。

必須の初期設定項目

公開範囲(Visibility level)

• Private: チームメンバーのみアクセス可能(推奨)
• Internal: GitLab.comの全ログインユーザーが閲覧可能
• Public: インターネット上の誰でも閲覧可能(OSSプロジェクト向け)

マージリクエスト承認
コードレビューの必須人数や承認者の条件を設定します。例えば「2名以上の承認が必要」「コード所有者の承認が必須」などのルールを定義できます。

イシュートラッキング
タスク管理機能を有効化します。無効にするとイシュー機能が使えなくなるため、通常は有効のままにします。

CI/CDパイプライン
.gitlab-ci.ymlファイルを配置することで、自動テスト・ビルド・デプロイが実行されます。初期段階では無効にして、後から段階的に導入することも可能です。

説明テンプレート
イシューやマージリクエストの説明欄に自動挿入されるテンプレートを設定できます。「再現手順」「期待される動作」などの項目を標準化することで、情報の抜け漏れを防げます。

## 概要
<!-- 変更内容を簡潔に記述 -->

## 変更理由
<!-- なぜこの変更が必要か -->

## テスト方法
<!-- 動作確認の手順 -->

## スクリーンショット
<!-- UIに変更がある場合 -->

詳細はこちら

2. セキュアなアクセス制御

プロジェクトへのアクセスを安全に管理するため、用途に応じて3つのツールを使い分けます。人間のユーザーアカウントを共有する必要はありません。

プロジェクトアクセストークン

CI/CDパイプラインから別のプロジェクトのAPIを呼び出す場合や、外部ツール(Slack bot、監視システムなど)との連携に使用します。

# 例: curlでAPIを呼び出す
curl --header "PRIVATE-TOKEN: glpat-xxxxxxxxxxxx" \
  "https://gitlab.com/api/v4/projects/278964/issues"

権限を細かく設定できるため、必要最小限のアクセス権のみを付与できます。

デプロイキー

本番サーバーやステージング環境からリポジトリをクローンする際に使用します。読み取り専用のSSH鍵を生成し、サーバーに配置します。

# サーバー側でSSH鍵を生成
ssh-keygen -t ed25519 -C "production-server"

# 公開鍵をGitLabのデプロイキーに登録後、クローン可能
git clone [e-mail]:your-org/your-project.git

デプロイトークン

Dockerイメージをプルする場合や、一時的なデプロイスクリプトで使用します。有効期限を設定できるため、短期間のアクセスに適しています。

# 例: Container Registryからイメージをプル
docker login registry.gitlab.com -u <username> -p <deploy-token>
docker pull registry.gitlab.com/your-org/your-project:latest

詳細はこちら

3. チーム協働とプロジェクト共有

複数のプロジェクトをグループで管理することで、チーム全体の作業を効率化できます。各プロジェクトは独立したリポジトリを持ちながら、グループレベルで権限管理やCI/CD設定を共有できます。

実践的なグループ構成例

グループ活用のメリット

1. 権限の一括管理: グループにメンバーを追加すれば、配下の全プロジェクトにアクセス権が付与されます
2. CI/CD変数の共有: API鍵やデプロイ先の情報をグループレベルで管理し、全プロジェクトで利用できます
3. イシューボードの統合: 複数プロジェクトのイシューを横断的に表示し、チーム全体の進捗を把握できます

サブグループの使い分け

大規模な組織では、サブグループを使って階層構造を作ります。例えば、フロントエンドチームにはread権限のみ、バックエンドチームにはwrite権限を付与するなど、細かい制御が可能です。

詳細はこちら

4. プロジェクトの発見性と認知度向上

組織が成長すると、数百のプロジェクトが存在するようになります。必要なプロジェクトを素早く見つけるための工夫が重要です。

命名規則の統一

一貫性のある命名規則を採用することで、検索性が向上します。

良い例:
- product-a-frontend
- product-a-backend-api
- product-a-mobile-ios
- product-b-web-service

悪い例:
- frontend (どのプロダクトか不明)
- api-v2 (何のAPIか不明)
- tanaka-test (個人名は避ける)

予約済みの名前(例: help, admin, api)は使用できないため、事前に確認が必要です。

バッジの活用

READMEファイルにバッジを追加することで、プロジェクトの状態を一目で把握できます。

# プロジェクト名

[![pipeline status](https://gitlab.com/your-org/your-project/badges/main/pipeline.svg)](https://gitlab.com/your-org/your-project/-/commits/main)
[![coverage report](https://gitlab.com/your-org/your-project/badges/main/coverage.svg)](https://gitlab.com/your-org/your-project/-/commits/main)

ビルドステータス、テストカバレッジ、最新バージョンなどを表示できます。

プロジェクトトピックの設定

トピックはタグのような機能で、関連プロジェクトをグループ化できます。

設定例:
- トピック: frontend, react, typescript
- トピック: backend, ruby, rails, api
- トピック: infrastructure, kubernetes, terraform

GitLab.comの検索画面でトピックをクリックすると、同じトピックを持つプロジェクトが一覧表示されます。

詳細はこちら

5. 開発効率とコード品質の向上

GitLab.comのコードインテリジェンス機能を活用することで、IDEを使わずにブラウザ上で効率的にコードを読めます。

コードナビゲーション

関数やクラスの定義にジャンプできます。大規模なコードベースでも、依存関係を素早く追跡できます。

# app/services/user_service.rb
class UserService
  def create_user(params)
    # この行で User をクリックすると、モデル定義にジャンプ
    User.create(params)
  end
end

ホバー情報

マウスオーバーするだけで、関数のシグネチャやドキュメントが表示されます。

ファイルファインダー

プロジェクトページでtキーを押すと、ファイルファインダーが起動します。ファイル名の一部を入力するだけで、目的のファイルに素早くアクセスできます。

入力: "user_serv"
候補:
- app/services/user_service.rb
- spec/services/user_service_spec.rb

大規模なリポジトリでディレクトリ構造を覚えていなくても、効率的にファイルを探せます。

詳細はこちら

6. プロジェクトのマイグレーション

GitHubやBitbucketからGitLab.comに移行する場合、ファイルエクスポート機能を使用します。リポジトリだけでなく、イシュー、マージリクエスト、ラベルなども移行できます。

移行の流れ

1. 移行元のプロジェクトをエクスポート(tar.gz形式)
2. GitLab.comで新規プロジェクトを作成
3. エクスポートファイルをインポート
4. メンバーの権限を再設定

プロジェクトエイリアス

頻繁にアクセスするリポジトリを元の名前で継続利用できます。例えば、old-project-nameからnew-project-nameに変更した場合でも、エイリアスを設定すれば古い名前でアクセス可能です。

# エイリアス設定後、古い名前でもクローンできる
git clone [e-mail]:your-org/old-project-name.git

プロジェクト転送

GitLab.com上で名前空間間のプロジェクト移動が可能です。個人アカウントからグループへ、またはグループ間での移動に使用します。

移動前: gitlab.com/yamada/my-project
移動後: gitlab.com/company-org/my-project

組織再編やチーム構成の変更時に、リポジトリのURLを変えずに所有権を移転できます。

詳細はこちら

7. ほか

システムノート
GitLabプロジェクトをGoパッケージとして活用
プロジェクトのトラブルシュート
チュートリアル : GitLabで実現する堅牢なコードレビューワークフロー

まとめ

GitLab.comのプロジェクトは、コード管理だけでなく、チーム協働、CI/CD、セキュリティ管理までを統合したプラットフォームです。本記事で紹介した6つのステップを実践することで、効率的な開発環境を構築できます。

次のアクションプラン

1. 小さく始める: まずは1つのプロジェクトを作成し、基本的な設定を試す
2. グループ構造を設計: チームの規模に応じて、グループとサブグループを計画する
3. CI/CDを段階的に導入: 自動テストから始め、徐々にデプロイまで自動化する
4. 命名規則とトピックを統一: 組織全体で検索性を高める
5. 定期的に見直す: プロジェクトの設定やアクセス権を定期的にレビューする

小規模なチームであれば、まずはプロジェクト作成とCI/CD設定から始めることをお勧めします。組織が成長するにつれて、グループ管理やアクセス制御を強化していくアプローチが現実的です。