GitLab Pages の設定

このドキュメントはGitLab Pagesが提供するオプションや設定を探るためのユーザーガイドです。

まず GitLab Pages に慣れるために：

GitLab Pagesの要件

簡単に言うと、GitLab Pagesでウェブサイトをアップロードするために必要なものは以下の通りです：

  1. インスタンスのドメイン：GitLab Pagesで使うドメイン名（管理者に聞いてください）。
  2. GitLab CI/CD:.gitlab-ci.yml ファイルで、リポジトリのルートディレクトリにpages という特定のジョブがあります。
  3. GitLab Runnerがプロジェクトで有効になっていること。

GitLab.comのGitLabページ

GitLab Pages on GitLab.comを使ってウェブサイトをホスティングしているのであれば：

  • GitLab Pages on GitLab.comのドメイン名はgitlab.io 。
  • カスタムドメインと TLS サポートは有効です。
  • 共有ランナーはデフォルトで有効になっており、無料で提供され、あなたのウェブサイトを構築するために使用することができます。お望みであれば、ご自身のランナーをお持ちいただくことも可能です。

プロジェクト例

GitLab Pages グループに、サンプルプロジェクトの完全なリストがあります。貢献者は大歓迎です。

カスタムエラーコードページ

public/ ディレクトリのルートに403.html と404.html ファイルを作成することで、独自の403 と404 エラーページを提供することができます。通常、これはプロジェクトのルート・ディレクトリですが、静的ジェネレーターの設定によって異なる場合があります。

404.html の場合、さまざまなシナリオがあります。例えば

  • プロジェクト Pages（/project-slug/ で提供）を使っていて、/project-slug/non/existing_file にアクセスしようとすると、GitLab Pages はまず/project-slug/404.html を提供しようとし、次に/404.html を提供しようとします。
  • ユーザーページやグループページ（/ で提供）を使っていて、/non/existing_file にアクセスしようとすると、GitLab Pages は/404.html を提供しようとします。
  • カスタムドメインを使っていて/non/existing_file にアクセスしようとすると、GitLab Pages は/404.html だけを提供しようとします。

GitLab Pages におけるリダイレクト

_redirects ファイルを使ってサイトのリダイレクトを設定することができます。詳しくは、Create redirects for GitLab Pagesをご覧ください。

ページの削除

ページを削除します：

  1. 左のサイドバーで「検索」または「移動」を選択してあなたのプロジェクトを検索します。
  2. 左サイドバーで、[デプロイ] > [Pages]を選択します。
  3. ページの削除]を選択します。

サブドメインのサブドメイン

GitLabインスタンスのトップレベルドメイン(*.example.io)の下でPagesを使用する場合、サブドメインのサブドメインでHTTPSを使用することはできません。ネームスペースやグループ名にドットが含まれている場合（例えばfoo.bar ）、ドメインhttps://foo.bar.example.io は機能しません。

この制限はHTTP Over TLS プロトコルによるものです。HTTPをHTTPSにリダイレクトしない限り、HTTPページは動作します。

プロジェクトやグループ内の GitLab ページ

GitLab Pagesウェブサイトをプロジェクトでホストする必要があります。このプロジェクトは非公開、内部、公開、グループや サブグループに属することができます。

グループウェブサイトの場合、グループはトップレベルでなければならず、サブグループであってはなりません。

プロジェクトウェブサイトの場合、まずプロジェクトを作成し、http(s)://namespace.example.io/project-path からアクセスできます。

独自ドメインの有効化

デフォルトでは、グループ内のすべてのプロジェクトは同じドメイン、例えばgroup.gitlab.ioを共有します。これは、グループ内のすべてのプロジェクトでクッキーも共有されることを意味します。

プロジェクトが固有の Pages ドメインを使用するようにするには、プロジェクトの固有ドメイン機能を有効にします：

  1. 左のサイドバーで「検索」または「移動」を選択してあなたのプロジェクトを検索します。
  2. 左サイドバーで、[デプロイ] > [Pages]を選択します。
  3. Use unique domainチェックボックスを選択します。
  4. 変更を保存を選択します。

Pagesの特定の設定オプション

GitLab CI/CDを特定のユースケースに設定する方法をご紹介します。

.gitlab-ci.yml プレーンな HTML ウェブサイトの場合

リポジトリに以下のファイルがあったとします：

├── index.html
├── css
│   └── main.css
└── js
    └── main.js

次に、.gitlab-ci.yml の例では、プロジェクトのルートディレクトリからpublic/ ディレクトリにすべてのファイルを移動します。.public の回避策は、cp がpublic/ を自分自身にコピーして無限ループにならないようにするためです：

pages:
  script:
    - mkdir .public
    - cp -r * .public
    - mv .public public
  artifacts:
    paths:
      - public
  only:
    - main

.gitlab-ci.yml 静的サイトジェネレーターの場合

ステップバイステップのガイドについては、このドキュメントを参照してください。

.gitlab-ci.yml コードを含むリポジトリに対して

GitLab Pages はデフォルトではブランチやタグに依存せず、デプロイは.gitlab-ci.yml で指定した内容のみに依存することを覚えておいてください。only パラメータ を指定すれば、新しいコミットがあなたのページ専用のブランチにプッシュされるたびに、pages のジョブを制限することができます。

そうすることで、プロジェクトのコードをmain ブランチに置き、静的ジェネレーターサイトをホストするためにオーファンブランチ (pages としましょう) を使用することができます。

このように、新しい空のブランチを作成します：

git checkout --orphan pages

この新しいブランチで最初に行われたコミットには親がなく、他のすべてのブランチやコミットから完全に切り離された新しい履歴のルートとなります。静的ジェネレータのソースファイルをpages ブランチにプッシュします。

以下は.gitlab-ci.yml のコピーです。最も重要な行は最後の行で、pages ブランチですべてを実行するように指定しています：

image: ruby:2.6

pages:
  script:
    - gem install jekyll
    - jekyll build -d public/
  artifacts:
    paths:
      - public
  only:
    - pages

main ブランチ 、Jekyllのソースファイルはpages ブランチ 、.gitlab-ci.ymlも含まれているの異なるファイルを持っている例を参照してください。

圧縮された資産を提供

最近のブラウザのほとんどは、圧縮されたフォーマットでのファイルのダウンロードをサポートしています。これにより、ファイルサイズが小さくなり、ダウンロードが高速化されます。

Pagesは、非圧縮ファイルを提供する前に、同じファイルが.br または.gz の拡張子で存在するかどうかをチェックします。存在し、ブラウザが圧縮ファイルの受信をサポートしている場合、非圧縮ファイルの代わりにそのバージョンを提供します。

この機能を利用するには、Pagesにアップロードするアーティファクトが次のような構造になっている必要があります：

public/
├─┬ index.html
│ | index.html.br
│ └ index.html.gz
│
├── css/
│   └─┬ main.css
│     | main.css.br
│     └ main.css.gz
│
└── js/
    └─┬ main.js
      | main.js.br
      └ main.js.gz

これは、.gitlab-ci.yml pagesジョブに次のようなscript: コマンドを含めることで実現できます：

pages:
  # Other directives
  script:
    # Build the public/ directory first
    - find public -type f -regex '.*\.\(htm\|html\|txt\|text\|js\|css\)$' -exec gzip -f -k {} \;
    - find public -type f -regex '.*\.\(htm\|html\|txt\|text\|js\|css\)$' -exec brotli -f -k {} \;

ファイルを事前に圧縮し、両方のバージョンをアーティファクトに含めることで、Pagesはファイルをオンデマンドで圧縮することなく、圧縮されたコンテンツと圧縮されていないコンテンツの両方のリクエストに対応することができます。

あいまいなURLの解決

GitLab Pages は、拡張子を含まない URL のリクエストを受け取ったとき、どのファイルを提供するかについて仮定します。

次のようなファイルでデプロイされた Pages サイトを考えてみましょう：

public/
├── index.html
├── data.html
├── info.html
├── data/
│   └── index.html
└── info/
    └── details.html

Pagesは、いくつかの異なるURLを通して、それぞれのファイルに到達することをサポートしています。特に、URL がディレクトリのみを指定する場合は、常にindex.html ファイルを探します。URL が存在しないファイルを参照していても、.html を URL に追加すると、存在するファイルにつながる場合、そのファイルが代わりに提供されます。上記のPagesサイトで何が起こるかの例をいくつか示します：

URLパスHTTPレスポンス
/ 200 OK:public/index.html
/index.html 200 OK:public/index.html
/index 200 OK:public/index.html
/data 302 Foundへのリダイレクト/data/
/data/ 200 OK:public/data/index.html
/data.html 200 OK:public/data.html
/info 302 Foundへのリダイレクト/info/
/info/ 404 Not Found エラーページ
/info.html 200 OK:public/info.html
/info/details 200 OK:public/info/details.html
/info/details.html 200 OK:public/info/details.html

public/data/index.html が存在する場合、/data と/data/ の両方の URL パスに対して、public/data.html ファイルよりも優先されます。

デフォルトフォルダーのカスタマイズ

デフォルトでは、サイトの静的ファイルを含むアーティファクトフォルダには public という名前が必要です。

このフォルダ名を他の値に変更するには、.gitlab-ci.yml のpages ジョブ設定にpublish プロパティを追加します。

以下の例では、代わりにdist という名前のフォルダを発行します：

pages:
  script:
    - npm run build
  artifacts:
    paths:
      - dist
  publish: dist

public以外のフォルダ名を使う場合は、Pages と一緒にデプロイするディレクトリをアーティファクトとpublish プロパティの両方で指定する必要があります。両方が必要な理由は、アーティファクトとして複数のパスを定義することができ、GitLab はどれをデプロイしたいのかわからないからです。

既知のイシュー

既知のイシューのリストについては、GitLab公開イシュー・トラッカーをご覧ください。

トラブルシューティング

GitLab Pages サイトの URL にアクセスすると 404 エラーが発生します。

この問題は、公開ディレクトリindex.html にファイルが index.htmlないことが原因である可能性が高いです。index.html Pagesサイトをデプロイした後に404が表示された場合は、公開ディレクトリにファイルが含まれていることを確認して index.htmlください。ファイルがtest.html のような別の名前を含んでいる場合でも、Pagesサイトにアクセスすることはできますが、フルパスが必要です。例:https//group-name.pages.example.com/project-slug/test.html.

公開ディレクトリの内容は、最新のパイプラインのアーティファクトを閲覧することで確認できます。

公開ディレクトリにリストされている Pages は、プロジェクトの Pages URL からアクセスできます。

404は不正な権限に関連している可能性もあります。Pages Access Controlが有効で、ユーザーがPages URLに移動して404応答を受け取った場合、ユーザーがサイトを表示する権限を持っていない可能性があります。これを解決するには、ユーザーがプロジェクトのメンバーであることを確認してください。

Safariでメディアコンテンツを再生できません

Safariでメディアコンテンツを再生するには、ウェブサーバーがRangeリクエストヘッダをサポートしている必要があります。GitLab PagesがHTTP Rangeリクエストを提供するためには、.gitlab-ci.yml ファイルで以下の2つの変数を使用する必要があります：

pages:
  stage: deploy
  variables:
    FF_USE_FASTZIP: "true"
    ARTIFACT_COMPRESSION_LEVEL: "fastest"
  script:
    - echo "Deploying pages"
  artifacts:
    paths:
      - public
  environment: production

FF_USE_FASTZIP 変数はARTIFACT_COMPRESSION_LEVELに必要な機能フラグを有効にします。