diff --git a/doc/.vale/gitlab/spelling-exceptions.txt b/doc/.vale/gitlab/spelling-exceptions.txt index f269d02c40731c7f0633cd5ac2653d995fb6da21..1261cf5bae35734d3ff3c994c6e051035f5db90e 100644 --- a/doc/.vale/gitlab/spelling-exceptions.txt +++ b/doc/.vale/gitlab/spelling-exceptions.txt @@ -284,6 +284,7 @@ namespaces namespacing namespacings Nanoc +Netlify NGINX Nokogiri npm diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index f6ff13edabdb653dfdaf5a9f582c75fd5fe4b9d0..3c0030be6299a280eb14d607f9af35e51d98af36 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -235,6 +235,7 @@ control over how the Pages daemon runs and serves content in your environment. | `pages_path` | The directory on disk where pages are stored, defaults to `GITLAB-RAILS/shared/pages`. | `pages_nginx[]` | | | `enable` | Include a virtual host `server{}` block for Pages inside NGINX. Needed for NGINX to proxy traffic back to the Pages daemon. Set to `false` if the Pages daemon should directly receive all requests, for example, when using [custom domains](index.md#custom-domains). +| `FF_ENABLE_REDIRECTS` | Feature flag to enable redirects. See the [redirects documentation](../../user/project/pages/redirects.md#enable-or-disable-redirects) for more info. | --- @@ -424,6 +425,10 @@ Authority (CA) in the system certificate store. For Omnibus, this is fixed by [installing a custom CA in Omnibus GitLab](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). +## Enable redirects + +In GitLab Pages, you can [enable the redirects feature](../../user/project/pages/redirects.md#enable-or-disable-redirects) to configure rules to forward one URL to another using HTTP redirects. + ## Activate verbose logging for daemon Verbose logging was [introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/2533) in diff --git a/doc/administration/pages/source.md b/doc/administration/pages/source.md index 87217b141a48fc58838ca87f7c63da74c1588b64..662817e741163e97655fc76d87b2545ac931ca38 100644 --- a/doc/administration/pages/source.md +++ b/doc/administration/pages/source.md @@ -347,6 +347,10 @@ world. Custom domains and TLS are supported. 1. Restart NGINX 1. [Restart GitLab](../restart_gitlab.md#installations-from-source) +## Enable redirects + +In GitLab Pages, you can [enable the redirects feature](../../user/project/pages/redirects.md#enable-or-disable-redirects) to configure rules to forward one URL to another using HTTP redirects. + ## NGINX caveats NOTE: **Note:** diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index eff80a4c9bd6c7e6c0c0067108c1cdfd24ea2e83..6c3b911d033a4aa50cb6e637f9254c1425caa2e0 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -59,6 +59,7 @@ To update a GitLab Pages website: | [Explore GitLab Pages](introduction.md) | Requirements, technical aspects, specific GitLab CI/CD configuration options, Access Control, custom 404 pages, limitations, FAQ. | | [Custom domains and SSL/TLS Certificates](custom_domains_ssl_tls_certification/index.md) | Custom domains and subdomains, DNS records, and SSL/TLS certificates. | | [Let's Encrypt integration](custom_domains_ssl_tls_certification/lets_encrypt_integration.md) | Secure your Pages sites with Let's Encrypt certificates, which are automatically obtained and renewed by GitLab. | +| [Redirects](redirects.md) | Set up HTTP redirects to forward one page to another. | Learn more and see examples: diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index b497e6ae563135c61e9b18e876eeee31782f6105..adb187c74f27503689271fb398d90281c9da8b6b 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -60,14 +60,8 @@ If the case of `404.html`, there are different scenarios. For example: ## Redirects in GitLab Pages -Since you cannot use any custom server configuration files, like `.htaccess` or -any `.conf` file, if you want to redirect a page to another -location, you can use the [HTTP meta refresh tag](https://en.wikipedia.org/wiki/Meta_refresh). - -Some static site generators provide plugins for that functionality so that you -don't have to create and edit HTML files manually. For example, Jekyll has the -[redirect-from plugin](https://github.com/jekyll/jekyll-redirect-from), Sphinx -has the [sphinx-reredirects](https://gitlab.com/documatt/sphinx-reredirects) extension. +You can configure redirects for your site using a `_redirects` file. To learn more, read +the [redirects documentation](redirects.md). ## GitLab Pages Access Control **(CORE)** diff --git a/doc/user/project/pages/redirects.md b/doc/user/project/pages/redirects.md new file mode 100644 index 0000000000000000000000000000000000000000..ae7b1b4fa6e1d56b4d0c985ae3a9b15f249afc71 --- /dev/null +++ b/doc/user/project/pages/redirects.md @@ -0,0 +1,130 @@ +--- +stage: Release +group: Release Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Create redirects for GitLab Pages + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/24) in GitLab Pages 1.25.0 and GitLab 13.4. +> - It's [deployed behind a feature flag](#enable-or-disable-redirects), disabled by default. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-redirects). + +CAUTION: **Warning:** +This feature might not be available to you. Check the **version history** note above for details. + +In GitLab Pages, you can [enable](#enable-or-disable-redirects) the redirects feature to configure rules to forward one URL to another using HTTP redirects. GitLab Pages uses +[Netlify style redirects](https://docs.netlify.com/routing/redirects/#syntax-for-the-redirects-file). + +## 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, and GitLab Pages doesn't support all +[special options offered by Netlify](https://docs.netlify.com/routing/redirects/redirect-options/): + +| 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` | +| 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: **Note:** +Supported paths must start with a forward slash `/`. + +## Create redirects + +To create redirects after [enabling](#enable-or-disable-redirects) the feature, +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: + +```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 +``` + +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 +/redirect-portal.html /magic-land.html 301 +/cake-portal.html /still-alive.html 302 +/wardrobe.html /narnia.html 302 +/pit.html /spikes.html 302 +``` + +## Files override redirects + +Files take priority over redirects. If a file exists on disk, GitLab Pages serves +the file instead of your redirect. For example, if the files `hello.html` and +`world.html` exist, and the `_redirects` file contains the following line, the redirect +is ignored because `hello.html` exists: + +```plaintext +/projectname/hello.html /projectname/world.html 302 +``` + +NOTE: **Note:** +GitLab does not support Netlify's +[force option](https://docs.netlify.com/routing/redirects/rewrites-proxies/#shadowing) +to change this behavior. + +## Debug redirect rules + +If a redirect isn't working as expected, or you want to check your redirect syntax, visit +`https://[namespace.gitlab.io]/projectname/_redirects`, replacing `[namespace.gitlab.io]` with +your domain name. The `_redirects` file isn't served directly, but your browser +displays a numbered list of your redirect rules, and whether the rule is valid or invalid: + +```plaintext +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 +``` + +## Enable or disable redirects + +Redirects in GitLab Pages is under development and not ready for production use. It is +deployed behind a feature flag that is **disabled by default**. + +For [Omnibus installations](../../../administration/pages/index.md), define the +`FF_ENABLE_REDIRECTS` 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_REDIRECTS'] = 'true' +``` + +For [source installations](../../../administration/pages/source.md), define the +`FF_ENABLE_REDIRECTS` environment variable, then +[restart GitLab](../../../administration/restart_gitlab.md#installations-from-source): + +```shell +export FF_ENABLE_REDIRECTS="true" +/path/to/pages/bin/gitlab-pages -config gitlab-pages.conf +```