GitLab Pagesの設定

GitLab Pagesには、静的サイトのデプロイと表示をカスタマイズするための設定オプションがあります。Pagesの設定では、次のことができます:

• 403応答と404応答にカスタムエラーページを提供する。
• _redirectsファイルを介してURLリダイレクトを設定する。
• CI/CDルールを使用して、任意のブランチからPagesをデプロイする。
• 事前に圧縮されたアセットを提供してページの読み込みを速くする。
• サイトの公開元となるフォルダーをカスタマイズする。
• サイトの一意のドメインを生成および管理する。

このドキュメントでは、GitLab Pagesサイトで利用可能な設定と設定オプションについて説明します。Pagesの概要については、GitLab Pagesを参照してください。

GitLab Pagesの要件

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

1. インスタンスのドメイン: GitLab Pagesに使用されるドメイン名（管理者に確認してください）。
2. GitLab CI/CD: リポジトリのルートディレクトリにある、pagesという名前の特定のジョブを含む.gitlab-ci.ymlファイル。
3. プロジェクトに対してGitLab Runnerが有効になっている。

GitLab.comのGitLab Pages

ウェブサイトのホスティングにGitLab.comのGitLab Pagesを使用している場合は、次のようになります:

• GitLab.comのGitLab Pagesのドメイン名は、gitlab.ioです。
• カスタムドメインとTLSのサポートが有効になっています。
• インスタンスRunnerはデフォルトで有効になっており、無料で提供され、ウェブサイトのビルドに使用できます。必要に応じて、Runnerを自分で持ち込むこともできます。

プロジェクトの例

プロジェクトの例の完全なリストについては、GitLab Pagesグループを参照してください。コントリビュートを歓迎します。

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

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

404.htmlの場合、複数のシナリオがあります。次に例を示します:

• プロジェクトのPages（/project-slug/で提供）を使用していて、/project-slug/non/existing_fileにアクセスしようとした場合、GitLab Pagesは最初に/project-slug/404.html、次に/404.htmlを表示しようとします。
• ユーザーまたはグループのPages（/で提供）を使用していて、/non/existing_fileにアクセスしようとした場合、GitLab Pagesは/404.htmlを表示しようとします。
• カスタムドメインを使用していて、/non/existing_fileにアクセスしようとした場合、GitLab Pagesは/404.htmlのみを表示しようとします。

GitLab Pagesでのリダイレクト

_redirectsファイルを使用して、サイトのリダイレクトを設定できます。詳細については、GitLab Pagesのリダイレクトの作成方法を参照してください。

Pagesサイトを削除する

プロジェクトのすべてのPagesデプロイを完全に削除します。これは永続的なもので、元に戻すことはできません。

Pagesを削除するには、次の手順に従います:

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。
2. デプロイ > Pagesを選択します。
3. Delete pages（Pagesを削除）を選択します。

Pagesサイトはデプロイされなくなりました。このPagesサイトを再度デプロイするには、新しいパイプラインを実行します。

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

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

この制限は、HTTP Over TLSプロトコルが原因です。HTTPをHTTPSにリダイレクトしない限り、HTTPページは機能します。

プロジェクトとグループのGitLab Pages

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

グループのウェブサイトの場合、グループはトップレベルに配置する必要があり、サブグループは使用できません。

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

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

特定のユースケースに合わせてGitLab CI/CDをセットアップする方法を説明します。

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

リポジトリに次のファイルが含まれているとします:

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

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

create-pages:
  script:
    - mkdir .public
    - cp -r * .public
    - mv .public public
  pages: true  # specifies that this is a Pages job and publishes the default public directory
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

以前のYAMLの例では、ユーザー定義のジョブ名を使用しています。

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

手順ガイドについては、こちらのドキュメントを参照してください。

コードを含むリポジトリの.gitlab-ci.yml

GitLab Pagesはデフォルトではブランチ/タグに依存せず、そのデプロイは.gitlab-ci.ymlで指定した内容のみに依存することに注意してください。新しいコミットがページ専用のブランチにプッシュされるたびに、rules:ifを使用してpagesジョブを制限できます。

そうすることで、プロジェクトのコードをmainブランチに保持し、孤立したブランチ（pagesという名前にします）を使用して静的サイトジェネレーターサイトをホスティングできます。

次のようにして、新しい空のブランチを作成できます:

git checkout --orphan pages

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

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

create-pages:
  image: ruby:2.6
  script:
    - gem install jekyll
    - jekyll build -d public/
  pages: true  # specifies that this is a Pages job and publishes the default public directory
  rules:
    - if: '$CI_COMMIT_REF_NAME == "pages"'

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

以前のYAMLの例では、ユーザー定義のジョブ名を使用しています。

圧縮されたアセットの提供

最新のほとんどのブラウザーは、圧縮形式でのファイルのダウンロードをサポートしています。これにより、ファイルサイズが削減され、ダウンロードのスピードが速くなります。

圧縮されていないファイルを提供する前に、Pagesは同じファイルが.br拡張子または.gz拡張子で存在するかどうかを確認します。存在し、ブラウザーが圧縮ファイルの受信をサポートしている場合、Pagesは圧縮されていないバージョンではなく、そのバージョンを提供します。

この機能を活用するには、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.ymlPagesジョブに次のようなscript:コマンドを含めます:

