커스텀 도메인을 다음과 같이 사용할 수 있습니다:

• GitLab Pages와 함께 사용.
• SAML 또는 SCIM 프로비저닝된 사용자의 이메일 확인 우회. 이 방식으로 커스텀 도메인을 사용할 때는 GitLab Pages 기능을 사용하지만 사전 요구 사항을 건너뛸 수 있습니다.

하나 이상의 커스텀 도메인 이름을 사용하려면:

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

커스텀 도메인 설정#

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

사전 요구 사항#

• 관리자가 GitLab Pages 커스텀 도메인을 위한 서버를 구성했어야 합니다.
• GitLab Pages 웹사이트가 실행 중이고 기본 Pages 도메인(GitLab.com의 경우 *.gitlab.io) 아래에서 서비스되고 있어야 합니다.
• 커스텀 도메인 이름 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. 상단 표시줄에서 검색 또는 이동을 선택하고 프로젝트를 찾으세요.
2. 왼쪽 사이드바에서 배포 > Pages를 선택하세요.
3. 오른쪽 상단에서 새 도메인을 선택하세요.
4. 도메인에 도메인 이름을 입력하세요.
5. 선택 사항. 인증서에서 Let's Encrypt를 사용한 자동 인증서 관리 토글을 끄고 SSL/TLS 인증서를 추가하세요. 나중에 인증서와 키를 추가할 수도 있습니다.
6. 새 도메인 생성을 선택하세요.

2단계: 인증 코드 받기#

Pages에 새 도메인을 추가한 후 GitLab에 인증 코드가 표시됩니다. 값을 복사하여 다음 단계에서 도메인 제어판에 TXT 레코드로 붙여넣으세요.

인증 상태 필드의 구조는 다음과 같습니다:

• 이름/호스트:
  • 루트 도메인의 경우: _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.)을 요청할 수 있습니다.
• 변경됨 GitLab Pages IP가 2018년에 GitLab.com에서 52.167.214.135에서 35.185.44.232로 변경되었습니다.
• 추가됨 2023년에 GitLab.com에 IPv6 지원이 추가되었습니다.

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

모든 DNS 레코드를 추가한 후:

1. 상단 표시줄에서 검색 또는 이동을 선택하고 프로젝트를 찾으세요.
2. 배포 > Pages를 선택하세요.
3. 도메인 이름 옆에서 편집(✏️)을 선택하세요.
4. 인증 상태에서 인증 재시도([retry])를 선택하세요.

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

또한:

• 도메인 인증은 GitLab.com 사용자에게 필수입니다. GitLab Self-Managed의 경우 GitLab 관리자가 커스텀 도메인 인증을 비활성화하는 옵션이 있습니다.
• DNS 전파는 시간이 걸릴 수 있습니다(최대 24시간). 완료될 때까지 인증은 실패하고 도메인을 방문하려는 시도는 404로 이어집니다.
• 도메인이 인증된 후 인증 레코드를 그대로 유지하세요. 도메인은 주기적으로 재인증되며, 레코드가 제거되면 비활성화될 수 있습니다.

도메인 별칭 추가#

동일한 프로젝트에 하나 이상의 별칭(커스텀 도메인과 서브도메인)을 추가할 수 있습니다. 별칭은 같은 방으로 이어지는 여러 문이 있는 것으로 이해할 수 있습니다.

사이트에 설정한 모든 별칭은 설정 > 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으로 가리키는 페이지 규칙을 추가하세요:
   1. 도메인의 대시보드로 이동하세요. 상단 탐색에서 페이지 규칙을 선택하세요.
   2. 페이지 규칙 생성을 선택하세요.
   3. 도메인 www.domain.com을 입력하고 + 설정 추가를 선택하세요.
   4. 드롭다운 목록에서 URL 전달을 선택한 다음 상태 코드 301 - 영구 리다이렉트를 선택하세요.
   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. 상단 표시줄에서 검색 또는 이동을 선택하고 프로젝트를 찾으세요.
2. 배포 > Pages를 선택하세요.
3. 오른쪽 상단에서 새 도메인을 선택하세요.
4. 도메인에 도메인 이름을 입력하세요.
5. 인증서에서 Let's Encrypt를 사용한 자동 인증서 관리 토글을 끄세요.
6. 인증서 필드를 완성하세요.
7. 새 도메인 생성을 선택하세요.

기존 도메인에 인증서를 추가하려면:

1. 상단 표시줄에서 검색 또는 이동을 선택하고 프로젝트를 찾으세요.
2. 배포 > Pages를 선택하세요.
3. 도메인 이름 옆에서 편집(✏️)을 선택하세요.
4. 인증서에서 Let's Encrypt를 사용한 자동 인증서 관리 토글을 끄세요.
5. 인증서 필드를 완성하세요.
6. 변경 사항 저장을 선택하세요.

인증서 필드를 완성할 때:

• **인증서(PEM)**에 PEM 인증서를 붙여넣으세요. 인증서에 별도의 중간 인증서가 필요한 경우 빈 줄로 구분하여 동일한 필드에 붙여넣으세요. 자세한 내용은 Cloudflare 인증서로 GitLab Pages 설정을 참조하세요.
• 개인 키 필드에 개인 키를 붙여넣으세요.

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

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

HTTPS를 강제 적용하려면:

1. 상단 표시줄에서 검색 또는 이동을 선택하고 프로젝트를 찾으세요.
2. 배포 > Pages를 선택하세요.
3. HTTPS 강제 적용(유효한 인증서 필요) 체크박스를 선택하세요.
4. 변경 사항 저장을 선택하세요.

GitLab Pages 앞에 Cloudflare CDN을 사용하는 경우 SSL 연결 설정을 flexible 대신 full로 설정하세요. 자세한 내용은 Cloudflare CDN 지침을 참조하세요.

커스텀 도메인 편집#

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

• 커스텀 도메인 보기.
• 추가할 DNS 레코드 보기.
• TXT 인증 항목 보기.
• 인증 재시도.
• 인증서 설정 편집.

커스텀 도메인을 편집하려면:

1. 상단 표시줄에서 검색 또는 이동을 선택하고 프로젝트를 찾으세요.
2. 배포 > Pages를 선택하세요.
3. 도메인 이름 옆에서 편집(✏️)을 선택하세요.

커스텀 도메인 삭제#

커스텀 도메인이 삭제되면 GitLab에서 도메인이 더 이상 인증되지 않고 GitLab Pages와 함께 사용할 수 없습니다.

커스텀 도메인을 삭제하고 제거하려면:

1. 상단 표시줄에서 검색 또는 이동을 선택하고 프로젝트를 찾으세요.
2. 배포 > Pages를 선택하세요.
3. 도메인 이름 옆에서 도메인 제거([remove])를 선택하세요.
4. 메시지가 표시되면 도메인 제거를 선택하세요.

트러블슈팅#

도메인 인증#

도메인 인증 TXT DNS 항목을 올바르게 구성했는지 수동으로 확인하려면 터미널에서 다음 명령을 실행할 수 있습니다:

dig _gitlab-pages-verification-code. TXT

예상 출력:

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

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

루트 도메인의 경우:

서브도메인의 경우: