diff options
Diffstat (limited to 'doc/user/project/pages/redirects.md')
| -rw-r--r-- | doc/user/project/pages/redirects.md | 264 |
1 files changed, 226 insertions, 38 deletions
diff --git a/doc/user/project/pages/redirects.md b/doc/user/project/pages/redirects.md index 8ed6f214605..3deea92f56e 100644 --- a/doc/user/project/pages/redirects.md +++ b/doc/user/project/pages/redirects.md @@ -9,62 +9,58 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/24) in GitLab Pages 1.25.0 and GitLab 13.4 behind a feature flag, disabled by default. > - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/367) in GitLab 13.5. -WARNING: -This feature might not be available to you. Check the **version history** note above for details. - In GitLab Pages, you can configure rules to forward one URL to another using [Netlify style](https://docs.netlify.com/routing/redirects/#syntax-for-the-redirects-file) HTTP redirects. -## Supported features - -GitLab Pages only supports the -[`_redirects` plain text file syntax](https://docs.netlify.com/routing/redirects/#syntax-for-the-redirects-file), -and `.toml` files are not supported. - -Redirects are only supported at a basic level. GitLab Pages doesn't support all -[special options offered by Netlify](https://docs.netlify.com/routing/redirects/redirect-options/). - -Note that supported paths must start with a forward slash `/`. +Not all +[special options offered by Netlify](https://docs.netlify.com/routing/redirects/redirect-options/) +are supported. | Feature | Supported | Example | | ------- | --------- | ------- | -| Redirects (`301`, `302`) | **{check-circle}** Yes | `/wardrobe.html /narnia.html 302` -| Rewrites (other status codes) | **{dotted-circle}** No | `/en/* /en/404.html 404` | -| [Splats](https://docs.netlify.com/routing/redirects/redirect-options/#splats) | **{dotted-circle}** No | `/news/* /blog/:splat` | -| Placeholders | **{dotted-circle}** No | `/news/:year/:month/:date/:slug /blog/:year/:month/:date/:slug` | +| [Redirects (`301`, `302`)](#redirects) | **{check-circle}** Yes | `/wardrobe.html /narnia.html 302` +| [Rewrites (`200`)](#rewrites) | **{check-circle}** Yes | `/* / 200` | +| [Splats](#splats) | **{check-circle}** Yes | `/news/* /blog/:splat` | +| [Placeholders](#placeholders) | **{check-circle}** Yes | `/news/:year/:month/:date /blog-:year-:month-:date.html` | +| Rewrites (other than `200`) | **{dotted-circle}** No | `/en/* /en/404.html 404` | | Query parameters | **{dotted-circle}** No | `/store id=:id /blog/:id 301` | | Force ([shadowing](https://docs.netlify.com/routing/redirects/rewrites-proxies/#shadowing)) | **{dotted-circle}** No | `/app/ /app/index.html 200!` | | Domain-level redirects | **{dotted-circle}** No | `http://blog.example.com/* https://www.example.com/blog/:splat 301` | | Redirect by country or language | **{dotted-circle}** No | `/ /anz 302 Country=au,nz` | | Redirect by role | **{dotted-circle}** No | `/admin/* 200! Role=admin` | +NOTE: +The [matching behavior test cases](https://gitlab.com/gitlab-org/gitlab-pages/-/blob/master/internal/redirects/matching_test.go) +are a good resource for understanding how GitLab implements rule matching in +detail. Community contributions are welcome for any edge cases that aren't included in +this test suite! + ## Create redirects -To create redirects, -create a configuration file named `_redirects` in the `public/` directory of your -GitLab Pages site. +To create redirects, create a configuration file named `_redirects` in the +`public/` directory of your GitLab Pages site. -If your GitLab Pages site uses the default domain name (such as -`namespace.gitlab.io/projectname`) you must prefix every rule with the project name: +Note that: -```plaintext -/projectname/redirect-portal.html /projectname/magic-land.html 301 -/projectname/cake-portal.html /projectname/still-alive.html 302 -/projectname/wardrobe.html /projectname/narnia.html 302 -/projectname/pit.html /projectname/spikes.html 302 -``` +- All paths must start with a forward slash `/`. +- A default status code of `301` is applied if no [status code](#http-status-codes) is provided. +- The `_redirects` file has a file size limit of 64KB and a maximum of 1,000 rules per project. + Only the first 1,000 rules are processed. +- If your GitLab Pages site uses the default domain name (such as + `namespace.gitlab.io/projectname`) you must prefix every rule with the project name: -If your GitLab Pages site uses [custom domains](custom_domains_ssl_tls_certification/index.md), -no project name prefix is needed. For example, if your custom domain is `example.com`, -your `_redirect` file would look like: + ```plaintext + /projectname/wardrobe.html /projectname/narnia.html 302 + ``` -```plaintext -/redirect-portal.html /magic-land.html 301 -/cake-portal.html /still-alive.html 302 -/wardrobe.html /narnia.html 302 -/pit.html /spikes.html 302 -``` +- If your GitLab Pages site uses [custom domains](custom_domains_ssl_tls_certification/index.md), + no project name prefix is needed. For example, if your custom domain is `example.com`, + your `_redirects` file would look like: + + ```plaintext + /wardrobe.html /narnia.html 302 + ``` ## Files override redirects @@ -81,6 +77,132 @@ GitLab doesn't support Netlify's [force option](https://docs.netlify.com/routing/redirects/rewrites-proxies/#shadowing) to change this behavior. +## HTTP status codes + +A default status code of `301` is applied if no status code is provided, but +you can explicitly set your own. The following HTTP codes are supported: + +- **301**: Permanent redirect. +- **302**: Temporary redirect. +- **200**: Standard response for successful HTTP requests. Pages + serves the content in the `to` rule if it exists, without changing the URL in + the address bar. + +## Redirects + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/458) in GitLab 14.3. +> - Enabled on GitLab.com. +> - Enabled by default in self-managed GitLab behind the [`FF_ENABLE_REDIRECTS` feature flag](#feature-flag-for-redirects). + +To create a redirect, add a rule that includes a `from` path, a `to` path, +and an [HTTP status code](#http-status-codes): + +```plaintext +# 301 permanent redirect +/old/file.html /new/file.html 301 + +# 302 temporary redirect +/old/another_file.html /new/another_file.html 302 +``` + +## Rewrites + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/458) in GitLab 14.3. +> - Enabled on GitLab.com. +> - Disabled by default in self-managed GitLab behind the [`FF_ENABLE_PLACEHOLDERS` feature flag](#feature-flag-for-rewrites). + +Provide a status code of `200` to serve the content of the `to` path when the +request matches the `from`: + +```plaintext +/old/file.html /new/file.html 200 +``` + +This status code can be used in combination with [splat rules](#splats) to dynamically +rewrite the URL. + +## Splats + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/458) in GitLab 14.3. + +A rule with an asterisk (`*`) in its `from` path, known as a splat, matches +anything at the start, middle, or end of the requested path. This example +matches anything after `/old/` and rewrites it to `/new/file.html`: + +```plaintext +/old/* /new/file.html 200 +``` + +### Splat placeholders + +The content matched by a `*` in a rule's `from` path can be injected into the +`to` path using the `:splat` placeholder: + +```plaintext +/old/* /new/:splat 200 +``` + +In this example, a request to `/old/file.html` serves the contents of `/new/file.html` +with a `200` status code. + +If a rule's `from` path includes multiple splats, the value of the first splat +match replaces any `:splat`s in the `to` path. + +### Splat matching behavior + +Splats are "greedy" and match as many characters as possible: + +```plaintext +/old/*/file /new/:splat/file 301 +``` + +In this example, the rule redirects `/old/a/b/c/file` to `/new/a/b/c/file`. + +Splats also match empty strings, so the previous rule redirects +`/old/file` to `/new/file`. + +### Rewrite all requests to a root `index.html` + +Single page applications (SPAs) often perform their own routing using +client-side routes. For these applications, it's important that _all_ requests +are rewritten to the root `index.html` so that the routing logic can be handled +by the JavaScript application. You can do this with a `_redirects` +rule like: + +```plaintext +/* /index.html 200 +``` + +## Placeholders + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/458) in GitLab 14.3. + +Use placeholders in rules to match portions of the requested URL and use these +matches when rewriting or redirecting to a new URL. + +A placehold is formatted as a `:` character followed by a string of letters +(`[a-zA-Z]+`) in both the `from` and `to` paths: + +```plaintext +/news/:year/:month/:date/:slug /blog/:year-:month-:date-:slug 200 +``` + +This rule instructs Pages to respond to a request for `/news/2021/08/12/file.html` by +serving the content of `/blog/2021-08-12-file.html` with a `200`. + +### Placeholder matching behavior + +Compared to [splats](#splats), placeholders are more limited in how much content +they match. Placeholders match text between forward slashes +(`/`), so use placeholders to match single path segments. + +In addition, placeholders do not match empty strings. A rule like the following +would **not** match a request URL like `/old/file`: + +```plaintext +/old/:path /new/:path +``` + ## Debug redirect rules If a redirect isn't working as expected, or you want to check your redirect syntax, visit @@ -103,8 +225,49 @@ rule 10: valid rule 11: valid ``` -## Disable redirects +## Differences from Netlify's implementation + +Most supported `_redirects` rules behave the same in both GitLab and Netlify. +However, there are some minor differences: + +- **All rule URLs must begin with a slash:** + + Netlify does not require URLs to begin with a forward slash: + + ```plaintext + # Valid in Netlify, invalid in GitLab + */path /new/path 200 + ``` + + GitLab validates that all URLs begin with a forward slash. A valid + equivalent of the previous example: + + ```plaintext + # Valid in both Netlify and GitLab + /old/path /new/path 200 + ``` +- **All placeholder values are populated:** + + Netlify only populates placeholder values that appear in the `to` path: + + ```plaintext + /old /new/:placeholder + ``` + + Given a request to `/old`: + + - Netlify redirects to `/new/:placeholder` (with a + literal `:placeholder`). + - GitLab redirects to `/new/`. + +## Features behind feature flags + +Some Pages features are behind feature flags. + +### Feature flag for redirects + +FLAG: Redirects in GitLab Pages is under development, and is deployed behind a feature flag that is **enabled by default**. @@ -126,3 +289,28 @@ For [source installations](../../../administration/pages/source.md), define the export FF_ENABLE_REDIRECTS="false" /path/to/pages/bin/gitlab-pages -config gitlab-pages.conf ``` + +### Feature flag for rewrites + +FLAG: +Rewrites in GitLab Pages is under development, and is deployed behind a feature flag +that is **disabled by default**. + +To enable rewrites, for [Omnibus installations](../../../administration/pages/index.md), define the +`FF_ENABLE_PLACEHOLDERS` environment variable in the +[global settings](../../../administration/pages/index.md#global-settings). +Add the following line to `/etc/gitlab/gitlab.rb` and +[reconfigure the instance](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure): + +```ruby +gitlab_pages['env']['FF_ENABLE_PLACEHOLDERS'] = 'true' +``` + +For [source installations](../../../administration/pages/source.md), define the +`FF_ENABLE_PLACEHOLDERS` environment variable, then +[restart GitLab](../../../administration/restart_gitlab.md#installations-from-source): + +```shell +export FF_ENABLE_PLACEHOLDERS="true" +/path/to/pages/bin/gitlab-pages -config gitlab-pages.conf +``` |