GitLab Pages Let’s Encrypt 인증서

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

GitLab Pages와 Let’s Encrypt (LE)의 통합을 통해 커스텀 도메인에 대한 LE 인증서를 사용할 수 있습니다. LE 인증서를 사용하면 자체적으로 인증서를 발급하고 업데이트할 필요 없이 GitLab이 기본 제공합니다.

Let’s Encrypt는 무료이고 자동화되며 오픈 소스인 인증 기관입니다.

caution
이 기능은 커스텀 도메인에 대한 인증서만 다룹니다. Pages 데몬 (Self-Managed, Free, Premium, Ultimate only)을 실행하는 데 필요한 와일드카드 인증서는 다루지 않습니다. 와일드카드 인증서 생성은 이 이슈에서 추적됩니다.

전제 조건

도메인에 대한 SSL 인증서의 자동 프로비저닝을 사용하려면 다음을 준비해야 합니다:

  • GitLab에 웹사이트의 소스 코드를 포함한 프로젝트를 생성했는지 확인합니다.
  • 도메인(example.com)을 확보하고 DNS 항목을 추가하여 해당 도메인을 Pages 웹사이트로 연결했는지 확인합니다. 최상위 도메인(.com)은 공개 접미어여야 합니다.
  • Pages 프로젝트에 도메인을 추가하고 소유권을 확인했는지 확인합니다.
  • 사용 중인 웹사이트가 커스텀 도메인을 통해 접근 가능한지 확인합니다.

GitLab과 Let’s Encrypt의 통합은 GitLab.com에서 활성화되어 있습니다. Self-Managed GitLab 인스턴스의 경우, 관리자가 이를 활성화했는지 확인합니다.

커스텀 도메인에 대한 Let’s Encrypt 통합 활성화

사전 요구 사항을 충족한 후 Let’s Encrypt 통합을 활성화합니다:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 배포 > Pages를 선택합니다.
  3. 도메인 이름 옆에서 편집을 선택합니다.
  4. Let’s Encrypt를 사용한 자동 인증서 관리 활성화 토글을 켭니다.

    Let's Encrypt 활성화

  5. 변경 사항 저장을 선택합니다.

활성화되면 GitLab은 LE 인증서를 획득하고 연결된 Pages 도메인에 추가합니다. GitLab은 자동으로 인증서를 갱신합니다.

참고:

  • 인증서 발급 및 Pages 구성 업데이트는 최대 1시간이 소요될 수 있습니다.
  • 도메인 설정에 이미 SSL 인증서가 있는 경우, Let’s Encrypt 인증서로 대체될 때까지 계속 작동합니다.

문제 해결

Let’s Encrypt 인증서 획득 중에 오류 발생

Let’s Encrypt 인증서 획득 중에 오류 발생 메시지를 받으면 먼저 프로젝트의 설정 > 일반 > 가시성에서 페이지 사이트를 “모두”로 설정했는지 확인합니다. 이렇게 하면 Let’s Encrypt 서버가 페이지 사이트에 액세스할 수 있습니다. 이 작업이 확인되면 다음 단계를 따라 인증서를 다시 획득해 볼 수 있습니다:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 배포 > Pages를 선택합니다.
  3. 도메인 이름 옆에서 편집을 선택합니다.
  4. 확인 상태에서 재시도 확인 ()를 선택합니다.
  5. 여전히 동일한 오류가 발생하는 경우:
    1. 도메인에는 CNAME 또는 A DNS 레코드가 하나만 설정되어 있는지 확인합니다.
    2. 도메인에 AAAA DNS 레코드가 없는지 확인합니다.
    3. 도메인이나 상위 도메인에 CAA DNS 레코드가 있는 경우, 여기에 letsencrypt.org이 포함되어 있는지 확인합니다.
    4. 도메인이 확인되었는지 확인합니다.
    5. 1단계로 돌아갑니다.

1시간 이상 Let’s Encrypt 인증서가 획득되지 않음

Let’s Encrypt 통합을 활성화했지만 1시간 이상 지나도 인증서가 없고 다음 메시지가 표시된 경우:

GitLab은 이 도메인에 대한 Let's Encrypt SSL 인증서를 획득 중입니다.
이 프로세스에는 시간이 걸릴 수 있습니다. 나중에 다시 시도하세요.

다음 단계를 따라 GitLab Pages를 위해 도메인을 다시 제거하고 추가해 보세요:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 배포 > Pages를 선택합니다.
  3. 도메인 이름 옆에서 제거를 선택합니다.
  4. Pages를 위해 도메인을 다시 추가하고 확인합니다.
  5. 도메인에 대한 Let’s Encrypt 통합을 활성화합니다.
  6. 여전히 동일한 오류가 발생하는 경우:
    1. 도메인에는 CNAME 또는 A DNS 레코드가 하나만 설정되어 있는지 확인합니다.
    2. 도메인에 AAAA DNS 레코드가 없는지 확인합니다.
    3. 도메인이나 상위 도메인에 CAA DNS 레코드가 있는 경우, 여기에 letsencrypt.org이 포함되어 있는지 확인합니다.
    4. 1단계로 돌아갑니다.