GitLab Runnerを使ったCI/CD入門｜初心者向けにわかりやすく解説

はじめに

ソフトウェア開発の現場で、GitLab Runner が注目を集めています。
これはGitLabと連携して自動テストやビルド、デプロイなどを行う役割を担います。
近年は、少人数で作業するプロジェクトでも積極的にCI/CD（継続的インテグレーションと継続的デリバリー）を導入し、開発をスムーズに進める流れが広まっていますね。
しかし一方で、CI/CDに馴染みのない人にとっては「どこから手をつければいいのか」「どうやってセットアップすれば良いのか」が分かりにくいかもしれません。
そこでこの記事では、GitLab Runnerの基本を平易な言葉で解説し、実務での活用手順やコード例を交えて紹介します。

この記事を読むとわかること

• GitLab Runnerの概要と仕組み
• GitLab Runnerを導入するメリット
• 基本的なインストールや登録の手順
• よくあるCI/CDパイプラインの事例と活用ポイント

GitLab Runnerとは何か

GitLab Runnerは、GitLabのCI/CD機能を実行するためのツールです。
皆さんがGitLabリポジトリに変更をプッシュしたとき、自動でテストやビルドを実行して結果を通知してくれます。
一連の動作を担うのがGitLab Runnerであり、プロジェクトごとに動作環境を整え、自動化の仕組みを手軽に構築できるようになります。

GitLab CIとの関係

GitLab CIは、GitLabの中でビルドやテスト、デプロイなどのワークフローを定義する仕組みです。
具体的には .gitlab-ci.yml という設定ファイルを使い、「どのステージで何をするか」を記述します。
実際にその記述どおりにジョブ（作業）を実行するのが、GitLab Runnerの役割です。
Runner自体はサーバーでもローカルマシンでも動作できます。
そのため、テストに必要な環境を手元に用意しながら動作させることもできますし、Dockerコンテナを使って安全に実行することも可能です。

実務での活用シーン

多くの開発現場では、マージリクエストやプルリクエストを通して新しい機能を追加します。
しかしテストを手動で行っていると抜け漏れが生じたり、作業時間が長くなったりするリスクがありますよね。
GitLab Runnerを使うと、コードがプッシュされるたびに自動でテストが走るため、品質管理がしやすくなります。
結果はGitLabの画面に集約され、修正が必要な箇所がすぐに分かるので、開発効率を高める一助となるでしょう。

GitLab Runnerを使うメリット

GitLab Runnerの導入には、いくつかのメリットがあります。
ここでは主なものを取り上げてみます。

テストやデプロイの自動化

テストやビルド、デプロイを自動で実行できるため、人間が行う単純作業を減らせます。
日常的にテストを走らせるようになれば、不具合を早期に発見して対処しやすくなるでしょう。
その結果、開発サイクルが短縮されて、不要なトラブルの発生リスクを減らせるというわけです。

環境ごとの柔軟な構成

RunnerはホストOS上で直接動かすことも可能ですし、Dockerや仮想マシン上で起動することもできます。
たとえばプロジェクトAではDockerコンテナを使ってNode.js環境を構築し、プロジェクトBでは別のDockerイメージを使ってPython環境を構築するなど、プロジェクト単位で柔軟に設定を切り替えられます。

チーム全体での品質向上

GitLab Runnerはチーム全員が同じテスト結果を共有できる点も魅力です。
開発者ごとにテスト環境が異なっていて動作結果が変わるような問題を最小化できます。
また、コードをプッシュした直後にテスト結果がメールやSlackなどで通知されるので、作業の抜け漏れを防ぐことにつながります。

GitLab Runnerの仕組み

GitLab Runnerは、GitLabサーバーと通信を行い、指定されたジョブを実行します。
ジョブとは「テストを実行する」「ビルドして成果物を生成する」「アプリケーションをデプロイする」などの作業を指します。
ここでは大まかな流れを見ていきましょう。

GitLabからジョブを受け取る

RunnerがGitLabに登録されると、ジョブの割り当てを受けられるようになります。
例えば、特定のブランチにコードがプッシュされたときにテストジョブがキックされるように設定しておくと、Runnerはそのリクエストを受け取ります。
そして指定されたイメージや環境でテストを実行し、結果をGitLabに送り返します。

結果のレポーティング

Runnerは作業完了後、結果をGitLabにレポートします。
ここで合格ならパイプラインの次のステージに進み、失敗ならパイプラインがストップするといった流れを制御します。
結果的に、GitLab上でテストの成功・失敗を可視化できるため、トラブル箇所をスピーディに特定できる仕組みが整うわけです。

GitLab Runnerの導入手順

ここでは、Linux環境にRunnerをインストールし、GitLabと連携する基本的な流れを紹介します。
Dockerを用いるケースも多いですが、まずはシンプルにホストOSに直接インストールする例を見ていきましょう。

インストールと登録コマンド例

コピー
# パッケージのリポジトリを追加
curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | sudo bash

# GitLab Runnerのインストール
sudo apt-get update
sudo apt-get install gitlab-runner

# GitLab Runnerの登録
sudo gitlab-runner register

上記の例はDebian系Linuxを想定したものです。
途中で表示される対話形式の画面で、GitLabのURLとプロジェクト側で発行された登録用トークンを入力すれば連携が完了します。
その際、Runnerの実行バージョンやタグ、説明などを聞かれますが、必要に応じて設定してください。

実務で役立つ設定ポイント

登録時にタグを付けられるので、複数のRunnerを使い分けたい場合に便利です。
たとえば、Docker環境でのみテストを動かすRunnerには docker-test のタグを、単純なビルド専用Runnerには build-only のタグを付けるなど、運用しやすい形に整理すると良いでしょう。

GitLab Runnerを活用したCI/CDパイプライン例

実際のパイプラインは .gitlab-ci.yml によって制御されます。
ここでは、Node.jsプロジェクトでテストとビルドを実行するシンプルな例を示します。

コピー
stages:
  - test
  - build

test-job:
  stage: test
  script:
    - npm install
    - npm test
  tags:
    - docker-test

build-job:
  stage: build
  script:
    - npm run build
  tags:
    - docker-test

上記では、2つのステージ（testとbuild）を定義し、それぞれ対応するジョブを記述しています。
さらに、Runnerで登録したタグ docker-test を指定することで、Docker環境で動作するRunnerがこのジョブを受け取る仕組みになっています。
テストでエラーがあればここで検出され、修正すべき点を早めに把握できますね。

パイプラインを効率化するポイント

ジョブを細かく分割する

テストやビルド、セキュリティ診断などを細かく分類しておくと、問題が発生した箇所を特定しやすくなります。

キャッシュの活用

依存ライブラリなどのダウンロードに時間がかかる場合は、キャッシュ機能を使ってパイプラインを高速化できることがあります。

実務でありがちな活用パターン

GitLab Runnerの設定はプロジェクトの規模や目的によってさまざまです。
ここでは、よく目にする2つのパターンを紹介します。

Webアプリケーションの自動テストとビルド

ウェブサービスを運営するチームでは、プッシュのたびに自動でテストを走らせるケースが一般的です。
複数のブランチで活発に開発が進む場合も、それぞれのブランチでテスト結果を確認できるため、コードの品質を安定させやすいでしょう。
ビルド後に成果物を生成し、ステージング環境へ自動デプロイする流れまで組み合わせると、リリース作業の手間を軽減できます。

マイクロサービス構成での利用

最近は、マイクロサービスとして機能を細分化し、それぞれを独立して開発・デプロイする形が増えています。
この場合、サービスごとにRunnerを立ち上げることもあれば、共通のRunnerでタグを分けて管理することもあります。
GitLab Runnerを併用することで、サービス単位のテストや依存関係のチェックを自動化し、大規模プロジェクトでも運用しやすい形に持っていけるのです。

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

Runnerを運用していると、意図しないエラーに遭遇するケースもあります。
ここではよくあるトラブルと、その際に確認しておきたいポイントをまとめます。

Runnerがジョブを受け取らない

ジョブが一向に走らずに「Pending」状態になることがあります。
その場合は以下の点をチェックしてみてください。

• Runnerの登録が完了しているか
• .gitlab-ci.yml のタグ設定が正しいか
• Runnerのステータスが「active」になっているか

特にタグが不一致だと「Runnerは稼働しているのにジョブが割り振られない」という状況に陥りやすいです。

実行環境の差分によるテスト失敗

ローカルマシンでは問題なく通るテストが、Runner上では失敗する場合があります。
このときは以下のような点を疑いましょう。

• 依存ライブラリのバージョンが違う
• Dockerイメージの中に必要なパッケージが含まれていない
• パスの指定やファイル名（大文字・小文字）が食い違っている

環境差を最小限に抑えるために、Dockerコンテナで統一した環境を使うか、設定ファイル .gitlab-ci.yml にすべての依存関係を明記することが大切です。

まとめ

ここまで、GitLab Runner を使ったCI/CDの基本から導入手順、実務での活用シーン、そしてトラブルシューティングのコツまでを紹介してきました。
最初は設定に戸惑うかもしれませんが、Runnerを活用することでテストやデプロイの安定性が増し、チーム全体の開発効率が向上しやすくなります。
最小限のステップでも十分に自動化の効果を実感できるはずです。
少しずつ慣れていきながら、皆さんのプロジェクトに適した形で活用してみてはいかがでしょうか。