GitLab Pagesは、GitLabのリポジトリに置いたHTMLや静的サイトジェネレーターの出力を、CI/CDのジョブ経由でgitlab.ioなどのドメインへ公開する機能です。この記事では、GitLab Pagesとは何かを公式ドキュメントで確かめたうえで、最小の.gitlab-ci.yml、ViteやHugoの成果物を出す設定、独自ドメインとアクセス制御の値を順に示します。後半はGitHub Pagesとの違いを比較表にまとめ、どちらを選ぶかの判断を書きました。仕様と上限値は2026年11月時点のGitLab.comの公式ドキュメントにもとづきます。
まとめ：GitLab PagesはCIのpagesジョブで静的サイトを出す無料機能
GitLab Pagesは、Freeを含む全プランで使える静的サイトのホスティングです。.gitlab-ci.ymlのジョブにpages: trueを書き、publicフォルダ（またはpages.publishで指定したフォルダ）に成果物を置けば公開されます。PHPのようなサーバー側の処理は動きません。
GitHub Pagesとの差で効くのは、閲覧をプロジェクトメンバーに絞るアクセス制御がFreeから使える点です。GitHub側の同等機能はGitHub Enterprise Cloudに限られます。すでにGitLabでコードとCIを回しているなら社内向けドキュメントの公開先として素直な選択で、逆にGitHubが主のチームがPagesのためだけにGitLabを足す理由はありません。
GitLab Pagesとは：リポジトリからgitlab.ioへ静的サイトを公開する機能
GitLab Pagesの定義と対応プラン：Freeを含む全プラン・3つの提供形態
公式ドキュメント「GitLab Pages」は、この機能を「GitLabのリポジトリから静的サイトを直接公開する」ものと定義しています。対象プランはFree・Premium・Ultimateのすべてで、提供形態もGitLab.com、GitLab Self-Managed、GitLab Dedicatedという3つの形態が対象です。Hugo、Jekyll、Gatsbyなどのジェネレーターのほか、素のHTML・CSS・JavaScript・Wasmもそのまま置けます。
デプロイはGitLab CI/CDのパイプラインが担います。ジョブを実際に動かすのはRunnerで、GitLab.comでは共有のインスタンスRunnerが既定で有効です。自前のRunnerを使う場合の準備はGitLab Runnerのexecutorの選び方と登録手順で解説しています。GitLab全体の構成とCE・EEの違いはGitLabの構成要素と3つの提供形態を参照してください。
公開URLの形式：ユーザー・グループ・プロジェクトで変わるgitlab.ioの付き方
公開されるURLは、プロジェクトの持ち主と名前で決まります。既定のドメインとURLのドキュメントの例を並べました。
# 種類：プロジェクトのパス → 公開URL
ユーザーサイト ：username/username.gitlab.io → https://username.gitlab.io
グループサイト ：acmecorp/acmecorp.gitlab.io → https://acmecorp.gitlab.io
プロジェクトサイト ：username/my-website → https://username.gitlab.io/my-website
サブグループ配下 ：acmecorp/documentation/product-manual → https://acmecorp.gitlab.io/documentation/product-manual新規プロジェクトでは「Use unique domain」が既定で有効になり、my-website-123456.gitlab.ioのようにプロジェクト名と6文字のIDを組み合わせたドメインが割り当てられます。上の表の形式でアクセスすると、308でこの固有ドメインへ転送されます。同じグループ内の別プロジェクトとCookieを共有させないための仕組みです。Self-Managedではgitlab.ioの部分が自社インスタンスのPagesドメインに置き換わります。
GitLab Pagesでできないこと：PHPなどサーバー側の処理と容量の上限
公式ドキュメントは「.phpや.aspのようなサーバー側の動的処理はサポートしない」と明記しています。問い合わせフォームの送信やログイン後の画面生成は、別のAPIサーバーか外部サービスで受ける必要があります。
容量の上限はGitLab.comの設定一覧に載っています。サイトの最大サイズは1GBで、これはCI/CDの成果物（artifacts）の圧縮後上限1GBに連動する値です。独自ドメインは1サイトにつき150件まで登録できます。動画や大量の画像を置くと1GBに届きやすいため、重いファイルはオブジェクトストレージへ逃がす設計にしておくと後で困りません。
GitLab Pagesの静的サイト公開：.gitlab-ci.ymlの記述と確認手順
HTML用.gitlab-ci.yml：pages: trueとrulesの最小設定
手書きのHTMLをそのまま出すなら、ジョブは1つで足ります。GitLab Pagesの設定ドキュメントの例をもとに、リポジトリ直下のファイルをpublicへ集めて公開する形にしました。
# .gitlab-ci.yml（リポジトリ直下に置く）
create-pages:
script:
- mkdir .public
- cp -r * .public # リポジトリ直下のファイルを一時フォルダへ集める
- mv .public public # 公開対象は既定で public フォルダ
pages: true # このジョブを Pages のデプロイ用ジョブとして扱う
rules:
- if: $CI_COMMIT_BRANCH == "main" # main への反映時だけ公開するジョブ名は自由で、目印になるのはpages: trueのほうです。pages: falseと書いたジョブはデプロイされません。見落としやすいのはrulesで公開ブランチを絞る指定で、絞らないと作業ブランチへのpushのたびに本番のサイトが上書きされます。publicフォルダ自体はコミット不要で、ビルドの途中で作れば足ります。
ViteやHugoのビルド成果物をpages.publishでdistのまま公開する設定
ViteのdistやNext.jsのoutのように、ツールの出力先がpublicではない場合はpages.publishで公開フォルダを指定します。設定ドキュメントの履歴では、この指定は16.1で導入され、17.9でpagesキーの下へ移りました。トップレベルのpublishは17.9で非推奨です。17.10からはpages.publishのパスがartifacts:pathsへ自動で足されるため、成果物の指定も省けます。
# Vite でビルドして dist をそのまま公開する例
image: node:22
create-pages:
script:
- npm ci
- npm run build # vite build で dist/ が生成される
pages:
publish: dist # 公開フォルダを public から dist へ変更
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH17.9より古いSelf-Managedではpages.publishが通りません。その場合はpublicフォルダのドキュメントのNext.jsの例と同じく、mv out/* publicのように出力をpublicへ移す書き方に戻します。同ページにはAstro・Nuxt・SvelteKit・Eleventy・Webpackの出力先の変え方もまとまっています。
Deploy > Pagesでの公開確認とpages:deployの失敗原因
パイプラインが成功すると、自分で書いたジョブの後ろにpages:deployという特別なジョブが現れます。ゼロから作るチュートリアルによれば、このジョブの実行場所はRunnerではなくGitLab側です。公開URLはプロジェクトのDeploy > Pagesで確認できます。
よくある失敗は2つです。1つ目は、公開フォルダの直下に中身のあるindex.htmlが無く、pages:deployが失敗するケース。ビルドの出力先がdist/clientのように1段深いと起きます。2つ目はプロジェクトサイトで画像やCSSが404になるケースで、URLに/my-website/のパスが付くのに、ジェネレーター側のベースパスが/のままになっていることが原因です。Viteならbase、HugoならbaseURLをプロジェクトのURLに合わせます。
独自ドメイン・アクセス制御・リダイレクトの設定：運用で触る3つの機能
独自ドメインのDNS設定：A・AAAA・CNAMEとTXT所有権確認レコードの値
独自ドメインを使う場合は、DNSに転送先と所有権確認の2種類のレコードを入れます。独自ドメインのドキュメントに載っているGitLab.com向けの値は次のとおりです。
# ルートドメイン（example.com）の場合
example.com. A 35.185.44.232
example.com. AAAA 2600:1901:0:7b8a::
# サブドメイン（docs.example.com）の場合
docs.example.com. CNAME namespace.gitlab.io.
# 所有権確認（値は Deploy > Pages の画面に表示されるコードを使う）
_gitlab-pages-verification-code.example.com. TXT "gitlab-pages-verification-code=<発行されたコード>"ルートドメインにはCNAMEを置けないため、AとAAAAを使います。DNSの管理画面によっては名前欄に自動でドメインが付くので、その場合に名前欄へ入力する値は_gitlab-pages-verification-codeだけです。証明書はLet’s Encryptとの連携をオンにすれば、GitLabが取得と更新を引き受けます。17.8からは複数ドメインのうち1つを主ドメインにし、他を308で転送する指定もできます。
Pagesのアクセス制御：プロジェクトメンバー限定で社内文書を公開する設定
GitLab.comでは、Pagesのサイトは既定で誰でも見られます。社内の設計書や手順書を置くなら、Pagesのアクセス制御で閲覧者を絞ります。この機能もFreeから利用可能です。設定場所はSettings > General > Visibility, project features, permissionsの中にあるPagesの項目です。
選べる範囲はプロジェクトの公開範囲で変わります。Privateのプロジェクトなら「Only Project Members」か「Everyone」、Internalならこれに「Everyone With Access」（ログイン済みのユーザー）が加わります。変更が反映されるまでにかかる時間の目安は、通常1分ほどです。17.10ではread_apiスコープのアクセストークンによる認証も入り、ブラウザを使わないスクリプトから非公開サイトを取得できるようになりました。
_redirectsと404.html：URL移転とエラーページで押さえる上限と非対応
公開フォルダの直下に404.htmlと403.htmlを置くと、独自のエラーページになります。プロジェクトサイトでは/my-website/404.htmlを先に探し、無ければルートの/404.htmlを使う順序です。
URLの移転は_redirectsファイルで書きます。リダイレクトのドキュメントによると、使えるステータスは301・302・200の3種で、省略すると301です。既定の上限はファイル64KB・1,000ルールで、超えた分は処理されません。クエリパラメータでの振り分けや国・言語別の転送には対応していないため、Netlifyから移す場合は書いてあるルールがそのまま動くか1行ずつ確かめます。既定ドメインのプロジェクトサイトでは/my-website/old.html /my-website/new.html 301のようにプロジェクト名のパスを付ける点も見落としやすいところです。
GitLab PagesとGitHub Pagesの違い：上限・ビルド方式・閲覧制限で比較
比較表：サイズ上限・ビルドの仕組み・非公開サイトの対応プラン
両者とも静的サイト専用で、サイズ上限も1GBで同じです。差が出るのは、ビルドをどこで動かすかと、閲覧者を絞れるプランです。GitHub側の値はGitHub Pagesの制限と公開範囲の変更のドキュメントから取りました。
| 観点 | GitLab Pages | GitHub Pages |
|---|---|---|
| サイズ上限 | 1GB | 1GB |
| ビルドの場所 | GitLab CI/CD | ブランチかActions |
| ビルド回数の目安 | CI/CDの枠に従う | 1時間10回（ソフト） |
| 帯域の目安 | 公開上限の記載なし | 月100GB（ソフト） |
| 閲覧者の限定 | Freeから可 | Enterprise Cloudのみ |
GitHub Pagesの1時間10回というビルドの目安は、GitHub Actionsのワークフローで自前にビルドする場合には適用されません。GitHub Pagesの料金や商用利用の条件はGitHub Pagesの料金・無料の範囲と容量制限で詳しく扱っています。リポジトリ管理とCIを含めたサービス全体の比較はGitHubとGitLabの違い（ActionsとGitLab CIの対応表）が入口です。
parallel deployments：Premium以上のブランチ別プレビュー
GitLab Pagesには、本番と別のパスにプレビューを並べて出すparallel deploymentsがあります。対象はPremiumとUltimateで、17.9で正式提供になりました。pages.path_prefixにブランチ名などを入れると、https://my-website-123456.gitlab.io/feature-xのようなURLで別の版が公開されます。
# main 以外のブランチへ push するたびにブランチ名のパスへプレビューを出す例（Premium 以上）
pages-preview:
script:
- npm ci
- npm run build
pages:
publish: dist
path_prefix: "$CI_COMMIT_BRANCH" # 例: /feature-x 配下に公開
expire_in: 1 week # 既定は 24 時間で自動削除
rules:
- if: $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCHプレビューは既定で24時間後に消え、expire_inで延ばせます。GitLab.comではプランごとに追加デプロイの数に枠があり、Premiumは100、Ultimateは500です。レビュー担当者が手元でビルドせずに確認できるため、ドキュメントサイトの修正をマージリクエストで回すチームでは効果が大きい機能です。
GitLab Pagesを採用する条件と見送る場面：既存のGit基盤と公開範囲で判断
採用してよい条件：GitLabでCIを回し社内限定の文書を公開したい場合
GitLab Pagesを選んでよいのは、次のどれかに当てはまるチームです。
- コードとCIがすでにGitLabにあり、設計書やAPI仕様書を同じパイプラインで更新したい
- 閲覧者をプロジェクトメンバーに絞りたいが、GitHub Enterprise Cloudは契約していない
- Self-Managedで社内ネットワークに閉じたドキュメントサイトを持ちたい
- 製品ごとに複数の独自ドメインを1つのサイトへ向けたい
2つ目の条件は判断を大きく左右します。社内限定の文書を外部の静的ホスティングに置く場合、Basic認証の代わりを別途用意する手間が増えますが、GitLab Pagesならプロジェクトの権限がそのまま閲覧権限になります。GitLabの基本操作から始める場合はGitLabの使い方（プロジェクト作成からIssue・MR・CI/CDまで）が手順の入口です。
見送るべき場面：GitHub中心のチームやサーバー処理が必要なサイト
リポジトリがGitHubにあるチームが、Pagesのためだけに GitLab へミラーを作るのは見送ります。同期の仕組みと権限管理が2重になるため、閲覧制限が要らない場合はGitHub Pagesだけで十分です。フォーム送信などサーバー側の処理を静的サイトと同じ場所で動かしたいなら、Workersと組み合わせられるCloudflare Pagesの公開手順と独自ドメイン設定のほうが合います。
もう1つの失敗パターンは、会社の公式サイトをrulesで絞らずに公開し、作業ブランチのpushで本番が書き換わる事故です。公開ジョブはデフォルトブランチ限定にし、そのブランチを保護ルールで守るところまでを最初に決めておきます。PagesをCI/CDの設計ごと整えたい、既存のビルドやレビューの流れに組み込みたいといった場合は、一創のDevOps・CI/CD導入支援で現状のパイプラインを確認したうえで構成を提案できます。
よくある質問
GitLab Pagesを使い始める前によく出る質問をまとめました。
GitLab Pagesは無料で使えますか？
使えます。GitLab PagesはFreeプランを含む全プランの機能で、GitLab.comではビルドに使う共有Runnerも既定で有効です。ただしRunnerの計算時間はプランごとの枠を消費するため、ビルドの重いサイトを頻繁に更新すると枠に届くことがあります。parallel deploymentsのようにPremium以上に限られる機能もあるので、プレビュー環境が要るかどうかで必要なプランが変わります。
GitLab Pagesを非公開にできますか？
できます。Pagesのアクセス制御を使い、閲覧範囲を「Only Project Members」にすると、プロジェクトのメンバーだけがログインして閲覧できる状態になります。Freeプランでも設定可能です。Self-Managedでは管理者がアクセス制御の機能を有効にしていないと選択肢が表示されないので、項目が見当たらない場合はインスタンスの管理者に確認します。
GitLab PagesでPHPやデータベースは動きますか？
動きません。公式ドキュメントは.phpや.aspなどサーバー側の動的処理を対象外としています。配信できるのはHTML・CSS・JavaScript・画像などの静的ファイルと、ブラウザで動くWasmです。データの保存や問い合わせの受付が必要なら、外部のAPIやフォームサービスを呼び出す構成にします。
publicフォルダ以外を公開できますか？
できます。ジョブのpagesキーの下にpublish: distのように書くと、そのフォルダが公開対象になります。この書き方はGitLab 17.9以降です。古いSelf-Managedでは指定が効かないため、ビルド後に出力をpublicへ移す処理をスクリプトに足してください。
GitLab Pagesの反映にはどれくらいかかりますか？
パイプラインの完了後、pages:deployジョブが終われば公開URLに反映されます。所要時間の大半を占めるのは自分で書いたビルドジョブで、その長さを左右するのは静的ジェネレーターの規模とRunnerの性能です。アクセス制御の設定変更は、キャッシュの更新を待つため反映まで通常1分ほどかかると公式ドキュメントに書かれています。
関連記事
- GitHub Pagesとは？料金・無料の範囲と容量制限、公開手順・商用利用・SEO設定【2026年】：GitHub側の料金と制限を詳しく確認できます
- GitHubとGitLabの違い｜ActionsとGitLab CIの対応表・料金・セルフホスト比較：Pagesを載せるサービスそのものを比べたいときに役立ちます
- GitLabとは：構成要素・CEとEEの違い・3つの提供形態とDockerで試す手順【2026年11月】：GitLab全体の構成と提供形態を押さえ直せます
- GitLab Runnerとは：executorの選び方と登録手順・config.tomlの設定例【2026年11月】：Pagesのビルドを自前のRunnerで動かすときの準備です
- MkDocsとは？使い方とMaterial for MkDocsの設定・日本語検索・GitHub Pages公開【2026年版】：ドキュメントサイトを作るジェネレーターの選択肢として参考になります
