Commit 94e68744 authored by Eric Eastwood's avatar Eric Eastwood Committed by Amy Qualls (slowly returning after surgery)

Add docs for Gitlab Pages Redirects

Redirects feature added in https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/336
parent d9579427
...@@ -284,6 +284,7 @@ namespaces ...@@ -284,6 +284,7 @@ namespaces
namespacing namespacing
namespacings namespacings
Nanoc Nanoc
Netlify
NGINX NGINX
Nokogiri Nokogiri
npm npm
......
...@@ -235,6 +235,7 @@ control over how the Pages daemon runs and serves content in your environment. ...@@ -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_path` | The directory on disk where pages are stored, defaults to `GITLAB-RAILS/shared/pages`.
| `pages_nginx[]` | | | `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). | `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. ...@@ -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). 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 ## Activate verbose logging for daemon
Verbose logging was [introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/2533) in Verbose logging was [introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/2533) in
......
...@@ -347,6 +347,10 @@ world. Custom domains and TLS are supported. ...@@ -347,6 +347,10 @@ world. Custom domains and TLS are supported.
1. Restart NGINX 1. Restart NGINX
1. [Restart GitLab](../restart_gitlab.md#installations-from-source) 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 ## NGINX caveats
NOTE: **Note:** NOTE: **Note:**
......
...@@ -59,6 +59,7 @@ To update a GitLab Pages website: ...@@ -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. | | [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. | | [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. | | [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: Learn more and see examples:
......
...@@ -60,14 +60,8 @@ If the case of `404.html`, there are different scenarios. For example: ...@@ -60,14 +60,8 @@ If the case of `404.html`, there are different scenarios. For example:
## Redirects in GitLab Pages ## Redirects in GitLab Pages
Since you cannot use any custom server configuration files, like `.htaccess` or You can configure redirects for your site using a `_redirects` file. To learn more, read
any `.conf` file, if you want to redirect a page to another the [redirects documentation](redirects.md).
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.
## GitLab Pages Access Control **(CORE)** ## GitLab Pages Access Control **(CORE)**
......
---
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
```
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment