GitLab Pages 리다이렉션

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-Managed, GitLab Dedicated

GitLab Pages에서는 Netlify style HTTP 리다이렉트를 사용하여 한 URL을 다른 URL로 전달하는 규칙을 구성할 수 있습니다.

special options offered by Netlify와 같은 모든 특별한 옵션을 지원하지는 않습니다.

기능 지원 여부 예시
리다이렉트 (301, 302) 예 /wardrobe.html /narnia.html 302
리라이트 (200) 예 /* / 200
스플랫 예 /news/* /blog/:splat
플레이스홀더 예 /news/:year/:month/:date /blog-:year-:month-:date.html
리라이트 (200 이외) 아니요 /en/* /en/404.html 404
쿼리 파라미터 아니요 /store id=:id /blog/:id 301
강제 (shadowing) 아니요 /app/ /app/index.html 200!
도메인 수준 리다이렉트 예 http://blog.example.com/* https://www.example.com/blog/:splat 301
국가 또는 언어별 리다이렉트 아니요 / /anz 302 Country=au,nz
역할별 리다이렉트 아니요 /admin/* 200! Role=admin
note
matching behavior test cases는 GitLab이 규칙 일치를 구현하는 방법을 자세히 이해하는 데 유용한 자료입니다. 커뮤니티 기여는 이 테스트 스위트에 포함되지 않은 모든 예외 사항에 대해 환영됩니다!

리다이렉트 생성

리다이렉트를 만들려면 GitLab Pages 사이트의 public/ 디렉터리에 _redirects라는 구성 파일을 만듭니다.

  • 모든 경로는 슬래시(/)로 시작해야 합니다.
  • 제공된 상태 코드가 없는 경우 기본 상태 코드 301이 적용됩니다.
  • _redirects 파일에는 파일 크기 제한과 프로젝트당 최대 규칙 수가 있으며 인스턴스 수준에서 구성됩니다. 구성된 최대 규칙 내에서 처음으로 일치하는 규칙만 처리됩니다. 기본 파일 크기 제한은 64 KB이고, 기본 최대 규칙 수는 1,000입니다.

  • GitLab Pages 사이트가 기본 도메인 이름(예: namespace.gitlab.io/project-slug)을 사용하는 경우 모든 규칙 앞에 경로를 접두사로 붙여야 합니다: 

    /project-slug/wardrobe.html /project-slug/narnia.html 302

  • GitLab Pages 사이트가 custom domains을 사용하는 경우 프로젝트 경로 접두사가 필요하지 않습니다. 예를 들어, 사용자 정의 도메인이 example.com인 경우 _redirects 파일은 다음과 같습니다: 

    /wardrobe.html /narnia.html 302

파일이 리다이렉트를 재정의합니다

파일은 리다이렉트보다 우선합니다. 디스크에 파일이 존재하는 경우 GitLab Pages는 리다이렉트 대신 파일을 제공합니다. 예를 들어 hello.html과 world.html 파일이 존재하고, _redirects 파일에 다음 줄이 포함된 경우 hello.html이 존재하기 때문에 리다이렉트는 무시됩니다: 

/project-slug/hello.html /project-slug/world.html 302

GitLab은 Netlify의 force option을 지원하지 않습니다.

HTTP 상태 코드

상태 코드가 제공되지 않은 경우 기본 상태 코드 301이 적용되지만, 직접 설정할 수 있습니다. 지원되는 HTTP 코드는 다음과 같습니다:

  • 301: 영구적 리다이렉트.
  • 302: 임시 리다이렉트.
  • 200: 성공적인 HTTP 요청에 대한 표준 응답. 페이지가 to 규칙에 있는 내용을 제공하며, 주소 표시줄의 URL을 변경하지 않습니다.

리다이렉트

리다이렉트를 만들려면 from 경로, to 경로 및 HTTP 상태 코드가 포함된 규칙을 추가합니다: 

# 301 영구적 리다이렉트
/old/file.html /new/file.html 301

# 302 임시 리다이렉트
/old/another_file.html /new/another_file.html 302

리라이트

  • GitLab 15.2에서 GitLab.com과 Self-Managed형에서 사용 가능.

요청이 from과 일치할 때 to 경로의 내용을 제공하려면 200 상태 코드를 제공합니다: 

/old/file.html /new/file.html 200

이 상태 코드는 스플랫 규칙과 결합하여 URL을 동적으로 재작성하는 데 사용할 수 있습니다.

도메인 수준 리다이렉트

Self-Managed형 GitLab에서는 기본적으로 이 기능을 사용할 수 없습니다. 사용하려면 관리자가 환경 변수 사용를 위해 FF_ENABLE_DOMAIN_REDIRECT라는 피처 플래그를 활성화할 수 있습니다. GitLab.com에서는 이 기능을 사용할 수 있습니다. GitLab Dedicated에서는 이 기능을 사용할 수 없습니다.

도메인 수준 리다이렉트를 만들려면 도메인 수준 경로(http:// 또는 https://로 시작)를 to 경로 또는 from 및 to 경로로 추가합니다.

지원되는 HTTP 상태 코드는 301과 302입니다: 

# 301 영구적 리다이렉트
http://blog.example.com/file_1.html https://www.example.com/blog/file_1.html 301
/file_2.html https://www.example.com/blog/file_2.html 301

# 302 임시 리다이렉트
http://blog.example.com/file_3.html https://www.example.com/blog/file_3.html 302
/file_4.html https://www.example.com/blog/file_4.html 302

도메인 수준 리다이렉트는 스플랫 규칙(스플랫 플레이스홀더 포함)과 결합하여 URL 경로를 동적으로 재작성하는 데 사용할 수 있습니다.

Splat 플레이스홀더

규칙의 from 경로에서 *로 일치하는 내용은 to 경로에서 :splat 플레이스홀더를 사용하여 삽입될 수 있습니다: 

/old/* /new/:splat 200

이 예에서 /old/file.html로의 요청은 200 상태 코드와 함께 /new/file.html의 내용을 제공합니다.

만약 규칙의 from 경로가 여러 개의 splat을 포함하면, 첫 번째 splat 일치의 값이 to 경로의 모든 :splat을 대체합니다.

Splat 일치 동작

Splats은 “탐욕스러우며” 가능한 많은 문자와 일치합니다: 

/old/*/file /new/:splat/file 301

이 예에서 규칙은 /old/a/b/c/file을 /new/a/b/c/file로 리디렉션합니다.

Splats은 빈 문자열과도 일치하므로, 이전 규칙은 /old/file을 /new/file로 리디렉션합니다.

모든 요청을 루트 index.html로 재작성하기

note
만약 GitLab Pages integration with Let’s Encrypt을 사용 중이라면 이 규칙을 추가하기 전에 이를 활성화해야 합니다. 그렇지 않으면 리디렉션이 Let’s Encrypt 통합을 망가뜨립니다. 더 자세한 내용은 GitLab Pages issue 649를 참조하세요.

싱글 페이지 애플리케이션(SPA)은 종종 클라이언트 측 라우트를 사용하여 자체 라우팅을 수행합니다. 이러한 애플리케이션에 대해 모든 요청이 루트 index.html로 재작성되어야 합니다. 이는 루팅 로직이 JavaScript 애플리케이션에서 처리될 수 있도록하기 위함입니다. 이를 _redirects 규칙으로 수행할 수 있습니다: 

/* /index.html 200

플레이스홀더

규칙에서 플레이스홀더를 사용하여 요청된 URL의 일부를 일치시키고 새 URL로 재작성하거나 리디렉팅하는 데 사용합니다.

플레이스홀더는 : 문자 다음의 문자열([a-zA-Z]+)로 형식화되며 from 및 to 경로에서 모두 사용됩니다: 

/news/:year/:month/:date/:slug /blog/:year-:month-:date-:slug 200

이 규칙은 Pages에게 /news/2021/08/12/file.html에 대한 요청에 대해 200과 함께 /blog/2021-08-12-file.html의 내용을 제공하도록 지시합니다.

플레이스홀더 일치 동작

splats와 비교하여, 플레이스홀더는 일치하는 콘텐츠의 양에 있어서 더 제한적입니다. 플레이스홀더는 슬래시(/) 사이의 텍스트에 일치하므로, 단일 경로 세그먼트에 대한 일치시키기 위해 플레이스홀더를 사용하세요.

또한 플레이스홀더는 빈 문자열과 일치하지 않습니다. 다음과 같은 규칙은 /old/file과 같은 요청 URL과 일치하지 않습니다: 

/old/:path /new/:path

리디렉트 규칙 디버깅

리디렉트가 예상대로 작동하지 않거나 리디렉트 구문을 확인하려는 경우 [your pages url]/_redirects를 방문하세요. _redirects 파일은 직접 제공되지 않지만, 브라우저에서는 리디렉트 규칙의 번호가 매겨지고 해당 규칙이 유효한지 여부가 표시됩니다: 

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

Netlify 구현과의 차이점

대부분의 지원되는 _redirects 규칙은 GitLab과 Netlify에서 동일하게 작동합니다. 그러나 약간의 차이가 있습니다:

  • 모든 규칙 URL은 슬래시로 시작해야 합니다:

    Netlify는 URL이 슬래시로 시작되지 않아도 됩니다: 

    # Netlify에서는 유효하며, GitLab에서는 유효하지 않음
*/path /new/path 200

    GitLab은 모든 URL이 슬래시로 시작하는지 확인합니다. 이전 예제의 유효한 등가 예시는 다음과 같습니다: 

    # Netlify와 GitLab 모두에서 유효
/old/path /new/path 200

  • 모든 플레이스홀더 값이 채워집니다:

    Netlify는 to 경로에 나타나는 플레이스홀더 값만 채웁니다: 

    /old /new/:placeholder

    /old 요청을 받았을 때,

    • Netlify는 리디렉트를 /new/:placeholder(문자 그대로의 :placeholder)로 수행합니다.
    • GitLab은 /new/로 리디렉트합니다.