5.3 KiB
stage | group | info |
---|---|---|
Release | Release | To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments |
Create redirects for GitLab Pages
- Introduced in GitLab Pages 1.25.0 and GitLab 13.4 behind a feature flag, disabled by default.
- Became enabled by default 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 HTTP redirects.
Supported features
GitLab Pages only supports the
_redirects
plain text file syntax,
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.
Note that supported paths must start with a forward slash /
.
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 | {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) | {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 |
Create redirects
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:
/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,
no project name prefix is needed. For example, if your custom domain is example.com
,
your _redirect
file would look like:
/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:
/projectname/hello.html /projectname/world.html 302
GitLab doesn't support Netlify's force option 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:
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
Disable redirects
Redirects in GitLab Pages is under development, and is deployed behind a feature flag that is enabled by default.
To disable redirects, for Omnibus installations, define the
FF_ENABLE_REDIRECTS
environment variable in the
global settings.
Add the following line to /etc/gitlab/gitlab.rb
and
reconfigure the instance.
gitlab_pages['env']['FF_ENABLE_REDIRECTS'] = 'false'
For source installations, define the
FF_ENABLE_REDIRECTS
environment variable, then
restart GitLab:
export FF_ENABLE_REDIRECTS="false"
/path/to/pages/bin/gitlab-pages -config gitlab-pages.conf