• 사용자 정의 도메인 설정
  • 사전 요구 사항
  • 단계
    • 1. 사용자 정의 도메인 추가
    • 2. 확인 코드 가져오기
    • 3. DNS 레코드 설정
      • 루트 도메인
      • 서브도메인
      • 루트 및 서브도메인
    • 4. 도메인 소유권 확인
  • 추가 도메인 별칭 추가
  • Cloudflare를 사용하여 www.domain.com을 domain.com으로 리다이렉트
• 페이지에 SSL/TLS 인증서 추가
  • SSL/TLS 인증서 매뉴얼 추가
    • 단계
• GitLab Pages 웹사이트를 위한 HTTPS 강제
• 사용자 정의 도메인 편집
• 사용자 정의 도메인 삭제
• 문제 해결
  • 도메인 확인

GitLab Pages 사용자 정의 도메인

• GitLab 15.4에서 도메인 확인을 사용하여 SAML 또는 SCIM로 생성된 사용자의 이메일 확인을 우회할 수 있습니다.

사용자 정의 도메인을 사용할 수 있습니다:

• GitLab Pages와 함께
• SAML 또는 SCIM으로 생성된 사용자의 이메일 확인 우회. 이 방법으로 사용자 정의 도메인을 사용하면 GitLab Pages 기능을 사용하지만 사전 요구 사항을 건너뛸 수 있습니다.

하나 이상의 사용자 정의 도메인 이름을 사용하려면:

• 사용자 정의 루트 도메인 또는 하위 도메인을 추가하세요.
• SSL/TLS 인증서를 추가하세요.

사용자 정의 도메인 설정

사용자 정의 도메인명으로 페이지를 설정하려면 아래 요구 사항 및 단계를 확인하세요.

사전 요구 사항

• 관리자가 서버를 GitLab Pages 사용자 정의 도메인으로 구성했습니다.
• 기본 페이지 도메인(*.gitlab.io - GitLab.com)으로 제공되는 GitLab Pages 웹사이트가 작동 중입니다.
• 사용자 정의 도메인명 example.com 또는 하위 도메인 subdomain.example.com.
• DNS 레코드를 설정하기 위해 도메인의 서버 컨트롤 패널에 액세스할 수 있습니다.
  • 도메인을 GitLab Pages 서버로 가리키는 A, ALIAS, 또는 CNAME DNS 레코드. 해당 이름에 여러 DNS 레코드가 있는 경우 ALIAS 레코드를 사용해야 합니다.
  • 도메인 소유권을 확인하는 DNS TXT 레코드.

단계

사용자 지정 도메인을 페이지에 추가하려면 아래 단계를 따르세요. 또한 DNS 레코드 개요 문서를 참조하세요.

1. 사용자 정의 도메인 추가

GitLab Pages에 사용자 정의 도메인을 추가하려면:

1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
2. 배포 > Pages를 선택합니다.
3. 오른쪽 상단에서 새 도메인을 선택합니다.
4. 도메인에 도메인명을 입력합니다.
5. 옵션. 인증서에서 Let’s Encrypt를 사용한 자동 인증서 관리 토글을 끄고 SSL/TLS 인증서를 추가할 수 있습니다. 또는 인증서와 키를 나중에 추가할 수도 있습니다.
6. 새 도메인 만들기를 선택합니다.

2. 확인 코드 가져오기

새 도메인을 추가한 후 확인 코드가 나타납니다. GitLab에서 값을 복사하고 다음 단계에서 도메인의 제어판에 TXT 레코드로 붙여넣습니다.

3. DNS 레코드 설정

Pages용 DNS 레코드 개요 문서를 확인하시고 익숙하다면 페이지 사이트에서 사용할 도메인 유형에 따라 아래 지침을 따라주세요:

• 루트 도메인, example.com에 대해.
• 서브도메인, subdomain.example.com에 대해.
• 루트 및 서브도메인에 대해.

Self-Managed형 인스턴스에서 IPv6를 구성할 수 있습니다, 그러나 현재 GitLab.com의 페이지에는 IPv6가 구성되어 있지 않습니다. 자세한 내용은 이 문제를 참조하세요.

루트 도메인

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

• 도메인을 Pages 서버로 가리키는 DNS A 레코드.
• 도메인 소유권을 확인하는 TXT 레코드.

GitLab.com 프로젝트의 경우 이 IP는 35.185.44.232입니다. 다른 GitLab 인스턴스(CE 또는 EE)에 있는 프로젝트의 경우 시스템 관리자에게 이 정보(인스턴스에서 Pages 서버가 실행 중인 IP 주소)를 문의하세요.

서브도메인

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

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

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

루트 및 서브도메인

example.com 및 www.example.com과 같이 서브도메인과 루트 도메인을 동일한 웹사이트로 가리켜야 하는 몇 가지 경우가 있습니다.

다음이 필요합니다:

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

Cloudflare를 사용하는 경우 Cloudflare에서 www.domain.com을 domain.com으로 리디렉션하는지 확인하세요.

추가로:

• 귀하의 GitLab Pages 사이트에 domain.com을 가리키려면 CNAME 레코드 대신 A 레코드를 사용하지 마세요.
• 기본 Pages 도메인 뒤에 특수 문자를 추가하지 마세요. 예를 들어, subdomain.domain.com을 가리키거나 namespace.gitlab.io/를 가리키지 마세요. 일부 도메인 호스팅 제공업체는 가끔 뒤에 점(namespace.gitlab.io.)을 요청할 수 있습니다.
• GitLab.com의 GitLab Pages IP가 2017년에 변경되었습니다.
• GitLab.com의 GitLab Pages IP가 2018년에 변경되었습니다(52.167.214.135에서 35.185.44.232).

4. 도메인 소유권 확인

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

1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
2. 배포 > 페이지를 선택합니다.
3. 도메인 이름 옆에서 편집을 선택합니다.
4. 확인 상태에서 확인 재시도 ()를 선택합니다.

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

추가로: - 도메인 확인은 GitLab.com 사용자에게 필수입니다. GitLab Self-Managed형 인스턴스의 경우, GitLab 관리자가 사용자 정의 도메인 확인을 비활성화할 수 있습니다. - DNS 전파에는 시간이 소요될 수 있지만 일반적으로 몇 분이면 완료됩니다. 그 동안 확인이 실패하고 도메인을 방문하면 404 오류가 발생합니다. - 도메인 확인이 완료되면 확인 레코드를 그대로 두십시오. 도메인은 주기적으로 재확인되며 레코드가 제거되면 비활성화될 수 있습니다.

추가 도메인 별칭 추가

동일한 프로젝트에 여러 별칭(사용자 정의 도메인 및 서브도메인)을 추가할 수 있습니다. 별칭은 같은 방을 통해 여러 출입구가 있는 것으로 이해할 수 있습니다.

사이트에 설정한 모든 별칭은 설정 > 페이지에 나열됩니다. 해당 페이지에서 보기, 추가 및 삭제할 수 있습니다.

Cloudflare를 사용하여 www.domain.com을 domain.com으로 리다이렉트

Cloudflare를 사용하는 경우 www를 domain.com으로 리다이렉트할 수 있습니다. 이를 위해 www.domain.com 및 domain.com을 GitLab에 모두 추가할 필요는 없습니다.

다음과 같이 Cloudflare의 페이지 규칙을 사용하여 www.domain.com을 domain.com으로 리다이렉트할 수 있습니다.

1. Cloudflare에서 DNS A 레코드를 만들어 domain.com을 35.185.44.232로 지정합니다.
2. GitLab에서 도메인을 추가하고 확인 코드를 받습니다.
3. Cloudflare에서 도메인을 확인하도록 DNS TXT 레코드를 만듭니다.
4. GitLab에서 도메인을 확인합니다.
5. Cloudflare에서 DNS CNAME 레코드를 만들어 www를 domain.com으로 지정합니다.
6. Cloudflare에서 www.domain.com을 domain.com으로 지정하는 페이지 규칙을 추가합니다:
   • 도메인 대시보드로 이동하여 상단 네비게이션에서 페이지 규칙을 선택합니다.
   • 페이지 규칙 생성을 선택합니다.
   • 도메인 www.domain.com 입력하고 설정 추가를 선택합니다.
   • 드롭다운 디렉터리에서 전송 URL을 선택한 후 상태 코드 301 - 영구 리디렉션을 선택합니다.
   • 대상 URL https://domain.com을 입력합니다.

페이지에 SSL/TLS 인증서 추가

SSL/TLS 인증서에 대한 개요를 확인하려면 이 문서를 읽으세요.

GitLab Pages와 사용자 정의 도메인을 안전하게 보호하려면 다음 중 하나를 선택할 수 있습니다:

• GitLab Pages와 Let’s Encrypt 통합을 사용하여 SSL 인증서를 자동으로 획득하고 갱신합니다.
• 아래 단계를 따라 매뉴얼으로 GitLab Pages 웹사이트에 SSL/TLS 인증서를 추가합니다.

SSL/TLS 인증서 매뉴얼 추가

다음 요구 사항을 충족하는 인증서를 사용할 수 있습니다:

