TDCソフト Advent Calendar 2025

TDCソフト株式会社

CentOS7で構築済のGitlabに対してGitlab CIを使用可能にする

Last updated at 2025-12-07Posted at 2025-12-07

環境

OS: CentOS Linux release 7.9.2009 (Core)
サーバー: AWS EC2
- GitLabサーバー: 172.16.xxx.xxx (gitlab.example.com)
Docker: バージョン 26.1.4
GitLab: バージョン 17.3.3
GitLab Runner: バージョン 18.6.2

GitLab Runnerの構築

1. Dockerデーモンの起動

# Dockerサービスの状態確認
sudo systemctl status docker

# Dockerデーモンを起動
sudo systemctl start docker

# システム起動時に自動起動を有効化
sudo systemctl enable docker

2. GitLab Runnerコンテナの起動

# Runnerコンテナを起動(ネットワークホストモード)
sudo docker run -d --name gitlab-runner --restart always \
  --network host \
  -v /srv/gitlab-runner/config:/etc/gitlab-runner \
  -v /var/run/docker.sock:/var/run/docker.sock \
  gitlab/gitlab-runner:latest

# コンテナの起動確認
sudo docker ps | grep gitlab-runner

ポイント: --network host を使用することで、Runnerコンテナがホストのネットワークスタックを共有します。ただし、最終的にはRunnerの設定でurlとclone_urlにホストのプライベートIPアドレス(172.16.xxx.xxx)を指定する必要があります。

Runnerの登録

1. Runnerの登録コマンド

sudo docker exec -it gitlab-runner gitlab-runner register

2. 登録時の入力内容

項目	入力値	説明
GitLab instance URL	`http://localhost`	GitLabサーバーのURL(後で設定ファイルで変更)
Registration token	`glrt-xxxxxxxxxxxxxxxxxxxxx`	GitLabのSettings > Runners作成時に取得
Description	`my-runner`	Runnerの説明
Tags	`docker,linux`	ジョブとRunnerをマッチングするためのタグ
Executor	`docker`	Docker Executorを使用
Default Docker image	`ruby:3.3`	デフォルトのDockerイメージ

注意: 登録時はhttp://localhostを指定していますが、後で設定ファイルを編集してプライベートIPアドレス(http://172.16.xxx.xxx)に変更する必要があります。

3. 登録の確認

# Runnerの状態確認
sudo docker exec -it gitlab-runner gitlab-runner verify

# Runnerリストの確認
sudo docker exec -it gitlab-runner gitlab-runner list

CI/CDパイプラインの設定

1. プロジェクトでCI/CD機能を有効化

GitLabのWeb UI:

Settings → General
Visibility, project features, permissions を展開
CI/CD をONにして保存

2. `.gitlab-ci.yml`の作成

プロジェクトルートに.gitlab-ci.ymlを作成する。今回はテスト用にechoコマンドのみを記載しますが、プロジェクトごとに必要なビルドやテストのコードを記載しましょう。:

image: alpine:latest

stages:
  - build
  - test
  - deploy

build-job:
  stage: build
  tags:
    - docker
  script:
    - echo "Building the application..."
    - echo "Build completed successfully"

test-job:
  stage: test
  tags:
    - docker
  script:
    - echo "Running tests..."
    - echo "All tests passed"

deploy-job:
  stage: deploy
  tags:
    - docker
  script:
    - echo "Deploying application..."
    - echo "Deployment completed"
  only:
    - main

重要なポイント:

image: alpine:latest: Docker Executorの場合、デフォルトイメージの指定が必須。Runnerのデフォルトイメージがruby:3.3でも、.gitlab-ci.ymlで指定したイメージ(alpine:latest)が優先される
tags: Runnerに設定したタグと一致させる必要がある
only: - main: デプロイジョブはmainブランチのみで実行

3. コミット&プッシュ

git add .gitlab-ci.yml
git commit -m "Add CI/CD configuration with Docker image"
git push origin katsumura_ci_test

発生したエラーと解決方法

基本的には上記手順ですが、dockerおよびGitlab Runnerで発生するであろうエラーの対処についてピックアップします。

エラー1: Dockerデーモンが起動していない

エラーメッセージ:

Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

原因: Dockerサービスが起動していない。単純なミスですので気を付けましょう。

解決方法:

sudo systemctl start docker
sudo systemctl enable docker

エラー2: 古いDockerバージョンの問題

エラーメッセージ:

/usr/bin/docker-current: missing signature key

原因: CentOSの古いDockerパッケージ(docker-current)を使用している。

解決方法: Docker CEに更新

# 古いDockerを削除
sudo yum remove docker docker-common docker-selinux docker-engine

# Docker CEリポジトリを追加
sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

# Docker CEをインストール
sudo yum install -y docker-ce docker-ce-cli containerd.io

# 起動
sudo systemctl start docker
sudo systemctl enable docker

エラー3: コンテナ名の競合

エラーメッセージ:

Conflict. The container name "/gitlab-runner" is already in use

原因: 同じ名前のコンテナが既に存在している

解決方法:

# 既存のコンテナを停止・削除
sudo docker stop gitlab-runner
sudo docker rm gitlab-runner

# 新しくコンテナを作成
sudo docker run -d --name gitlab-runner --restart always \
  --network host \
  -v /srv/gitlab-runner/config:/etc/gitlab-runner \
  -v /var/run/docker.sock:/var/run/docker.sock \
  gitlab/gitlab-runner:latest

エラー4: Registration tokenによる登録が無効化

エラーメッセージ:

ERROR: Registering runner... failed
status=POST http://localhost/api/v4/runners: 410 Gone

原因: GitLab 16.0以降、古いRegistration tokenによる登録方法が廃止された。glrtから始まるtoken名を記載します。Runnerを作成する際にのみ表示されますので、忘れずにメモしましょう。

解決方法: 新しい登録方法を使用

GitLab UI: Settings → CI/CD → Runners → New project runner
タグを設定して「Create runner」をクリック
表示された登録コマンドを実行:

sudo docker exec -it gitlab-runner gitlab-runner register \
  --url http://localhost \
  --token glrt-xxxxxxxxxxxxxxxxxxxxx

エラー5: Runnerコンテナから`localhost`に接続できない

エラーメッセージ:

fatal: unable to access 'http://localhost/bplinks/3.5_dev.git/': 
Failed to connect to localhost port 80

原因: Runnerコンテナ内のlocalhostはコンテナ自身を指すため、ホストのGitLabに接続できない

解決方法: clone_urlの設定とnetwork_modeの追加

# Runner設定ファイルを編集
sudo vi /srv/gitlab-runner/config/config.toml

設定内容:

[[runners]]
  name = "my-runner"
  url = "http://172.16.xxx.xxx"
  clone_url = "http://172.16.xxx.xxx"
  executor = "docker"
  [runners.docker]
    image = "ruby:3.3"
    volumes = ["/cache"]
    network_mode = "host"

重要な設定項目:

url: Runner APIの接続先(ホストのIPアドレス)
clone_url: Gitリポジトリのクローン元(ホストのIPアドレス)
network_mode = "host": Runnerコンテナがホストのネットワークを使用

# Runnerを再起動
sudo docker restart gitlab-runner

エラー6: Git cloneのタイムアウト

エラーメッセージ:

fatal: unable to access 'https://gitlab.example.com/mygroup/myproject.git/': 
Connection timed out after 300029 milliseconds

原因: RunnerがGitLabサーバーの外部URLにアクセスしようとして、ネットワーク接続がタイムアウト

解決方法: 上記のclone_url設定により、プライベートIPアドレス経由でアクセスするように変更

Runnerの設定確認コマンド集

# Runnerの設定ファイル確認
sudo docker exec -it gitlab-runner cat /etc/gitlab-runner/config.toml

# Runnerの状態確認
sudo docker exec -it gitlab-runner gitlab-runner verify

# Runnerのログ確認
sudo docker logs gitlab-runner

# Runnerのリアルタイムログ監視
sudo docker logs -f gitlab-runner

# Runnerリストの確認
sudo docker exec -it gitlab-runner gitlab-runner list

# コンテナの状態確認
sudo docker ps | grep gitlab-runner

最終的なRunner設定ファイル

/srv/gitlab-runner/config/config.toml:

concurrent = 1
check_interval = 0
shutdown_timeout = 0

[session_server]
  session_timeout = 1800

[[runners]]
  name = "my-runner"
  url = "http://172.16.xxx.xxx"
  clone_url = "http://172.16.xxx.xxx"
  id = 3
  token = "glrt-xxxxxxxxxxxxxxxxxxxxx"
  token_obtained_at = 2025-12-07T12:00:00Z
  token_expires_at = 0001-01-01T00:00:00Z
  executor = "docker"
  [runners.cache]
    MaxUploadedArchiveSize = 0
    [runners.cache.s3]
    [runners.cache.gcs]
    [runners.cache.azure]
  [runners.docker]
    tls_verify = false
    image = "ruby:3.3"
    privileged = false
    disable_entrypoint_overwrite = false
    oom_kill_disable = false
    disable_cache = false
    volumes = ["/cache"]
    shm_size = 0
    network_mtu = 0

パイプラインの実行確認

GitLab UIでの確認方法

Pipelinesページ: Build → Pipelines
Jobsページ: Build → Jobs
Commitsページ: Code → Repository → Commits (各コミットの右側にパイプラインステータスが表示される)

手動実行

Build → Pipelines
右上の Run pipeline ボタンをクリック
ブランチを選択して Run pipeline をクリック

まとめ

構築のポイント

Dockerの準備: 最新のDocker CEを使用する
ネットワーク設定: --network hostでRunnerコンテナを起動
Runner登録: GitLab 16.0以降は新しいトークン方式を使用
設定ファイル: clone_urlとnetwork_modeを適切に設定
CI/CD機能: プロジェクトでCI/CD機能を有効化する
タグの一致: .gitlab-ci.ymlのタグとRunnerのタグを一致させる

トラブルシューティングのコツ

ログの確認: sudo docker logs gitlab-runnerで問題を特定
設定の確認: config.tomlの内容を確認
ネットワーク: 同じサーバー上ではプライベートIPまたはlocalhostを使用
段階的テスト: 手動でパイプラインを実行してテスト

参考資料

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

CentOS7で構築済のGitlabに対してGitlab CIを使用可能にする

目次

環境

GitLab Runnerの構築

1. Dockerデーモンの起動

2. GitLab Runnerコンテナの起動

Runnerの登録

1. Runnerの登録コマンド

2. 登録時の入力内容

3. 登録の確認

CI/CDパイプラインの設定

1. プロジェクトでCI/CD機能を有効化

2. .gitlab-ci.ymlの作成

3. コミット&プッシュ

発生したエラーと解決方法

エラー1: Dockerデーモンが起動していない

エラー2: 古いDockerバージョンの問題

エラー3: コンテナ名の競合

エラー4: Registration tokenによる登録が無効化

エラー5: Runnerコンテナからlocalhostに接続できない

エラー6: Git cloneのタイムアウト

Runnerの設定確認コマンド集

最終的なRunner設定ファイル

パイプラインの実行確認

GitLab UIでの確認方法

手動実行

まとめ

構築のポイント

トラブルシューティングのコツ

参考資料

2. `.gitlab-ci.yml`の作成

エラー5: Runnerコンテナから`localhost`に接続できない