【実務・中級編】GitLab CI/CD入門：.gitlab-ci.ymlの書き方と基本構成をマスターする – バージョン管理・CI/CD活用バイブル

GitLab CI/CD極限活用術：`.gitlab-ci.yml`の真髄と開発スピードを爆発させる設計思想

こんにちは。テックリードの私たちが日々直面している最大の課題、それは「いかにしてデプロイの恐怖を取り除き、価値を高速でユーザーに届けるか」に他なりません。

GitLabは、単なるコードの置き場所ではありません。リポジトリ、Issue、Merge Request（MR）、そしてCI/CDがシームレスに統合された、「最強の単一アプリケーション（Single Application）」です。その中でもGitLab CI/CDは、正しく手なづければ、開発チームの生産性を劇的に跳ね上げる魔力を秘めています。

今回は、一般的な入門記事の枠を完全に超え、実務の現場で明日から使える「極限まで最適化された`.gitlab-ci.yml`の書き方」と、チーム開発を加速させるプロのハックを余すところなく伝授します。

—

1. 概念図解：GitLab CI/CDの全体像とパイプラインの哲学

まずは、GitLab CI/CDが頭の中でどう動いているか、そのメンタルモデルを同期しましょう。

[ Developer ] –( git push / MR )–> [ GitLab Repository ]
│
(.gitlab-ci.yml検知)
▼
┌──────────────────────────────────────────────────────────┐
│ Pipeline │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Stage │ │ Stage │ │ Stage │ │
│ │ (build) │──>│ (test) │ │ (deploy) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │ │ │
│ [Job A] [Job B] [Job C] │
└──────────────────────────────────────────────────────────┘

Pipeline（パイプライン）: 一連の自動化プロセスのトップレベル。
Stage（ステージ）: パイプラインを論理的に分割するグループ（例: Build -> Test -> Deploy）。同じステージ内のジョブは並列実行され、前のステージが成功しないと次のステージには進みません。
Job（ジョブ）: 実際にRunner上で実行される最小単位のコマンド群。

この構造をいかに美しく、かつ無駄なく記述するか。それが `.gitlab-ci.yml` の腕の見せ所です。

—

2. `.gitlab-ci.yml` の基本構文と「プロの作法」

まずは基本を押さえつつ、現場でスケーラブルな構成にするための構文を見ていきます。

必須の3大要素：`stages`, `jobs`, `script`

以下のサンプルを見てください。単なる「動くコード」ではなく、大規模開発でも破綻しない命名規則と構造化を取り入れています。

=====================================================================
グローバル設定
=====================================================================
default:
image: node:20-alpine # プロジェクト全体のデフォルトDockerイメージ
before_script:

echo “=== Job Execution Started: $CI_JOB_NAME ===”
node -v && npm -v

パイプラインの実行ステージを定義（左から右へ流れる）
stages:

lint
build
test
deploy

=====================================================================
ジョブ定義
=====================================================================

1. 静的解析（Lint）ジョブ
lint:code:
stage: lint
script:

npm ci
npm run lint

cache:
key: ${CI_COMMIT_REF_SLUG}-npm
paths:

node_modules/

rules:

if: ‘$CI_PIPELINE_SOURCE == “merge_request_event”‘ # MR作成時のみ実行

2. ビルドジョブ
build:artifact:
stage: build
script:

npm ci
npm run build

artifacts:
name: “dist-${CI_COMMIT_SHA}”
expire_in: 1 weeks # 1週間で自動削除しストレージを節約
paths:

dist/

dependencies:

lint:code

rules:

if: ‘$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH’
if: ‘$CI_PIPELINE_SOURCE == “merge_request_event”‘

3. テストジョブ
test:unit:
stage: test
script:

npm run test:unit

dependencies:

build:artifact

4. デプロイジョブ
deploy:staging:
stage: deploy
environment:
name: staging
url: https://staging.example.com
script:

echo “Deploying to Staging Environment…”
./scripts/deploy.sh

rules:

if: ‘$CI_COMMIT_BRANCH == “develop”‘

—

3. 開発スピードを劇的に高めるプロのハック

ここからが本題です。凡百のエンジニアと「一流のDevOpsエンジニア」を分ける、実践的な最適化テクニックを公開します。

① 隠れたキーボードショートカットでGitLabを爆速操作する

コードを書くのと同じくらい、GitLabのUI上での操作頻度も開発スピードに影響します。

`?` (Shift + /): どこにいても全キーボードショートカットのヘルプモーダルが開く（これマスト）。
`e`: ファイル表示画面で即座にWebIDE/エディターモードへ移行。
`c`: ファイルやコードの行に対して即座にコメント（Discussion）を追加。
`t`: ファイルファインダー起動（リポジトリ内のファイルを爆速検索）。

② チーム開発で役立つ「設定の共有化ルール」（`include`キーワードの極意）

モノレポや複数マイクロサービスを運用していると、`.gitlab-ci.yml`が何百行にも膨れ上がり、誰も読めないスパゲッティ状態になります。これを防ぐのが `include` です。

共通のCI/CDテンプレートを別リポジトリ（または同一リポジトリの `.gitlab/ci-templates/`）に切り出し、各プロジェクトからは数行でインクルードさせます。

各サービスの .gitlab-ci.yml はこれだけにする
include:

project: ‘company-infra/ci-templates’

ref: ‘main’
file: ‘/node-service-pipeline.yml’

個別のオーバーライドや環境変数のみここに書く
variables:
SERVICE_NAME: “user-api”

恩恵: セキュリティパッチや脆弱性スキャンのツールを変更した際、テンプレートを1箇所直すだけで全マイクロサービスのCI/CDが一斉にアップデートされます。

③ 賢いキャッシュ戦略でパイプライン時間を半分にする

`node_modules`や`vendor/`を毎回ゼロからダウンロードしていては時間がいくらあっても足りません。GitLab CIの `cache` と `artifacts` を明確に使い分けましょう。

`cache`: ジョブ間で「使い回す」もの（依存関係のパッケージなど）。ブランチ単位やキー単位で効率よくヒットさせます。
`artifacts`: ジョブ間で「受け渡す」もの（ビルドされた成果物）。次のステージのジョブはこれをダウンロードして使います。

cache:
key:
files:

package-lock.json # package-lock.jsonが変わった時だけキャッシュを無効化する神設定

paths:

node_modules/

policy: pull-push # デフォルトはpullしてpushする

—

4. 現場で即採用できる！実用的なYAMLベストプラクティス構成例

最後に、プロダクション環境で私たちが実際に採用している、洗練されたディレクトリ構造と設定ファイルのベストプラクティスを提示します。

推奨ディレクトリ構成

.
├── .gitlab/
│ └── ci/
│ ├── _templates.yml # 共通スニペットや再利用可能な定義
│ ├── build.gitlab-ci.yml
│ ├── test.gitlab-ci.yml
│ └── deploy.gitlab-ci.yml
├── .gitlab-ci.yml # エントリポイント（includeで結合するだけ）
└── src/

エントリポイントとしての `.gitlab-ci.yml`

.gitlab-ci.yml
各パーツを美しくルーティングするだけの司令塔にする

stages:

build
test
security
deploy

include:

local: ‘.gitlab/ci/build.gitlab-ci.yml’
local: ‘.gitlab/ci/test.gitlab-ci.yml’
local: ‘.gitlab/ci/deploy.gitlab-ci.yml’
template: Jobs/SAST.gitlab-ci.yml # GitLab公式のセキュリティスキャンを組み込む

この設計にしておくと、「テストの仕組みを変えたい時は `test.gitlab-ci.yml` を見る」「デプロイ先を追加したい時は `deploy.gitlab-ci.yml` を見る」と、認知負荷が劇的に下がります。

—

さいごに

GitLab CI/CDは、単にテストを自動化するためのツールではありません。「チームの心理的安全性を担保し、コードを自信を持って本番へ送り出すためのインフラストラクチャ」です。

今回紹介した設計思想やキャッシュ戦略、ファイル分割のテクニックをあなたのチームのパイプラインに導入すれば、ビルド待ちのイライラから解放され、より本質的なコードを書く時間に没頭できるようになります。

さあ、今すぐ `.gitlab-ci.yml` をリファクタリングし、チームの開発スピードを次の次元へと引き上げましょう！