• 사용자 정의 도메인을 통해 접근할 수 있는 GitLab Pages 웹사이트가 실행 중이어야 합니다.
• PEM 인증서: CA에서 생성된 인증서로, 인증서 (PEM) 필드에 추가해야 합니다.
• 중간 인증서: (루트 인증서) CA를 식별하는 암호화 키 체인의 일부입니다. 보통 PEM 인증서와 결합되지만 매뉴얼으로 추가해야 할 때도 있습니다. Cloudflare 인증서는 이러한 경우 중 하나입니다.
• 개인 키: 도메인에 대한 PEM의 유효성을 검사하는 암호화된 키입니다.

예를 들어, Cloudflare 인증서가 이러한 요구 사항을 충족시킵니다.

단계

• 새 도메인을 추가하는 동안 인증서를 추가하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 배포 > 페이지를 선택합니다.
  3. 우측 상단에서 새 도메인을 선택합니다.
  4. 도메인에 도메인 이름을 입력합니다.
  5. 인증서에서 Let’s Encrypt를 사용한 자동 인증서 관리 토글을 사용하지 않도록 설정하여 SSL/TLS 인증서를 추가합니다.
  6. 새 도메인 만들기를 선택합니다.

• 이전에 추가된 도메인에 인증서를 추가하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 배포 > 페이지를 선택합니다.
  3. 도메인 이름 옆에서 편집을 선택합니다.
  4. 인증서에서 Let’s Encrypt를 사용한 자동 인증서 관리 토글을 사용하지 않도록 설정하여 SSL/TLS 인증서를 추가합니다.
  5. 변경 사항 저장을 선택합니다.

1. PEM 인증서를 해당 필드에 추가합니다.
2. 인증서에 중간 인증서가 누락된 경우, CA 웹사이트에서 일반적으로 사용 가능한 루트 인증서를 복사하여 PEM 인증서와 동일한 필드에 붙여 넣습니다.
3. 개인 키를 복사하여 마지막 필드에 붙여넣습니다.

일반 텍스트 편집기가 아닌 코드 편집기(Sublime Text, Dreamweaver, Brackets 등)를 사용하여 인증서 또는 암호화 키를 열지 마십시오.

GitLab Pages 웹사이트를 위한 HTTPS 강제

GitLab Pages의 웹사이트 방문자를 더 안전하게 만들기 위해 GitLab Pages에 HTTPS를 강제로 사용할 수 있습니다. 이렇게 하면 HTTP를 통한 웹사이트 방문 시 자동으로 HTTPS로 301 리디렉션이 이루어집니다.

GitLab 기본 도메인뿐만 아니라 유효한 인증서를 설정한 사용자 정의 도메인에서도 작동합니다.

이 설정을 활성화하려면:

1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
2. 배포 > 페이지를 선택합니다.
3. HTTPS 강제 (유효한 인증서가 필요함) 확인란을 선택합니다.
4. 변경 사항 저장을 선택합니다.

GitLab Pages 앞에 Cloudflare CDN를 사용하는 경우 SSL 연결 설정을 유연(flexible) 대신 완전(full)으로 설정해야 합니다. 자세한 내용은 Cloudflare CDN 지침을 참조하세요.

사용자 정의 도메인 편집

사용자 정의 도메인을 편집하여 다음을 수행할 수 있습니다:

• 사용자 정의 도메인 보기.
• 추가할 DNS 레코드 보기.
• TXT 확인 항목 보기.
• 확인 재시도.
• 인증서 설정 편집.

사용자 정의 도메인을 편집하려면:

1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
2. 배포 > 페이지를 선택합니다.
3. 도메인 이름 옆에서 편집을 선택합니다.

사용자 정의 도메인 삭제

사용자 정의 도메인을 삭제한 후에는 해당 도메인이 GitLab에서 더 이상 확인되지 않으며 GitLab Pages와 함께 사용할 수 없습니다.

사용자 정의 도메인을 삭제하려면 다음을 수행하세요:

1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
2. 배포 > 페이지를 선택합니다.
3. 도메인 이름 옆에서 제거를 선택합니다.
4. 프롬프트가 표시되면 도메인 제거를 선택합니다.

문제 해결

도메인 확인

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

dig _gitlab-pages-verification-code.<YOUR-PAGES-DOMAIN> TXT

아래와 같은 출력이 예상됩니다:

;; ANSWER SECTION:
_gitlab-pages-verification-code.<YOUR-PAGES-DOMAIN>. 300 IN TXT "gitlab-pages-verification-code=<YOUR-VERIFICATION-CODE>"

경우에 따라 등록하려는 도메인 이름과 동일한 도메인 이름으로 확인 코드를 추가하는 것이 도움이 될 수 있습니다.

루트 도메인의 경우:

서브도메인의 경우: