GitLab Pages のリダイレクト

GitLab Pagesでは、NetlifyスタイルのHTTPリダイレクトを使って、あるURLを別のURLに転送するルールを設定することができます。

Netlifyが提供するすべての特別なオプションがサポートされているわけではありません。

機能対応物件例
リダイレクト (301,302) {チェックサークル｝はい/wardrobe.html /narnia.html 302
書き換え (200) {チェックサークル｝はい/* / 200
スプラッツ {チェックサークル｝はい/news/* /blog/:splat
プレースホルダ {チェックサークル｝はい/news/:year/:month/:date /blog-:year-:month-:date.html
書き換え（200 以外） {点線円｝いいえ/en/* /en/404.html 404
クエリパラメータ {点線円｝いいえ/store id=:id /blog/:id 301
フォース（シャドーイング） {点線円｝いいえ/app/ /app/index.html 200!
ドメインレベルリダイレクト {点線円｝いいえhttp://blog.example.com/* https://www.example.com/blog/:splat 301
国または言語によるリダイレクト {点線円｝いいえ/ /anz 302 Country=au,nz
ロールによるリダイレクト {点線円｝いいえ/admin/* 200! Role=admin
note
マッチングの振る舞いのテストケースは、GitLab がどのようにルールマッチングを実装しているのかを詳しく理解するための良いリソースです。このテストスイートに含まれていないエッジケースについては、コミュニティからの貢献を歓迎します！

リダイレクトの作成

リダイレクトを作成するには、GitLab Pages サイトのpublic/ ディレクトリに_redirects という設定ファイルを作成します。

  • すべてのパスはフォワードスラッシュ/ で始まる必要があります。
  • ステータスコードが指定されない場合、デフォルトのステータスコード301 が適用されます。
  • _redirects ファイルには、インスタンス・レベルで設定された、ファイル・サイズの制限とプロジェクトごとのルールの最大数があります。設定された最大数内で最初に一致するルールのみが処理されます。デフォルトのファイル・サイズ制限は 64 KB、デフォルトの最大ルール数は 1,000 です。

  • GitLab Pages サイトがデフォルトのドメイン名（namespace.gitlab.io/project-slug など）を使用している場合は、すべてのルールの前にパスを付ける必要があります：

     /project-slug/wardrobe.html /project-slug/narnia.html 302

  • GitLab Pages サイトがカスタムドメインを使っている場合は、プロジェクトパスのプレフィックスは必要ありません。例えば、カスタムドメインがexample.com の場合、_redirects ファイルは次のようになります：

     /wardrobe.html /narnia.html 302

リダイレクトを上書きするファイル

ファイルはリダイレクトよりも優先されます。ファイルがディスク上に存在する場合、GitLab Pages はリダイレクトの代わりにそのファイルを提供します。例えば、hello.html とworld.html というファイルが存在し、_redirects ファイルに次の行がある場合、hello.html が存在するのでリダイレクトは無視されます：

/project-slug/hello.html /project-slug/world.html 302

GitLab はこの動作を変更する Netlifyforce オプションをサポートしていません。

HTTPステータスコード

ステータスコードが指定されない場合、デフォルトのステータスコード301 が適用されますが、明示的に指定することもできます。以下のHTTPコードがサポートされています：

  • 301: 恒久的なリダイレクト。
  • 302:一時的なリダイレクト。
  • 200: HTTPリクエストが成功した場合の標準レスポンス。Pages はアドレスバーの URL を変更することなく、to ルールのコンテンツが存在する場合、そのコンテンツを提供します。

リダイレクト

リダイレクトを作成するには、from パス、to パス、HTTP ステータスコードを含むルールを追加します：

# 301 permanent redirect
/old/file.html /new/file.html 301

# 302 temporary redirect
/old/another_file.html /new/another_file.html 302

リライト

リクエストがfrom にマッチした場合、to パスのコンテンツを提供するためにステータスコード200 を提供します：

/old/file.html /new/file.html 200

このステータスコードは、動的に URL を書き換えるためにsplat のルールと組み合わせて使うことができます。

スプラット

GitLab 14.3で導入されました。

from パスにアスタリスク (*) を含むルールは、スプラットとして知られ、要求されたパスの開始、中間、終了のいずれかにマッチします。この例では、/old/ 以降にマッチし、/new/file.html に書き換えます：

/old/* /new/file.html 200

スプラットプレースホルダ

ルールのfrom パスの* でマッチしたコンテンツは、:splat プレースホルダを使用してto パスに注入できます：

/old/* /new/:splat 200

この例では、/old/file.html へのリクエストは200 のステータスコードで/new/file.html のコンテンツを提供します。

ルールのfrom パスが複数のスプラットを含んでいる場合、 最初のスプラットにマッチした値がto パスの:splatを置き換えます。

スプラットマッチングの動作

スプラットは「貪欲」で、できるだけ多くの文字とマッチします：

/old/*/file /new/:splat/file 301

この例では、ルールは/old/a/b/c/file を/new/a/b/c/file にリダイレクトします。

スプラットは空文字列にもマッチするので、前のルールは/old/file を/new/file にリダイレクトします。

すべてのリクエストをルートindex.html

note
GitLab PagesとLet’s Encryptのインテグレーションを使っている場合は、このルールを追加する前に有効にする必要があります。さもなければ、リダイレクトはLet’s Encryptインテグレーションを壊してしまいます。詳しくはGitLab Pages イシュー649をご覧ください。

シングルページアプリケーション（SPA）は、クライアントサイドルートを使って独自のルーティングを行うことがよくあります。このようなアプリケーションでは、_すべての_リクエストをルートindex.html に書き換えて、JavaScript アプリケーションでルーティングロジックを処理できるようにすることが重要です。これは_redirects のようなルールで実現できます：

/* /index.html 200

プレースホルダ

GitLab 14.3で導入されました。

リクエストされた URL の一部にマッチするプレースホルダをルールで使用し、新しい URL に書き換えたりリダイレクトしたりする際にこれらのマッチを使用します。

プレースホルダは、: 文字の後に文字列 ([a-zA-Z]+) が続く形式で、from とto の両方のパスに使用されます：

/news/:year/:month/:date/:slug /blog/:year-:month-:date-:slug 200

このルールは、/news/2021/08/12/file.html に対するリクエストに対して、/blog/2021-08-12-file.html のコンテンツを200 で提供するように Pages に指示します。

プレースホルダーのマッチング動作

プレースホルダはスプラットと比較して、マッチするコンテンツに制限があります。プレースホルダはスラッシュ (/) の間のテキストにマッチするので、 パスセグメントひとつにマッチさせるためにプレースホルダを使います。

さらに、プレースホルダは空の文字列にはマッチしません。次のようなルールは/old/file のようなリクエストURLにはマッチしません：

/old/:path /new/:path

リダイレクトルールのデバッグ

リダイレクトが期待通りに動作しない場合や、リダイレクトの構文をチェックしたい場合は、[your pages url]/_redirects にアクセスしてください。_redirects ファイルは直接提供されませんが、ブラウザにはリダイレクトルールの番号付きリストと、ルールが有効か無効かが表示されます：

11 rules
rule 1: valid
rule 2: valid
rule 3: error: splats are not supported
rule 4: valid
rule 5: error: placeholders are not supported
rule 6: valid
rule 7: error: no domain-level redirects to outside sites
rule 8: error: url path must start with forward slash /
rule 9: error: no domain-level redirects to outside sites
rule 10: valid
rule 11: valid

Netlify の実装との違い

サポートされている_redirects ルールのほとんどは GitLab でも Netlify でも同じように動作します。しかし、いくつかの細かな違いがあります：

  • すべてのルールのURLはスラッシュで始まる必要があります：

    Netlify では URL がスラッシュで始まる必要はありません：

     # Valid in Netlify, invalid in GitLab
 */path /new/path 200

    GitLab はすべての URL がスラッシュで始まることを検証します。先ほどの例と同じです：

     # Valid in both Netlify and GitLab
 /old/path /new/path 200

  • 全てのプレースホルダーの値が入力されます：

    Netlify はto パスに現れるプレースホルダーの値だけを入力します：

     /old /new/:placeholder

    /old へのリクエストがあるとします：

    • Netlify は/new/:placeholder にリダイレクトします(リテラルは:placeholder)。
    • GitLab は/new/ にリダイレクトします。