【実務・中級編】GitLab Pagesで静的サイトを無料でホスティング！GitHub Pagesより便利？ – バージョン管理・CI/CD活用バイブル

GitLab Pagesの真の実力：GitHub Pagesを超えた自動化と、CI/CDパイプラインを極限まで加速する実践テクニック

テックリードの皆さん、日々のCI/CDパイプラインの最適化、本当にお疲れ様です。
「静的サイトのホスティング」と聞いて、まずGitHub Pagesを思い浮かべるエンジニアは多いでしょう。しかし、GitLabをメインストリームで使っているチームにとって、GitLab Pagesを使わないことは、手元にある最高峰のランチャーを使わずに手押し車で坂を登るようなものです。

単なる「無料の静的置場」として扱っていませんか？
GitLab Pagesの本質は、GitLab CI/CDの強大なオーケストレーション能力と直結している点にあります。ビルド、テスト、プレビュー環境の動的生成、そしてセキュアな配信までを、1つのプラットフォームで完結させる。その極限のワークフローを、プロの視点で徹底解説します。

—

1. なぜGitLab PagesがGitHub Pagesより「圧倒的に便利」なのか？

結論から言えば、「CI/CDエンジンとの結合度と柔軟性」が桁違いだからです。

任意のCI/CDツール不要: GitHub Pagesで複雑なビルド（Hugo, Jekyll, Nuxtなど）を走らせる場合、専用のGitHub Actionsを書くか、ローカルでビルドした成果物をコミットし直すというアンチパターンを踏みがちです。GitLab Pagesは、標準の`gitlab-ci.yml`の成果物（Artifacts）をそのままパブリックにマウントするだけなので、シームレスです。
Merge Requestごとの「プレビュー環境（Review Apps）」: これが最大のキラー機能です。コードを修正してMRを作った瞬間、そのブランチ専用のプレビュー用URLが自動生成され、デザインや挙動の確認が爆速で行えます。
強固なアクセス制御（GitLab Pages Access Control）: Enterprise/Ultimateプランに限らず、グループ設定やプロジェクト単位で「ログインユーザーのみ閲覧可能」に制限できます。社内ドキュメントや仕様書のホスティングにおいて、これ以上の選択肢はありません。

—

2. 実践：Hugo/Jekyllを最速でデプロイする `.gitlab-ci.yml` ベストプラクティス

百聞は一見に如かず。実務でそのまま使える、極限まで無駄を削ぎ落としたCI/CD設定ファイルを公開します。今回はモダンな静的サイトジェネレーターの代表格である Hugo を例取りますが、JekyllやAstroでも構造は同じです。

=====================================================================
GitLab Pages Production-Ready CI/CD Pipeline for Hugo
=====================================================================

workflow:
rules:
# デバッグビルドの無駄撃ちを防ぐため、デフォルトブランチとMR、タグのみで発火

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

stages:

build
test
deploy

variables:
GIT_SUBMODULE_STRATEGY: recursive
HUGO_VERSION: “0.111.3” # バージョンを固定し、ビルドの再現性を担保する

———————————————————————
1. Build Stage
———————————————————————
build:site:
stage: build
image:
name: klakegg/hugo:${HUGO_VERSION}-ext-alpine
entrypoint: [“”]
script:

hugo –minify –destination public

artifacts:
name: “hugo-artifacts-$CI_COMMIT_REF_SLUG”
expire_in: 1 days # ストレージ容量を圧迫しないよう短めに設定
paths:

public

rules:

if: ‘$CI_COMMIT_BRANCH’

———————————————————————
2. Test Stage (Link Checker & Security)
———————————————————————
test:links:
stage: test
image: alpine:latest
dependencies:

build:site

script:
# リンク切れがないかを検証するプロセスの例（必要に応じてhtmlproofer等に変更）

echo “Running internal link validation…”
grep -rn “http://localhost” public/ && exit 1 || echo “Link check passed.”

allow_failure: true

———————————————————————
3. Deploy Stage (GitLab Pages Reserved Job Name)
———————————————————————
pages:
stage: deploy
image: alpine:latest
dependencies:

build:site

script:

echo “Deploying static files to GitLab Pages…”

# GitLab Pagesは必ず ‘public’ というディレクトリ名を探しに行く仕様
artifacts:
paths:

public

rules:

if: ‘$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH’

environment:
name: production
url: $CI_PAGES_URL

この設定のこだわりポイント

