- Create redirects
- Files override redirects
- HTTP status codes
- Debug redirect rules
- Differences from Netlify’s implementation
- Feature flag for rewrites
In GitLab Pages, you can configure rules to forward one URL to another using Netlify style HTTP redirects.
Not all special options offered by Netlify are supported.
|Rewrites (other than ||No|
|Redirect by country or language||No|
|Redirect by role||No|
To create redirects, create a configuration file named
_redirects in the
public/ directory of your GitLab Pages site.
- All paths must start with a forward slash
- A default status code of
301is applied if no status code is provided.
_redirectsfile 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:
/projectname/wardrobe.html /projectname/narnia.html 302
If your GitLab Pages site uses custom domains, no project name prefix is needed. For example, if your custom domain is
_redirectsfile would look like:
/wardrobe.html /narnia.html 302
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
world.html exist, and the
_redirects file contains the following line, the redirect
is ignored because
/projectname/hello.html /projectname/world.html 302
GitLab doesn’t support Netlify’s force option to change this behavior.
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
torule if it exists, without changing the URL in the address bar.
To create a redirect, add a rule that includes a
from path, a
and an HTTP status code:
# 301 permanent redirect /old/file.html /new/file.html 301 # 302 temporary redirect /old/another_file.html /new/another_file.html 302
Provide a status code of
200 to serve the content of the
to path when the
request matches the
/old/file.html /new/file.html 200
This status code can be used in combination with splat rules to dynamically rewrite the URL.
Introduced 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
/old/* /new/file.html 200
The content matched by a
* in a rule’s
from path can be injected into the
to path using the
/old/* /new/:splat 200
In this example, a request to
/old/file.html serves the contents of
200 status code.
If a rule’s
from path includes multiple splats, the value of the first splat
match replaces any
:splats in the
Splats are “greedy” and match as many characters as possible:
/old/*/file /new/:splat/file 301
In this example, the rule redirects
Splats also match empty strings, so the previous rule redirects
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
/* /index.html 200
Introduced 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 placeholder is formatted as a
: character followed by a string of letters
[a-zA-Z]+) in both the
/news/:year/:month/:date/:slug /blog/:year-:month-:date-:slug 200
This rule instructs Pages to respond to a request for
serving the content of
/blog/2021-08-12-file.html with a
Compared to 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
If a redirect isn’t working as expected, or you want to check your redirect syntax, visit
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
_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:
# 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:
# 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
Given a request to
- Netlify redirects to
/new/:placeholder(with a literal
- GitLab redirects to
- Netlify redirects to
To enable rewrites, for Omnibus installations, define the
FF_ENABLE_PLACEHOLDERS environment variable in the
Add the following line to
reconfigure the instance:
gitlab_pages['env']['FF_ENABLE_PLACEHOLDERS'] = 'true'
export FF_ENABLE_PLACEHOLDERS="true" /path/to/pages/bin/gitlab-pages -config gitlab-pages.conf