GitLabサーバーの構築と運用

本ガイドでは、GitLabサーバーの基本的なインストールから、日々の運用に必要な設定、さらに高度な機能であるLDAP連携やコンテナレジストリの利用方法までを網羅的に解説します。

1. システム要件と前提条件

GitLabサーバーを安定して運用するためには、適切なシステムリソースと事前準備が必要です。

1.1. サポートされるオペレーティングシステム

• Ubuntu (16.04/18.04/20.04)
• Debian (9/10)
• CentOS (7/8)
• openSUSE Leap (15.2)
• SUSE Linux Enterprise Server (12 SP2/12 SP5)
• Red Hat Enterprise Linux (CentOSパッケージを利用)

1.2. ハードウェア要件

• ディスク: ソースコードの保存領域に加え、十分な余裕が必要です。SAS 7.2k RPM HDDまたはSSDの使用が推奨されます。
• CPU:
  • 500ユーザーまで: 4コア
  • 1000ユーザーまで: 8コア
• メモリ:
  • 500ユーザーまで: 4 GB
  • 1000ユーザーまで: 8 GB

1.3. 依存パッケージのインストール

GitLabのインストールに必要な基本的なパッケージを事前に導入します。

# ファイアウォールを一時的に無効化、またはGitLabが必要とするポートを開放
sudo systemctl stop firewalld
sudo systemctl disable firewalld

# 必要な依存関係をインストール (CentOS/RHELの場合)
sudo yum install -y curl openssh-server postfix wget
# Ubuntu/Debianの場合:
# sudo apt-get update
# sudo apt-get install -y curl openssh-server ca-certificates postfix

2. GitLabのインストール

GitLabのRPMパッケージをダウンロードし、システムに導入します。

2.1. リポジトリ設定とパッケージダウンロード

最新のパッケージや特定のバージョンを取得するため、適切なリポジトリを設定し、wgetコマンドでRPMパッケージをダウンロードします。

# CentOS 8 ストリーム版のリポジトリを使用する場合の例
# sed -i "s|\$releasever|8-stream|g" /etc/yum.repos.d/CentOS-*.repo
# yum makecache

# GitLab CEのRPMパッケージをダウンロード (バージョンは適宜変更)
# 例: GitLab CE 13.2.2 for CentOS 8
wget --content-disposition https://packages.gitlab.com/gitlab/gitlab-ce/packages/el/8/gitlab-ce-13.2.2-ce.0.el8.x86_64.rpm/download.rpm

2.2. パッケージのインストール

ダウンロードしたRPMファイルをローカルインストールします。

# ダウンロードしたパッケージ名に置き換えて実行
sudo yum localinstall -y gitlab-ce-13.2.2-ce.0.el8.x86_64.rpm

インストールが完了すると、GitLabインスタンスのURLを設定するよう促すメッセージが表示されます。

GitLab was unable to detect a valid hostname for your instance.
Please configure a URL for your GitLab instance by setting `external_url`
configuration in /etc/gitlab/gitlab.rb file.
Then, you can start your GitLab instance by running the following command:
sudo gitlab-ctl reconfigure

3. GitLabの初期設定

GitLabの動作に必要なURL設定、メール通知、およびオプションコンポーネントの調整を行います。設定ファイルは主に/etc/gitlab/gitlab.rbです。

3.1. 外部URLとメール設定

GitLabインスタンスがアクセスされるURLと、システムからのメール通知設定を行います。

# /etc/gitlab/gitlab.rb ファイルを編集

# GitLabインスタンスのアクセスURLを設定
external_url 'http://git.yourcompany.com'

# メール送信機能の有効化と送信元情報の指定
gitlab_rails['gitlab_email_enabled'] = true
gitlab_rails['gitlab_email_from'] = 'gitlab-notifications@yourcompany.com'
gitlab_rails['gitlab_email_display_name'] = 'GitLab 通知サービス'

# SMTPサーバー設定 (例: 163.comのSMTPを使用)
gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "smtp.yourcompany.com" # または "smtp.163.com"
gitlab_rails['smtp_port'] = 587 # または 465 (SSL/TLSのポートに応じて)
gitlab_rails['smtp_user_name'] = "your_smtp_username@yourcompany.com"
gitlab_rails['smtp_password'] = "YOUR_SMTP_PASSWORD" # アプリケーションパスワードなど
gitlab_rails['smtp_domain'] = "yourcompany.com" # または "163.com"
gitlab_rails['smtp_authentication'] = "login"
gitlab_rails['smtp_enable_starttls_auto'] = true
gitlab_rails['smtp_tls'] = false # TLSの場合、trueに設定

3.2. 不要なコンポーネントの無効化

システムリソースを節約するため、現時点で使用しないコンポーネントを無効化できます。

# Prometheusと関連コンポーネントを無効にする例
prometheus['enable'] = false
prometheus['monitor_kubernetes'] = false
alertmanager['enable'] = false
node_exporter['enable'] = false
redis_exporter['enable'] = false
postgres_exporter['enable'] = false
gitlab_monitor['enable'] = false
prometheus_monitoring['enable'] = false
grafana['enable'] = false

3.3. 設定の適用とサービス起動

/etc/gitlab/gitlab.rbの変更を反映させるには、gitlab-ctl reconfigureコマンドを実行します。

# 設定ファイルを再読み込みし、GitLabコンポーネントを再構成
sudo gitlab-ctl reconfigure

# GitLabサービスの起動と停止 (必要に応じて)
sudo gitlab-ctl start
sudo gitlab-ctl stop
sudo gitlab-ctl status # サービスの状態を確認

初回アクセス時は、rootユーザーのパスワード設定が求められます。

4. GitLab機能の確認

4.1. メール送信機能のテスト

設定したSMTP経由でメールが送信できるかを確認します。

# GitLab Railsコンソールを起動
sudo gitlab-rails console

# コンソール内でテストメールを送信
# Notify.test_email('宛先メールアドレス','テスト件名','テスト本文').deliver_now
Notify.test_email('test-user@example.com','GitLabテスト通知','これはテストメールです。').deliver_now

# コンソールを終了
exit

4.2. 日本語化（オプション）

GitLabの管理画面を日本語表示にしたい場合、コミュニティが提供する日本語化パッチを適用できます。

1. 日本語化パッチのダウンロード: xhang/gitlabなどのリポジトリから、インストールされているGitLabバージョンに合った日本語化ファイルをダウンロードします。
2. GitLabサービスの停止:

sudo gitlab-ctl stop

3. ファイルのコピー: ダウンロードした日本語化ファイルをGitLabのインストールディレクトリに上書きコピーします。

# 例: ダウンロードした日本語化ファイルが 'gitlab-12-0-stable-zh' ディレクトリにある場合
# バックアップを取ることを強く推奨します
sudo cp -r gitlab-12-0-stable-zh/* /opt/gitlab/embedded/service/gitlab-rails/

4. GitLabサービスの再起動:

sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart

ログイン後、一部のUIが日本語化されていることを確認します。

5. トラブルシューティング

5.1. 依存関係の欠如

インストール時にpolicycoreutils-pythonがないというエラーが出た場合、CentOS 8などではパッケージ名が変更されている可能性があります。

エラー例:
nothing provides policycoreutils-python needed by gitlab-ce-12.3.5-ce.0.el7.x86_64

この場合、以下のパッケージをインストールしてください。

sudo yum install -y policycoreutils-python-utils

また、RPMパッケージはOSバージョン（el7はCentOS 7、el8はCentOS 8）に合致するものを選択してください。

6. HTTPS/SSLの有効化

GitLabへの安全なアクセスを確保するため、HTTPSを有効にすることを強く推奨します。

# /etc/gitlab/gitlab.rb ファイルを編集

# external_urlをHTTPSプロトコルに変更
external_url 'https://git.yourcompany.com'

# Nginx設定
nginx['enable'] = true
nginx['client_max_body_size'] = '250m' # 必要に応じてアップロードサイズを調整
nginx['redirect_http_to_https'] = true # HTTPアクセスをHTTPSへリダイレクト
nginx['redirect_http_to_https_port'] = 443

# SSL証明書とキーのパスを指定
nginx['ssl_certificate'] = "/etc/gitlab/ssl/git.yourcompany.com.crt"
nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/git.yourcompany.com.key"

# その他のSSL/TLS設定 (セキュリティ強化のため)
nginx['ssl_ciphers'] = "ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256"
nginx['ssl_prefer_server_ciphers'] = "on"
nginx['ssl_protocols'] = "TLSv1.2 TLSv1.3" # 推奨されるプロトコル
nginx['ssl_session_cache'] = "builtin:1000 shared:SSL:10m"
nginx['ssl_session_timeout'] = "5m"

設定後、忘れずにgitlab-ctl reconfigureを実行します。

sudo gitlab-ctl reconfigure

7. GitLabのアップグレード

GitLabのアップグレードは、メジャーバージョン間でスキップせずに段階的に行う必要があります。通常は以下の手順が推奨されます。

1. 現在のメジャーバージョンの最新マイナーバージョンにアップグレードする。
2. 次にアップグレードしたいメジャーバージョンの最初のマイナーバージョン（例: X.0.Z）にアップグレードする。
3. その後、最新のバージョンへと段階的にアップグレードを進める。

8. バックアップとリストア

GitLabのデータは非常に重要であるため、定期的なバックアップとリストア手順の理解が不可欠です。

8.1. バックアップ設定

gitlab.rbでバックアップの保存場所と保持期間を設定できます。

# /etc/gitlab/gitlab.rb ファイルを編集

# バックアップディレクトリの管理をGitLabに任せるか
gitlab_rails['manage_backup_path'] = true
# バックアップファイルの保存ディレクトリ
gitlab_rails['backup_path'] = "/var/opt/gitlab/backups"
# バックアップアーカイブのファイル権限
gitlab_rails['backup_archive_permissions'] = 0600 # より厳格な権限を推奨
# バックアップファイルを保持する期間 (秒単位, 例: 7日間 = 604800秒)
gitlab_rails['backup_keep_time'] = 604800

設定変更後はgitlab-ctl reconfigureを実行します。

8.2. 手動バックアップの実行

以下のコマンドでGitLabの全データをバックアップします。

sudo gitlab-rake gitlab:backup:create

8.3. 定期バックアップの設定

Cronジョブを使用して、自動的にバックアップを実行できます。

#!/bin/bash
# GitLabデータと設定のバックアップスクリプト

BACKUP_DIR="/var/opt/gitlab/backups"
CONFIG_BACKUP_DIR="/opt/gitlab_config_backups" # 設定ファイルのバックアップ場所

mkdir -p $CONFIG_BACKUP_DIR

echo "GitLabデータのバックアップを開始..."
sudo gitlab-rake gitlab:backup:create

echo "GitLab設定ファイルのバックアップを開始..."
sudo tar zcf ${CONFIG_BACKUP_DIR}/gitlab-config-$(date +%Y%m%d_%H%M%S).tar.gz /etc/gitlab/

echo "バックアップ完了。"

このスクリプトを/usr/local/bin/gitlab_daily_backup.shなどに保存し、実行権限を与えます。

sudo chmod +x /usr/local/bin/gitlab_daily_backup.sh

Cronに登録し、毎日自動実行させます（例: 毎日午前3時に実行）。

# crontab -e を実行し、以下を追加
0 3 * * * /usr/local/bin/gitlab_daily_backup.sh &>/dev/null

8.4. データリストア手順

バックアップからデータを復元するには、以下の手順を実行します。

1. GitLab関連サービスの停止: リストア中にデータ破損を防ぐため、GitLabの主要なプロセスを停止します。

sudo gitlab-ctl stop unicorn
sudo gitlab-ctl stop sidekiq

2. バックアップファイルの配置: 復元したいバックアップファイル（例: 1537261122_2018_09_18_9.2.5_gitlab_backup.tar）を/var/opt/gitlab/backups/ディレクトリに配置します。
3. リストアの実行: バックアップファイル名からタイムスタンプとバージョン部分（例: 1537261122_2018_09_18_9.2.5）を指定してリストアします。

# ファイル名が `1537261122_2018_09_18_9.2.5_gitlab_backup.tar` の場合
sudo gitlab-rake gitlab:backup:restore BACKUP=1537261122_2018_09_18_9.2.5

4. GitLabサービスの起動: リストアが完了したらサービスを起動し、設定を再適用します。

sudo gitlab-ctl start
sudo gitlab-ctl reconfigure # 念のため再構成

9. GitLabサーバーの移行

既存のGitLabサーバーから新しいサーバーへの移行は、バックアップとリストアの仕組みを利用して行います。

1. 新しいサーバーに、既存のサーバーと同じバージョンのGitLabをインストールします。
2. 既存のサーバーで最新のバックアップを作成します。
3. 作成したバックアップファイルを新しいサーバーの/var/opt/gitlab/backups/ディレクトリに転送します。
4. 新しいサーバーで、上記「8.4. データリストア手順」に従ってバックアップをリストアします。

10. 外部PostgreSQLとの連携（オプション）

GitLabに同梱されているPostgreSQLではなく、外部のPostgreSQLデータベースを利用することも可能です。

10.1. DockerでPostgreSQLを構築する例

# データ永続化用のディレクトリを作成
mkdir -p /data/gitlab_pg_data

# DockerでPostgreSQL 11.5コンテナを起動
# パスワード、ボリューム、ポートは環境に合わせて変更
docker run --name gitlab_external_pg \
  -e POSTGRES_PASSWORD=my_secure_pg_password \
  -v /data/gitlab_pg_data:/var/lib/postgresql/data \
  -p 54321:5432 \
  -d postgres:11.5

10.2. データベースとユーザーの作成

GitLabが使用するデータベースとユーザーをPostgreSQL内に作成します。

# PostgreSQLコンテナに接続
docker exec -it gitlab_external_pg psql -U postgres

# psqlプロンプト内で以下を実行
CREATE ROLE gitlab_user LOGIN ENCRYPTED PASSWORD 'my_secure_gitlab_db_password';
CREATE DATABASE gitlab_production_db OWNER=gitlab_user ENCODING='UTF8';
\c gitlab_production_db
CREATE EXTENSION IF NOT EXISTS btree_gist;
CREATE EXTENSION IF NOT EXISTS pg_trgm;
\q # psqlを終了

10.3. GitLabのPostgreSQL設定

/etc/gitlab/gitlab.rbを編集し、外部PostgreSQLに接続するように設定します。

# /etc/gitlab/gitlab.rb ファイルを編集

# GitLabに同梱されているPostgreSQLを無効化
postgresql['enable'] = false

# 外部PostgreSQLへの接続設定
gitlab_rails['db_adapter'] = "postgresql"
gitlab_rails['db_encoding'] = "utf8"
gitlab_rails['db_database'] = "gitlab_production_db" # 作成したデータベース名
gitlab_rails['db_username'] = "gitlab_user" # 作成したユーザー名
gitlab_rails['db_password'] = "my_secure_gitlab_db_password" # 作成したユーザーのパスワード
gitlab_rails['db_host'] = "127.0.0.1" # PostgreSQLホストのアドレス
gitlab_rails['db_port'] = 54321 # PostgreSQLのポート

設定後、gitlab-ctl reconfigureを実行して変更を適用します。

11. Gitクライアントの基本設定

ローカルのGitクライアントを適切に設定することで、GitLabとの連携がスムーズになります。

11.1. グローバルユーザー設定

コミット時に表示されるユーザー名とメールアドレスを設定します。

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
git config --global color.ui true # Gitの出力を色付け

11.2. SSHキーの生成

GitLabにSSH経由でアクセスするためには、SSHキーペアを作成し、公開鍵をGitLabに登録します。

# SSHキーペアを生成
ssh-keygen -t rsa -C "your.email@example.com"
# プロンプトに従い、デフォルトの場所（~/.ssh/id_rsa）で、パスフレーズは空でEnter

生成された公開鍵（~/.ssh/id_rsa.pub）の内容をコピーし、GitLabの「ユーザー設定」→「SSHキー」に貼り付けて追加します。

11.3. 基本的なGit操作

# 新しいローカルリポジトリを初期化
git init

# リモートリポジトリをクローン
git clone https://git.yourcompany.com/yourgroup/your_project.git
cd your_project

# ファイルの追加とコミット
touch README.md
git add README.md
git commit -m "Initial commit: Added README"

# リモートリポジトリへプッシュ
git push -u origin master

12. コンテナレジストリとLDAP連携

GitLabは、内蔵のコンテナレジストリとLDAP/Active Directoryとの連携をサポートしています。

12.1. GitLabコンテナレジストリの有効化

GitLabに内蔵されたコンテナレジストリを有効にして、Dockerイメージをホストできます。

# /etc/gitlab/gitlab.rb ファイルを編集

# コンテナレジストリの外部URLを設定 (例: サブドメイン)
registry_external_url 'https://registry.yourcompany.com'

# GitLab Rails側でレジストリ機能を有効化
gitlab_rails['registry_enabled'] = true
# レジストリへのHTTPアクセスをHTTPSへリダイレクト
registry_nginx['redirect_http_to_https'] = true

# レジストリサービス自体を有効化
registry['enable'] = true
# レジストリがデータを保存するディレクトリ
registry['dir'] = "/var/opt/gitlab/registry"

レジストリのHTTPS設定もNginxセクションと同様に証明書パスを設定する必要があります。

12.2. LDAPサーバー連携

既存のLDAP/Active DirectoryとGitLabを連携させることで、ユーザー認証を一元化できます。

# /etc/gitlab/gitlab.rb ファイルを編集

# LDAP認証を有効化
gitlab_rails['ldap_enabled'] = true
# LDAP経由で作成されたユーザーが自動ログインすることを許可
gitlab_rails['prevent_ldap_sign_in'] = false

# LDAPサーバー設定 (複数のサーバーを設定可能)
gitlab_rails['ldap_servers'] = {
  'main' => { # サーバー識別子
    'label' => '企業LDAP', # UIに表示されるラベル
    'host' =>  'ldap.yourcompany.com', # LDAPサーバーのホスト名またはIP
    'port' => 636, # LDAPS (SSL) ポート
    'uid' => 'uid', # ユーザーを一意に識別する属性 (例: 'sAMAccountName' for AD)
    'encryption' => 'simple_tls', # TLS暗号化方式 (none, simple_tls, start_tls)
    'bind_dn' => 'cn=gitlab-bind-user,ou=ServiceAccounts,dc=yourcompany,dc=com', # LDAP検索用のバインドDN
    'password' => 'YOUR_BIND_PASSWORD', # バインドDNのパスワード
    'ca_file' => '/etc/gitlab/ssl/ldap_ca.crt', # LDAPサーバーのCA証明書パス (TLS利用時)
    'timeout' => 10, # タイムアウト秒数
    'active_directory' => false, # Active Directoryの場合true
    'allow_username_or_email_login' => true, # LDAPユーザーがユーザー名またはメールでログイン可能か
    'block_auto_created_users' => false, # 自動作成されたLDAPユーザーをブロックするか
    'base' => 'ou=Users,dc=yourcompany,dc=com', # ユーザー検索のベースDN
    'user_filter' => '(&(objectClass=inetOrgPerson)(memberOf=cn=gitlab-users,ou=Groups,dc=yourcompany,dc=com))', # ユーザーフィルタ (GitLabに同期するユーザーを絞り込む)
    'attributes' => {
      'username' => ['uid', 'sAMAccountName'], # ユーザー名として使用するLDAP属性
      'email' => ['mail', 'userPrincipalName'], # メールアドレスとして使用するLDAP属性
      'name' => 'cn', # フルネームとして使用するLDAP属性
      'first_name' => 'givenName',
      'last_name' => 'sn'
    },
    'lowercase_usernames' => true, # ユーザー名を小文字に変換するか

    # Enterprise Editionのみの機能 (グループ同期など)
    # 'group_base' => 'ou=Groups,dc=yourcompany,dc=com',
    # 'admin_group' => 'GitLabAdmins', # LDAPグループに基づく管理者権限付与
    # 'sync_ssh_keys' => false
  }
}

LDAP設定後もgitlab-ctl reconfigureを実行して変更を適用します。