• 사용자 정의 도메인 설정
  • Prerequisites
  • 단계
    • 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 인증 추가

사용자 정의 도메인 설정

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

Prerequisites

• 관리자가 서버를 구성했으며 GitLab Pages 사용자 정의 도메인을 위해 설정했습니다.
• GitLab Pages 웹사이트가 기본 Pages 도메인(*.gitlab.io, GitLab.com의 경우) 하에 서비스 중이어야 합니다.
• example.com 또는 subdomain.example.com과 같은 사용자 정의 도메인 이름이 필요합니다.
• 도메인의 서버 제어판에 액세스하여 DNS 레코드를 설정할 수 있어야 합니다:
  • 도메인을 GitLab Pages 서버로 가리키는 DNS 레코드(A, ALIAS, 또는 CNAME)가 필요합니다. 해당 이름에 여러 DNS 레코드가 있는 경우 ALIAS 레코드를 사용해야 합니다.
  • 도메인 소유권을 확인하기 위한 DNS TXT 레코드가 필요합니다.

단계

사용자 정의 도메인을 Pages에 추가하려면 아래 단계를 따르세요. 또한 DNS 레코드 개요도 확인하세요.

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

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

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

2. 확인 코드 가져오기

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

3. DNS 레코드 설정

Pages용 DNS 레코드 개요를 확인하세요. 해당 주제에 익숙하다면, Pages 사이트에 사용할 도메인 유형에 따라 아래 지침을 따르세요.

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

당신이 Self-managed 인스턴스에서 IPv6를 구성할 수 있지만, 현재 GitLab.com의 Pages에는 IPv6가 구성되어 있지 않습니다. 상세 내용은 이 문제를 참조하세요.

루트 도메인에 대해

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

• 도메인을 Pages 서버로 가리키는 DNS A 레코드가 필요합니다.
• 도메인 소유권을 확인하기 위한 TXT 레코드가 필요합니다.

GitLab.com의 프로젝트의 경우, 이 IP는 35.185.44.232입니다. 다른 GitLab 인스턴스 (CE 또는 EE)에서 프로젝트를 사용하는 경우에는 이 정보를 얻기 위해 시스템 관리자에게 문의하세요 (인스턴스의 Pages 서버가 어떤 IP 주소에서 실행되고 있는지).

서브도메인에 대해

서브도메인(subdomain.example.com)을 사용하려면 다음이 필요합니다:

• DNS ALIAS 또는 CNAME 레코드를 사용하여 서브도메인을 Pages 서버로 연결합니다.
• 도메인 소유를 확인하는 DNS TXT 레코드가 필요합니다.

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

루트 도메인과 서브도메인에 대해

예를 들어 example.com과 www.example.com 같이 서브도메인과 루트 도메인을 동일한 웹사이트로 가리켜야 하는 몇 가지 경우에는 다음이 필요합니다:

• 도메인에 대한 DNS A 레코드가 필요합니다.
• 서브도메인에 대한 DNS ALIAS/CNAME 레코드가 필요합니다.
• 각각에 대해 DNS TXT 레코드가 필요합니다.

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

추가 정보:

• domain.com을 GitLab Pages 사이트로 가리키려면 A 레코드를 사용하고 CNAME 레코드를 사용하지 않습니다.
• 기본 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 인스턴스의 경우, 도메인이 7일 동안 확인되지 않으면 GitLab 프로젝트에서 제거됩니다.

추가 정보:

• 도메인 확인은 GitLab.com 사용자에게 필요합니다; GitLab self-managed 인스턴스의 경우 GitLab 관리자가 사용자 정의 도메인 확인을 비활성화할 수 있습니다.
• DNS 전파에는 시간이 소요될 수 있습니다(최대 24시간), 하지만 일반적으로 몇 분 정도 소요됩니다. 완료되기 전까지 확인이 실패하고 도메인을 방문하려는 시도는 404 오류가 발생합니다.
• 도메인이 확인된 후에는 확인 레코드를 그대로 두세요. 주기적으로 도메인이 재확인되며 레코드가 제거되면 비활성화될 수 있습니다.

추가 도메인 별칭 추가

동일한 프로젝트에 여러 별칭(사용자 정의 도메인 및 서브도메인)을 추가할 수 있습니다. 별칭은 동일한 방에 이어지는 많은 문이 있다고 생각할 수 있습니다.

설정 > 페이지에서 사이트에 설정한 모든 별칭을 확인할 수 있습니다. 해당 페이지에서 별칭을보거나 추가/제거할 수 있습니다.

Cloudflare를 사용하여 www.domain.com을 domain.com으로 리디렉션

Cloudflare를 사용하면 www를 domain.com으로 리디렉션할 수 있습니다. 이를 위해 www.domain.com과 domain.com을 GitLab에 모두 추가할 필요가 없습니다.

이를 수행하기 위해 Cloudflare의 페이지 규칙을 사용하여 CNAME 레코드에 www.domain.com을 domain.com으로 리디렉션할 수 있습니다. 다음 설정을 사용할 수 있습니다:

1. Cloudflare에서 DNS A 레코드를 생성하여 domain.com을 35.185.44.232로 지정합니다.
2. GitLab에서 도메인을 GitLab Pages에 추가하고 확인 코드를 받습니다.
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에 대한 HTTPS 강제 설정을 선택할 수 있습니다. 이렇게 하면 HTTP를 통해 웹사이트에 접근하는 모든 시도가 자동으로 301을 통해 HTTPS로 리디렉션됩니다.

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>"

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

루트 도메인의 경우:

하위 도메인의 경우: