GitLab Pagesの並列デプロイ

プラン: Premium、Ultimate
提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

GitLab 16.7で、pages_multiple_versions_settingというフラグを伴う実験として導入されました。デフォルトでは無効になっています。
GitLab 17.4で、名称が「multiple deployments」から「parallel deployments」（並列デプロイ）に変更されました。
GitLab 17.4のGitLab.com、GitLab Self-Managed、GitLab Dedicatedで有効になりました。
GitLab 17.7で、プロジェクト設定を削除するように変更されました。
GitLab 17.8で、path_prefixでピリオドが使用できるように変更されました。
GitLab 17.9で、publishプロパティに渡す際に変数を利用できるように変更されました。
GitLab 17.9で一般提供になりました。機能フラグpages_multiple_versions_settingは削除されました。
GitLab 17.10で、Pagesジョブのみを対象に、artifacts:pathsへのpages.publishパスの自動付加が導入されました。

並列デプロイを使用すると、複数のバージョンのGitLab Pagesサイトを同時に公開できます。各バージョンには、指定したプレフィックスパスに基づく独自のURLがあります。

並列デプロイは、以下のような場合に使用します:

本番環境にマージする前に、開発ブランチでの変更をテストするためのワークフローを強化します。
関係者と作業プレビューを共有してフィードバックを得ます。
複数のソフトウェアバージョンのドキュメントを同時に管理します。
異なる対象者向けにローカライズされたコンテンツを公開します。
最終公開前に、レビュー用のステージング環境を作成します。

サイトの各バージョンには、指定したプレフィックスパスに基づく独自のURLがあります。これらの並列デプロイの存在期間を制御します。デフォルトでは24時間後に有効期限が切れますが、この期間をレビュータイムラインに合わせてカスタマイズできます。

並列デプロイの作成

前提要件:

ルートレベルのネームスペースには、利用可能な並列デプロイスロットが必要です。

並列デプロイを作成するには:

.gitlab-ci.ymlファイルで、path_prefixを使用してPagesジョブを追加します:
```
pages:
  stage: deploy
  script:
    - echo "Pages accessible through ${CI_PAGES_URL}"
  pages:  # specifies that this is a Pages job and publishes the default public directory
    path_prefix: "$CI_COMMIT_BRANCH"
```
path_prefixの値:
- 小文字に変換されます。
- 数字（0-9）、文字（a-z）、およびピリオド（.）を含めることができます。
- 他の文字はすべてハイフン（-）に置き換えられます。
- ハイフン（-）またはピリオド（.）で開始または終了することはできません。そのため、削除されます。
- 63バイト以下にする必要があります。これより長いものは切り捨てられます。
オプション。動的なプレフィックスが必要な場合は、path_prefixでCI/CD変数を使用します。例:
```
pages:
  path_prefix: "mr-$CI_MERGE_REQUEST_IID" # Results in paths like mr-123
```
オプション。デプロイの有効期限を設定するには、expire_inを追加します:
```
pages:
  pages:
    path_prefix: "$CI_COMMIT_BRANCH"
    expire_in: 1 week
```
デフォルトでは、並列デプロイは24時間後に有効期限が切れます。
変更をコミットして、リポジトリにプッシュします。

デプロイには以下からアクセスできます:

固有のドメインを使用する場合：https://project-123456.gitlab.io/your-prefix-name。
固有のドメインを使用しない場合：https://namespace.gitlab.io/project/your-prefix-name。

サイトドメインとパブリックディレクトリの間のURLパスは、path_prefixによって決定されます。たとえば、メインデプロイのコンテンツが/index.htmlにある場合、プレフィックスstagingを持つ並列デプロイは、/staging/index.htmlで同じコンテンツにアクセスできます。

パスの衝突を防ぐため、サイト内の既存のフォルダーの名前と一致するパスプレフィックスを使用しないでください。詳細については、Path clashを参照してください。

設定例

https://gitlab.example.com/namespace/projectのようなプロジェクトを検討してください。デフォルトでは、そのメインのPagesデプロイには以下からアクセスできます:

固有のドメインを使用する場合：https://project-123456.gitlab.io/。
固有のドメインを使用しない場合：https://namespace.gitlab.io/project。

pages.path_prefixがプロジェクトのブランチ名（path_prefix = $CI_COMMIT_BRANCHなど）に設定されており、username/testing_featureという名前のブランチがある場合、この並列のPagesデプロイには以下からアクセスできます:

固有のドメインを使用する場合：https://project-123456.gitlab.io/username-testing-feature。
固有のドメインを使用しない場合：https://namespace.gitlab.io/project/username-testing-feature。

制限

並列デプロイの数は、ルートレベルのネームスペースによって制限されます。具体的な制限については、以下を参照してください:

GitLab.com, その他の制限を参照してください。
GitLab Self-Managed、並列Pagesデプロイの数を参照してください。

ネームスペース内のアクティブなデプロイの数をすぐに減らすには、一部のデプロイを削除します。詳細については、デプロイの削除を参照してください。

古いデプロイを自動的に削除するように有効期限を設定するには、期限切れのデプロイを参照してください。

有効期限

デフォルトでは、並列デプロイは24時間後に有効期限が切れ、その後削除されます。セルフホストインスタンスを使用している場合、インスタンス管理者は別のデフォルト期間を設定できます。

有効期限をカスタマイズするには、pages.expire_in設定を行います。

デプロイが自動的に有効期限切れにならないようにするには、pages.expire_inをneverに設定します。

パスの衝突

pages.path_prefixは、サイト内の既存のパスと競合する可能性のあるPagesデプロイを作成できるCI/CD変数から動的な値を取得できます。たとえば、次のパスを持つ既存のGitLab Pagesサイトがあるとします:

/index.html
/documents/index.html

pages.path_prefixがdocumentsの場合、そのバージョンは既存のパスをオーバーライドします。言い換えれば、https://namespace.gitlab.io/project/documents/index.htmlは、サイトのdocumentsデプロイの/index.htmlを指し、サイトのmainデプロイのdocuments/index.htmlではありません。

CI/CD変数を他の文字列と組み合わせると、パスの衝突の可能性を減らすことができます。例:

create-pages:
  stage: deploy
  script:
    - echo "Pages accessible through ${CI_PAGES_URL}"
  variables:
    PAGES_PREFIX: "" # No prefix by default (main)
  pages:  # specifies that this is a Pages job and publishes the default public directory
    path_prefix: "$PAGES_PREFIX"
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # Run on default branch (with default PAGES_PREFIX)
    - if: $CI_COMMIT_BRANCH == "staging" # Run on main (with default PAGES_PREFIX)
      variables:
        PAGES_PREFIX: '_stg' # Prefix with _stg for the staging branch
    - if: $CI_PIPELINE_SOURCE == "merge_request_event" # Conditionally change the prefix for Merge Requests
      when: manual # Run pages manually on Merge Requests
      variables:
        PAGES_PREFIX: 'mr-$CI_MERGE_REQUEST_IID' # Prefix with the mr-<iid>, like `mr-123`

動的なプレフィックスの文字列と変数を組み合わせたその他の例を次に示します:

pages.path_prefix: 'mr-$CI_COMMIT_REF_SLUG': mr-が付いたブランチまたはタグ付け名（mr-branch-nameなど）。
pages.path_prefix: '_${CI_MERGE_REQUEST_IID}_': _でプレフィックスが付けられたマージリクエスト番号（_123_など）。

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

並列デプロイを使用してPages環境を作成する

並列GitLab Pagesデプロイを使用して、新しい環境を作成できます。例:

create-pages:
  stage: deploy
  script:
    - echo "Pages accessible through ${CI_PAGES_URL}"
  variables:
    PAGES_PREFIX: "" # no prefix by default (run on the default branch)
  pages:  # specifies that this is a Pages job and publishes the default public directory
    path_prefix: "$PAGES_PREFIX"
  environment:
    name: "Pages ${PAGES_PREFIX}"
    url: $CI_PAGES_URL
  rules:
    - if: $CI_COMMIT_BRANCH == "staging" # ensure to run on the default branch (with default PAGES_PREFIX)
      variables:
        PAGES_PREFIX: '_stg' # prefix with _stg for the staging branch
    - if: $CI_PIPELINE_SOURCE == "merge_request_event" # conditionally change the prefix on Merge Requests
      when: manual # run pages manually on Merge Requests
      variables:
        PAGES_PREFIX: 'mr-$CI_MERGE_REQUEST_IID' # prefix with the mr-<iid>, like `mr-123`

この設定を使用すると、ユーザーはUIを介して各GitLab Pagesデプロイにアクセスできるようになります。ページに環境を使用する場合、すべてのページ環境はプロジェクト環境リストにリストされます。

同様の環境をグループ化することもできます。

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

自動クリーン

path_prefixを使用してマージリクエストによって作成された並列Pagesデプロイは、マージリクエストが閉じられるか、マージされると自動的に削除されます。

リダイレクトでの使用法

リダイレクトは絶対パスを使用します。並列デプロイはサブパスで使用できるため、リダイレクトでは、並列デプロイで機能するように_redirectsファイルに追加の変更が必要です。

既存のファイルは常にリダイレクト規則よりも優先されるため、プレフィックスが付いたパスへのリクエストをキャッチするためにSplatのプレースホルダーを使用できます。

path_prefixが/mr-${$CI_MERGE_REQUEST_IID}の場合、この_redirectファイルの例を適用して、プライマリデプロイと並列デプロイの両方のリクエストをリダイレクトします:

# Redirect the primary deployment
/will-redirect.html /redirected.html 302

# Redirect parallel deployments
/*/will-redirect.html /:splat/redirected.html 302