create-pages:
  # Other directives
  script:
    # Build the public/ directory first
    - find public -type f -regex '.*\.\(htm\|html\|xml\|txt\|text\|js\|css\|svg\)$' -exec gzip -f -k {} \;
    - find public -type f -regex '.*\.\(htm\|html\|xml\|txt\|text\|js\|css\|svg\)$' -exec brotli -f -k {} \;
  pages: true  # specifies that this is a Pages job

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

以前のYAMLの例では、ユーザー定義のジョブ名を使用しています。

あいまいなURLの解決

GitLab Pagesは、拡張子を含まないURLのリクエストを受信した場合に、提供するファイルを仮定します。

Pagesサイトが次のファイルでデプロイされているとします:

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

Pagesは、いくつかの異なるURLを介してこれらの各ファイルに到達することをサポートしています。特に、URLがディレクトリのみを指定する場合、常にindex.htmlファイルを探します。URLが、存在しないファイルを参照しているが、URLに.htmlを追加すると存在するファイルになる場合は、代わりにそのファイルが提供されます。以下に、前のPagesサイトの場合に行われる動作の例を示します:

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

デフォルトフォルダーをカスタマイズする

デフォルトでは、Pagesはビルドファイルでpublicという名前のフォルダーを探して公開します。

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

次の例では、代わりにdistという名前のフォルダーを公開します:

create-pages:
  script:
    - npm run build
  pages:  # specifies that this is a Pages job
    publish: dist

以前のYAMLの例では、ユーザー定義のジョブ名を使用しています。

pages.publishフィールドで変数を使用する方法については、pages.publishを参照してください。

Pagesはアーティファクトを使用してサイトのファイルを保存するため、pages.publishの値はartifacts:pathsに自動的に付け加えられます。前の例は、以下と同等です:

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

GitLab Pagesの一意のドメインを再生成する

GitLab Pagesサイトの専任のドメインを再生成できます。

ドメインが再生成されると、以前のURLはアクティブではなくなります。古いURLにアクセスしようとすると、404エラーが表示されます。

前提要件

• プロジェクトのメンテナーロール以上を持っている必要があります。
• プロジェクトのPages設定で、一意のドメインを使用の設定を有効にする必要があります。

GitLab Pagesサイトの専任のドメインを再生成するには:

1. 左側のサイドバーで、デプロイ > Pagesを選択します。
2. ページへアクセスの横にある一意のドメインを再生成を押します。
3. GitLabは、Pagesサイトの新しい一意のドメインを生成します。

既知の問題

既知の問題のリストについては、GitLabの公開イシュートラッカーを参照してください。

トラブルシューティング

GitLab PagesサイトのURLにアクセスするときの404エラー

この問題は、ほとんどの場合、公開ディレクトリにindex.htmlファイルがないことが原因で発生します。Pagesサイトをデプロイした後に404エラーが発生した場合は、公開ディレクトリにindex.htmlファイルが含まれていることを確認します。ファイルにtest.htmlなどの異なる名前が含まれている場合でも、Pagesサイトにアクセスできますが、フルパスが必要になります。たとえば、https//group-name.pages.example.com/project-slug/test.htmlのようになります。

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

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

404は、権限が正しくないことにも関連している可能性があります。Pagesアクセス制御が有効になっていて、ユーザーがPages URLにアクセスして404応答を受け取った場合、サイトを表示する権限がユーザーにない可能性があります。これを修正するには、ユーザーがプロジェクトのメンバーであることを確認します。

壊れた相対リンク

GitLab Pagesは、拡張子のないURLをサポートしています。ただし、イシュー#354で説明されている問題により、拡張子のないURLがフォワードスラッシュ（/）で終わる場合、ページの相対リンクが壊れます。

この問題を解決するには:

• Pagesサイトを指すURLに拡張子が含まれているか、または末尾のスラッシュが含まれていないことを確認します。
• 可能であれば、サイトで絶対URLのみを使用してください。

Safariでメディアコンテンツを再生できない

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

create-pages:
  stage: deploy
  variables:
    FF_USE_FASTZIP: "true"
    ARTIFACT_COMPRESSION_LEVEL: "fastest"
  script:
    - echo "Deploying pages"
  pages: true  # specifies that this is a Pages job and publishes the default public directory
  environment: production

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

以前のYAMLの例では、ユーザー定義のジョブ名を使用しています。

複数のブラウザータブでプライベートGitLab Pagesサイトにアクセスしたときの401エラー

事前の認証なしに、2つの異なるタブ形式でプライベートPages URLに同時にアクセスしようとすると、各タブ形式に対して2つの異なるstate値が返されます。ただし、Pagesセッションでは、特定のクライアントに対して最新のstate値のみが保存されます。このため、認証情報を送信した後、いずれかのタブで401 Unauthorizedエラーが返されます。

401エラーを解決するには、ページを更新してください。

pages:deployジョブの失敗

GitLab Pagesでデプロイするには、ルートコンテンツディレクトリに空でないindex.htmlファイルが含まれている必要があります。そうでない場合、pages:deployジョブは失敗します。

コンテンツディレクトリは、デフォルトでpublic/であるか、pages.publishファイルで.gitlab-ci.ymlキーワードで指定されたディレクトリです。