`GIT_SUBMODULE_STRATEGY: recursive`: テーマをGitサブモジュールとして管理しているプロジェクトでも、設定一つで確実に依存関係を解決します。
成果物の有効期限（`expire_in`）: デフォルトのままだとストレージがゴミファイルで溢れます。静的サイトのビルド成果物は数日経てば再生成できるため、`1 days` で十分です。
ジョブ名 `pages`: GitLab Pagesの公式仕様として、デプロイを実行するジョブ名は必ず `pages` である必要があります。ここを間違えると一生デプロイされません。

—

3. 開発スピードを爆上げする「プロの隠し技」

ここからは、チーム全体の開発体験（DX）を一段引き上げるための実践テクニックです。

① WebIDEとキーボードショートカットで秒速修正

ローカル環境を立ち上げるまでもないタイポの修正や、マークダウンの微調整には、GitLab内蔵の Web IDE を使います。

`Ctrl` + `.` (Macでは `Cmd` + `.`): リポジトリ内のファイルを瞬時に検索して開く。
`Ctrl` + `Shift` + `P`: コマンドパレットを開き、各種操作をキーボードだけで完結させる。

Web IDEで変更を加え、コミット＆MR作成までをブラウザータブを切り替えずに完結させることで、CONTEXT SWITCHING（文脈の切り替え）コストをゼロに近づけられます。

② チーム開発を加速する「共有設定テンプレート（CI/CD Components）」

複数チームで静子サイトを乱立させる場合、毎回同じようなYAMLを書かせるのはテックリードの怠慢です。GitLabの CI/CD Components 機能（または従来の `include:project`）を使い、組織共通の「静人サイトホスティング・テンプレート」を作成しましょう。

.gitlab/ci/templates/static-pages.yml としてリポジトリ（または共通プロジェクト）に配置
spec:
inputs:
hugo_version:
default: “0.111.3”
type: string
—
stages:

build
deploy

build_and_deploy_pages:
stage: build
image: klakegg/hugo:$[[ inputs.hugo_version ]]-ext-alpine
script:

hugo –minify –destination public

artifacts:
paths:

public

rules:

if: ‘$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH’

pages:
stage: deploy
dependencies:

build_and_deploy_pages

script:

echo “Pages deployed successfully.”

artifacts:
paths:

public

rules:

if: ‘$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH’

各プロジェクト側では、たったこれだけの行数を書くだけでセキュアでモダンなPagesパイプラインが即座に手に入ります。

include:

project: ‘my-org/ci-templates’

file: ‘/static-pages.yml’
inputs:
hugo_version: “0.111.3”

—

4. トラブルシューティング：ありがちな「ハマりどころ」

GitLab Pagesを運用する上で、誰もが一度は踏む地雷と、その回避策をシェアします。

1. 404 Not Found エラーが消えない

原因: プロジェクトのルートディレクトリに `public` フォルダが出力されていない、あるいは出力先のパスが間違っている。
対策: `artifacts: paths: – public` が正しく設定されているか、ビルドコマンドの出力先（`–destination public` など）が一致しているかをジョブのログで確認してください。

2. カスタムドメインでSSL/TLS証明書が発行されない

原因: Let’s Encryptの自動発行プロセスにおいて、DNSのTXTレコードやCNAMEの設定が伝播しきっていない。
対策: GitLabの設定画面でカスタムドメインを追加後、DNSレコードが正しく引けることを `dig` コマンド等で確認し、数分〜数時間待ちます。大半はDNSのTTL設定のミスです。

3. サブグループ（Subgroups）でのパス解決エラー

原因: `https://namespace.gitlab.io/project-name/` のように、ルート直下ではなくサブパスでホスティングされるため、絶対パスで指定したアセット（CSS/JS/画像）が読み込めなくなる。
対策: Hugoの `config.toml` の `baseURL` に `$CI_PAGES_URL` を動的に埋め込むか、相対パス（Relative URLs）を有効にしてください（例: Hugoなら `relativeURLs = true`）。

—

まとめ：GitLab Pagesで「静的サイトの民主化」を推し進めろ

GitLab Pagesは、単なる「無料のウェブサーバー」ではありません。
GitLab CI/CDの強大なパイプライン、レビュー環境、そしてコード管理が三位一体となった、エンジニアのための強力なパブリッシング・プラットフォームです。

今日からあなたのチームでも、面倒なサーバー管理や複雑なデプロイ手順を捨て、GitLab Pagesと洗練されたCI/CD YAMLによる「オートメーション・ファースト」の文化を根付かせてみませんか？開発スピードの次元が変わることを、私が保証します。