커스텀 도메인은 다음 용도로 사용할 수 있습니다.

• GitLab Pages와 함께 사용합니다.
• SAML 또는 SCIM으로 프로비저닝된 사용자의 이메일 확인 절차를 건너뛰는 데 사용합니다. 이 방식으로 커스텀 도메인을 사용하면 GitLab Pages 기능을 쓰되 사전 요구 사항은 건너뛸 수 있습니다.

커스텀 도메인 이름을 하나 이상 사용하려면 다음 작업을 수행합니다.

• 커스텀 루트 도메인 또는 서브도메인을 추가합니다.
• SSL/TLS 인증서를 추가합니다.

커스텀 도메인 설정#

커스텀 도메인으로 Pages를 설정하려면 다음 단계를 완료합니다.

사전 요구 사항#

• 관리자가 GitLab Pages 커스텀 도메인을 위해 서버를 구성해야 합니다.
• 기본 Pages 도메인(GitLab.com의 경우 *.gitlab.io)으로 제공되는 GitLab Pages 웹사이트가 실행 중이어야 합니다.
• 커스텀 도메인 이름 example.com 또는 서브도메인 subdomain.example.com 이 필요합니다.
• DNS 레코드를 설정할 수 있는 도메인 서버 제어판에 접근할 수 있어야 합니다.
  • 도메인을 GitLab Pages 서버로 연결하는 DNS 레코드(A, AAAA, ALIAS 또는 CNAME). 해당 이름에 DNS 레코드가 여러 개 있으면 ALIAS 레코드를 사용해야 합니다.
  • 도메인 소유권을 확인하는 DNS TXT 레코드.

DNS 레코드 개요는 GitLab Pages DNS 레코드를 참고합니다.

1단계: 커스텀 도메인 추가#

GitLab Pages에 커스텀 도메인을 추가하려면 다음 단계를 수행합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Deploy > Pages를 선택합니다.
3. 오른쪽 상단 모서리에서 New Domain을 선택합니다.
4. Domain에 도메인 이름을 입력합니다.
5. 선택 사항. Certificate에서 Automatic certificate management using Let's Encrypt 토글을 꺼서 SSL/TLS 인증서를 추가합니다. 인증서와 키는 나중에 추가할 수도 있습니다.
6. Create New Domain을 선택합니다.

2단계: 인증 코드 받기#

Pages에 새 도메인을 추가하면 GitLab이 인증 코드를 표시합니다. 다음 단계에서 이 값을 복사하여 도메인 제어판에 TXT 레코드로 붙여 넣습니다.

인증 코드의 구조는 다음과 같습니다.

• Name/Host:
  • 루트 도메인: _gitlab-pages-verification-code.example.com
  • 서브도메인: _gitlab-pages-verification-code.subdomain.example.com
• DNS 레코드 유형: TXT
• 값: gitlab-pages-verification-code=00112233445566778899aabbccddeeff (GitLab에 표시된 실제 코드를 사용합니다)

3단계: DNS 레코드 설정#

Pages 사이트에서 사용하려는 도메인 유형에 맞게 DNS 레코드를 설정하려면 다음 중 하나를 선택합니다.

• 루트 도메인
• 서브도메인
• 루트 도메인과 서브도메인 모두

루트 도메인#

루트 도메인(example.com)에는 다음이 필요합니다.

• 다음 중 최소 하나:
  • 도메인을 Pages 서버로 연결하는 DNS A 레코드.
  • 도메인을 Pages 서버로 연결하는 DNS AAAA 레코드.
• 도메인 소유권을 확인하는 TXT 레코드.

GitLab.com의 프로젝트에서 IPv4 주소는 35.185.44.232 이고 IPv6 주소는 2600:1901:0:7b8a:: 입니다.

다른 GitLab 인스턴스(CE 또는 EE)의 프로젝트에서는 시스템 관리자에게 문의하여 해당 인스턴스의 Pages 서버 IP 주소를 요청합니다.

서브도메인#

서브도메인(subdomain.example.com)에는 다음이 필요합니다.

• 서브도메인을 Pages 서버로 연결하는 DNS ALIAS 또는 CNAME 레코드.
• 도메인 소유권을 확인하는 DNS TXT 레코드.

사용자 웹사이트든 프로젝트 웹사이트든 DNS 레코드는 경로 없이 Pages 도메인(namespace.gitlab.io)을 가리켜야 합니다.

루트 도메인과 서브도메인 모두#

예를 들어 example.com과 www.example.com처럼 루트 도메인과 서브도메인을 같은 웹사이트로 연결하려면 다음이 필요합니다.

• 도메인의 DNS A 레코드.
• 도메인의 DNS AAAA 레코드.
• 서브도메인의 DNS ALIAS/CNAME 레코드.
• 각각에 대한 DNS TXT 레코드.

Cloudflare를 사용한다면 Cloudflare로 www.domain.com을 domain.com으로 리다이렉트를 참고합니다.

추가로 다음 사항을 확인합니다.

• domain.com을 GitLab Pages 사이트로 연결하려는 경우 CNAME 레코드를 사용하지 않습니다. 대신 A 레코드를 사용합니다.
• 기본 Pages 도메인 뒤에 특수 문자를 추가하지 않습니다. 예를 들어 subdomain.domain.com을 namespace.gitlab.io/로 연결하지 않습니다. 일부 도메인 호스팅 공급자는 끝에 점을 붙인 형태(namespace.gitlab.io.)를 요구할 수 있습니다.
• 2018년에 GitLab.com의 GitLab Pages IP가 52.167.214.135에서 35.185.44.232로 변경됨.
• 2023년에 GitLab.com에 IPv6 지원이 추가됨.

4단계: 도메인 소유권 확인#

DNS 레코드를 모두 추가한 후 다음 단계를 수행합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Deploy > Pages를 선택합니다.
3. 도메인 이름 옆에서 Edit (✏️)를 선택합니다.
4. Verification status에서 Retry verification ([retry])을 선택합니다.

도메인이 활성화되면 해당 도메인 이름으로 웹사이트를 사용할 수 있습니다.

추가로 다음 사항을 확인합니다.

• GitLab.com 사용자는 도메인 인증이 필수입니다. GitLab Self-Managed에서는 GitLab 관리자가 커스텀 도메인 인증을 비활성화할 수 있습니다.
• DNS 전파에는 시간이 걸릴 수 있습니다(최대 24시간). 보통은 몇 분 안에 완료됩니다. 전파가 완료될 때까지 인증은 실패하고, 도메인에 접속하면 404가 표시됩니다.
• 도메인이 인증된 후에도 인증 레코드를 그대로 둡니다. 도메인은 주기적으로 재인증되며, 레코드를 제거하면 비활성화될 수 있습니다.

도메인 별칭 추가#

같은 프로젝트에 별칭(커스텀 도메인과 서브도메인)을 여러 개 추가할 수 있습니다. 별칭은 같은 방으로 통하는 여러 개의 문이라고 이해할 수 있습니다.

사이트에 설정한 모든 별칭은 Settings > Pages에 표시됩니다. 해당 페이지에서 별칭을 확인하고 추가하거나 제거할 수 있습니다.

Cloudflare로 www.domain.com을 domain.com으로 리다이렉트#

Cloudflare를 사용하면 두 도메인을 모두 GitLab에 추가하지 않고도 페이지 규칙으로 www.domain.com을 domain.com으로 리다이렉트할 수 있습니다.

1. Cloudflare에서 다음 중 최소 하나를 생성합니다.
   • domain.com을 35.185.44.232로 연결하는 DNS A 레코드.
   • domain.com을 2600:1901:0:7b8a::로 연결하는 DNS AAAA 레코드.
2. GitLab에서 GitLab Pages에 도메인을 추가하고 인증 코드를 받습니다.
3. Cloudflare에서 도메인을 인증하는 DNS TXT 레코드를 생성합니다.
4. GitLab에서 도메인을 인증합니다.
5. Cloudflare에서 www를 domain.com으로 연결하는 DNS CNAME 레코드를 생성합니다.
6. Cloudflare에서 www.domain.com을 domain.com으로 연결하는 Page Rule을 추가합니다.
   1. 도메인 대시보드로 이동합니다. 상단 탐색에서 Page Rules를 선택합니다.
   2. Create Page Rule을 선택합니다.
   3. 도메인 www.domain.com을 입력하고 + Add a Setting을 선택합니다.
   4. 드롭다운 목록에서 Forwarding URL을 선택한 다음 상태 코드 301 - Permanent Redirect를 선택합니다.
   5. 대상 URL https://domain.com을 입력합니다.

Pages에 SSL/TLS 인증서 추가#

GitLab Pages에서 커스텀 도메인을 보호하려면 다음 방법을 사용할 수 있습니다.

• Let's Encrypt 통합으로 SSL 인증서를 자동으로 발급하고 갱신합니다.
• SSL/TLS 인증서를 수동으로 추가합니다.

SSL/TLS 인증서 개요는 GitLab Pages SSL/TLS 인증서를 참고합니다.

SSL/TLS 인증서 수동 추가#

사전 요구 사항:

• 커스텀 도메인으로 접근할 수 있는 GitLab Pages 웹사이트가 실행 중이어야 합니다.

• 다음 인증서 구성 요소가 필요합니다.

  • PEM 인증서: CA가 생성한 인증서입니다.
  • 중간 인증서: 루트 인증서라고도 하며 CA를 식별합니다. 보통 PEM 인증서와 결합되어 있지만, Cloudflare 인증서 같은 일부 인증서는 별도로 추가해야 합니다.
  • 비공개 키: PEM을 도메인에 대해 검증하는 암호화된 키입니다.

새 도메인을 생성할 때 인증서를 추가하려면 다음 단계를 수행합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Deploy > Pages를 선택합니다.
3. 오른쪽 상단 모서리에서 New Domain을 선택합니다.
4. Domain에 도메인 이름을 입력합니다.
5. Certificate에서 Automatic certificate management using Let's Encrypt 토글을 끕니다.
6. 인증서 필드를 입력합니다.
7. Create New Domain을 선택합니다.

기존 도메인에 인증서를 추가하려면 다음 단계를 수행합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Deploy > Pages를 선택합니다.
3. 도메인 이름 옆에서 Edit (✏️)를 선택합니다.
4. Certificate에서 Automatic certificate management using Let's Encrypt 토글을 끕니다.
5. 인증서 필드를 입력합니다.
6. Save changes를 선택합니다.

인증서 필드를 입력할 때는 다음을 따릅니다.

• **Certificate (PEM)**에 PEM 인증서를 붙여 넣습니다. 인증서에 별도의 중간 인증서가 필요하면 같은 필드에 빈 줄로 구분하여 붙여 넣습니다. 자세한 내용은 Cloudflare 인증서로 GitLab Pages 설정하기를 참고합니다.
• 비공개 키 필드에 비공개 키를 붙여 넣습니다.

GitLab Pages 웹사이트에 HTTPS 강제 적용#

GitLab Pages에 HTTPS를 강제 적용하여 HTTP 요청을 301 리다이렉트로 HTTPS에 자동 전달할 수 있습니다. 이 기능은 기본 GitLab Pages 도메인과 유효한 인증서가 있는 커스텀 도메인에서 동작합니다.

HTTPS를 강제 적용하려면 다음 단계를 수행합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Deploy > Pages를 선택합니다.
3. Force HTTPS (requires valid certificates) 체크박스를 선택합니다.
4. Save changes를 선택합니다.

GitLab Pages 앞단에 Cloudflare CDN을 사용한다면 SSL 연결 설정을 flexible 이 아니라 full로 설정합니다. 자세한 내용은 Cloudflare CDN 안내를 참고합니다.

커스텀 도메인 편집#

커스텀 도메인을 편집하여 다음 작업을 수행할 수 있습니다.

• 커스텀 도메인을 확인합니다.
• 추가할 DNS 레코드를 확인합니다.
• TXT 인증 항목을 확인합니다.
• 인증을 다시 시도합니다.
• 인증서 설정을 편집합니다.

커스텀 도메인을 편집하려면 다음 단계를 수행합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Deploy > Pages를 선택합니다.
3. 도메인 이름 옆에서 Edit (✏️)를 선택합니다.

커스텀 도메인 삭제#

커스텀 도메인을 삭제하면 해당 도메인은 GitLab에서 더 이상 인증되지 않으며 GitLab Pages에서 사용할 수 없습니다.

커스텀 도메인을 삭제하고 제거하려면 다음 단계를 수행합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Deploy > Pages를 선택합니다.
3. 도메인 이름 옆에서 Remove domain ([remove])을 선택합니다.
4. 확인 메시지가 표시되면 Remove domain을 선택합니다.

문제 해결#

도메인 인증#

도메인 인증용 TXT DNS 항목이 올바르게 구성되었는지 직접 확인하려면 터미널에서 다음 명령을 실행합니다.

dig _gitlab-pages-verification-code. TXT

다음과 같은 출력이 나타납니다.

;; ANSWER SECTION:
_gitlab-pages-verification-code.. 300 IN TXT "gitlab-pages-verification-code="

등록하려는 도메인 이름과 동일한 이름으로 인증 코드를 추가하면 도움이 되는 경우가 있습니다.

루트 도메인의 경우:

서브도메인의 경우: