GitLab Pages 개발에 기여하기

요약

GitLab Pages를 구성하여 기능 개발에 기여하는 방법을 알아보세요. GitLab Pages는 각각의 GitLab Pages 사이트가 서브도메인을 통해 접근되므로 호스트명 또는 도메인이 필요합니다. 와일드카드 없이, hosts 파일 편집하기.

GitLab Pages를 구성하여 기능 개발에 기여하는 방법을 알아보세요.

GitLab Pages 호스트명 구성#

GitLab Pages는 각각의 GitLab Pages 사이트가 서브도메인을 통해 접근되므로 호스트명 또는 도메인이 필요합니다. GitLab Pages 호스트명을 설정할 수 있는 방법은 다음과 같습니다:

와일드카드 없이, hosts 파일 편집하기#

/etc/hosts는 와일드카드 호스트명을 지원하지 않으므로, GitLab Pages에 대한 항목 하나와 각 페이지 사이트에 대한 항목을 별도로 구성해야 합니다:

127.0.0.1 gdk.test           # GDK를 사용하는 경우
127.0.0.1 pages.gdk.test     # Pages 호스트
# 모든 네임스페이스/그룹/사용자는
# pages 호스트의 서브도메인으로 추가해야 합니다. 이는
# /etc/hosts가 와일드카드를 허용하지 않기 때문입니다
127.0.0.1 root.pages.gdk.test # root 페이지용

DNS 와일드카드 대안 사용하기#

/etc/hosts 파일을 편집하는 대신 DNS 와일드카드를 사용하려면 다음 중 하나를 사용할 수 있습니다:

GDK 없이 GitLab Pages 구성하기#

GitLab Pages 사이트의 루트에 다음과 같이 gitlab-pages.conf 파일을 생성합니다:

# 기본 포트는 3010이지만 다른 포트도 사용 가능합니다
listen-http=:3010

# 로컬 GitLab Pages 도메인
pages-domain=pages.gdk.test

# 페이지가 저장되는 디렉터리
pages-root=shared/pages

# 로그에 더 많은 정보 표시
log-verbose=true

더 많은 옵션을 보려면 internal/config/flags.go를 확인하거나 gitlab-pages --help를 실행하세요.

GitLab Pages 수동 실행#

코드를 변경한 경우 앱을 빌드하기 위해 make를 실행해야 합니다. 앱을 시작하기 전에 항상 먼저 실행하는 것이 좋습니다. 빌드가 빠르니 걱정하지 마세요!

make && ./gitlab-pages -config=gitlab-pages.conf

GDK를 사용하여 GitLab Pages 구성하기#

다음 단계에서 $GDK_ROOT는 GDK를 클론한 디렉터리입니다.

GDK 호스트명을 설정합니다.

gdk.yml에 GitLab Pages 호스트명을 추가합니다:

gitlab_pages:
  enabled: true         # GDK에서 GitLab Pages를 관리하도록 활성화
  port: 3010            # 기본 포트는 3010
  host: pages.gdk.test  # GitLab Pages 도메인
  auto_update: true     # gdk가 GitLab Pages git을 업데이트해야 하는 경우
  verbose: true         # 로그에 더 많은 정보 표시

GDK로 GitLab Pages 실행하기#

이 구성을 완료하면 GDK가 GitLab Pages 프로세스를 관리하며, 다음과 같은 명령으로 접근할 수 있습니다:

시작: gdk start gitlab-pages
중지: gdk stop gitlab-pages
재시작: gdk restart gitlab-pages
로그 확인: gdk tail gitlab-pages

GitLab Pages 수동 실행#

GDK 프로세스 관리와 독립적으로 앱을 빌드하고 시작할 수도 있습니다.

make && ./gitlab-pages -config=gitlab-pages.conf

FIPS 모드에서 GitLab Pages 빌드하기#

FIPS_MODE=1 make && ./gitlab-pages -config=gitlab-pages.conf

GitLab Pages 사이트 생성하기#

GitLab Pages 사이트를 로컬에서 빌드하려면 gitlab-runner 구성이 필요합니다.

자세한 내용은 사용자 매뉴얼을 참고하세요.

접근 제어 활성화하기#

GitLab Pages는 비공개 사이트를 지원합니다. 비공개 사이트는 해당 GitLab 프로젝트에 접근 권한이 있는 사용자만 접근할 수 있습니다.

GitLab Pages 접근 제어는 기본적으로 비활성화되어 있습니다. 활성화하려면 다음 단계를 따르세요:

GitLab 자체에서 GitLab Pages 접근 제어를 활성화합니다. 두 가지 방법이 있습니다:

GDK를 사용하지 않는 경우 gitlab.yml을 편집합니다:

# gitlab/config/gitlab.yml
pages:
  access_control: true

GDK를 사용하는 경우 gdk.yml을 편집합니다:

# $GDK_ROOT/gdk.yml
gitlab_pages:
  enabled: true
  access_control: true

GitLab을 재시작합니다(GDK로 실행 중인 경우 gdk restart를 실행합니다). gdk reconfigure를 실행하면 config/gitlab.yml의 access_control 값이 덮어써집니다.

로컬 GitLab 인스턴스의 브라우저에서 http://gdk.test:3000/admin/applications로 이동합니다.

api 스코프로 인스턴스 전체 OAuth 애플리케이션을 생성합니다.

redirect-uri 값을 pages-domain 인증 엔드포인트로 설정합니다 (예: http://pages.gdk.test:3010/auth). redirect-uri에는 GitLab Pages 사이트 도메인이 포함되어서는 안 됩니다.

인증 클라이언트 구성을 추가합니다:

GDK를 사용하는 경우, gdk.yml에서:

gitlab_pages:
  enabled: true
  access_control: true
  auth_client_id: $CLIENT_ID           # http://gdk.test:3000/admin/applications에서 생성한 OAuth 애플리케이션 ID
  auth_client_secret: $CLIENT_SECRET   # http://gdk.test:3000/admin/applications에서 생성한 OAuth 애플리케이션 시크릿

GDK는 무작위 auth_secret을 생성하고 GitLab Pages 호스트 구성을 기반으로 auth_redirect_uri를 빌드합니다.

GDK를 사용하지 않는 경우, gitlab-pages.conf에서:

## 다음은 비공개 프로젝트의 인증을 테스트하려는 경우에만 필요합니다
auth-client-id=$CLIENT_ID                         # http://gdk.test:3000/admin/applications에서 생성한 OAuth 애플리케이션 ID
auth-client-secret=$CLIENT_SECRET                 # http://gdk.test:3000/admin/applications에서 생성한 OAuth 애플리케이션 시크릿
auth-secret=$SOME_RANDOM_STRING                   # 최소 32바이트 이상이어야 합니다
auth-redirect-uri=http://pages.gdk.test:3010/auth # GitLab Pages의 인증 콜백 URL

GDK 내에서 Pages를 실행하는 경우 gdk.yml의 gdk 하위 protected_config_files 섹션을 사용하여 gitlab-pages.conf 구성이 덮어써지는 것을 방지할 수 있습니다:

gdk:
  protected_config_files:
  - 'gitlab-pages/gitlab-pages.conf'

오브젝트 스토리지 활성화하기#

GitLab Pages는 아티팩트 저장을 위한 오브젝트 스토리지 사용을 지원하지만, 오브젝트 스토리지는 기본적으로 비활성화되어 있습니다. GDK에서 활성화할 수 있습니다:

gdk.yml을 편집하여 GitLab 자체에서 오브젝트 스토리지를 활성화합니다:

# $GDK_ROOT/gdk.yml
object_store:
  enabled: true

gdk reconfigure 및 gdk restart 명령을 실행하여 GitLab을 재구성하고 재시작합니다.

자세한 내용은 GDK 문서를 참고하세요.

린팅#

# 로컬에서 린터 실행
make lint

# 린터 실행 및 문제 수정 (린터에서 지원하는 경우)
make format

테스트#

테스트를 실행하려면 다음 명령을 사용할 수 있습니다:

# 코드베이스의 모든 테스트를 실행합니다
make test

# 특정 테스트 파일 실행
go test ./internal/serving/disk/

# 파일의 특정 테스트 실행
go test ./internal/serving/disk/ -run TestDisk_ServeFileHTTP

# acceptance_test.go를 제외한 모든 단위 테스트 실행
go test ./... -short

# acceptance_test.go만 실행
make acceptance
# 특정 acceptance 테스트 실행
# 여기서 `make`를 추가하는 이유는 acceptance 테스트가 마지막으로 컴파일된 바이너리를 사용하므로
# 테스트되는 빌드에 최신 변경 사항이 포함되도록 하기 위함입니다
make && go test ./ -run TestRedirect

기여하기#

피처 플래그#

새로 도입되는 모든 피처 플래그는 기본적으로 비활성화되어야 합니다.

사소하지 않은 변경 사항에 대해서는 피처 플래그 추가를 고려하세요. 피처 플래그를 사용하면 이러한 변경 사항의 릴리스와 롤백이 더 쉬워지고, 인시던트와 다운타임을 방지할 수 있습니다. GitLab Pages에 새 피처 플래그를 추가하려면:

internal/feature/feature.go에 피처 플래그를 생성합니다. 기본값은 반드시 off여야 합니다.
Feature flag 템플릿을 사용하여 피처 플래그를 추적할 이슈를 생성합니다.
피처 플래그를 처리하는 머지 리퀘스트에 ~"feature flag" 라벨을 추가합니다.

GitLab Pages의 경우 피처 플래그는 전역 수준에서 환경 변수로 제어됩니다. 피처 플래그의 상태를 변경하려면 서비스 수준의 배포가 필요합니다. GitLab Pages 피처 플래그를 활성화하는 머지 리퀘스트 예시: GitLab Pages 속도 제한 적용

GitLab Pages 메인테이너 되기#

이 문서는 GitLab Pages 프로젝트의 메인테이너가 되고자 하는 GitLab 팀원을 위한 가이드라인입니다. 메인테이너는 GitLab Pages 코드베이스에 대한 고급 이해가 있어야 합니다. 프로젝트의 메인테이너를 신청하기 전에, 코드베이스에 대한 충분한 감각과 하나 이상의 기능에 대한 전문성, 그리고 코딩 표준에 대한 깊은 이해를 갖추어야 합니다.

기대 사항#

GitLab에서 메인테이너가 되는 프로세스는 핸드북에 정의되어 있으며, 이 프로세스의 기준이 됩니다. 기대되는 것 중 하나는 높은 수의 리뷰이지만, GitLab Rails 프로젝트에 비해 GitLab Pages의 변경 빈도는 너무 낮습니다.

이 문제를 해결하기 위해 코드베이스의 다음 영역에 익숙해져야 합니다:

주요 영역:

네임스페이스/프로젝트 해석
ZIP 서빙 및 가상 파일 시스템
인증

더 작은 영역:

리다이렉트
아티팩트 프록시
TLS 인증서 처리
속도 제한
메트릭 및 모니터링

이를 달성하기 위해, 위에서 언급한 모든 주요 영역과 2~3개의 더 작은 영역에서 관련 기여를 시도해야 기능에 대한 더 나은 이해를 얻을 수 있습니다. 관련 기여는 버그 수정, 성능 개선, 새 기능, 또는 중요한 리팩토링일 수 있습니다.

리뷰어#

메인테이너가 되기 전에 먼저 프로젝트의 리뷰어가 되어야 합니다. 여기에는 문서를 포함한 코드베이스의 어느 부분에 대한 변경도 포함됩니다.

리뷰어가 되려면 핸드북에 설명된 단계를 따르세요. 리뷰어로 활동해야 하는 기간에 대한 정해진 타임라인은 없지만, 이 문서의 기대 사항 섹션에서 언급된 영역에서 충분한 경험을 쌓아야 합니다.

메인테이너#

메인테이너가 되려면 핸드북에 설명된 단계를 따르세요. 다음 사항이 사실로 느껴질 때 메인테이너가 될 준비가 된 것입니다:

리뷰한 머지 리퀘스트가 메인테이너 리뷰를 통과할 때 중요한 추가 변경 요청 없이 일관되게 통과됩니다
생성한 머지 리퀘스트가 리뷰어 및 메인테이너 리뷰를 거칠 때 중요한 변경 요청 없이 일관되게 통과됩니다
운영 작업을 처리하는 데 익숙합니다

이러한 주관적 요건이 충족되면, MR을 열어 메인테이너로 승격을 요청하고 기존 메인테이너들을 태그하세요.

GitLab Pages 개발에 기여하기

GitLab v19.1

원문 보기

번역일: 2026-06-19

요약

GitLab Pages를 구성하여 기능 개발에 기여하는 방법을 알아보세요.

GitLab Pages 호스트명 구성#

와일드카드 없이, hosts 파일 편집하기#

/etc/hosts는 와일드카드 호스트명을 지원하지 않으므로, GitLab Pages에 대한 항목 하나와 각 페이지 사이트에 대한 항목을 별도로 구성해야 합니다:

127.0.0.1 gdk.test           # GDK를 사용하는 경우
127.0.0.1 pages.gdk.test     # Pages 호스트
# 모든 네임스페이스/그룹/사용자는
# pages 호스트의 서브도메인으로 추가해야 합니다. 이는
# /etc/hosts가 와일드카드를 허용하지 않기 때문입니다
127.0.0.1 root.pages.gdk.test # root 페이지용

DNS 와일드카드 대안 사용하기#

/etc/hosts 파일을 편집하는 대신 DNS 와일드카드를 사용하려면 다음 중 하나를 사용할 수 있습니다:

GDK 없이 GitLab Pages 구성하기#

GitLab Pages 사이트의 루트에 다음과 같이 gitlab-pages.conf 파일을 생성합니다:

# 기본 포트는 3010이지만 다른 포트도 사용 가능합니다
listen-http=:3010

# 로컬 GitLab Pages 도메인
pages-domain=pages.gdk.test

# 페이지가 저장되는 디렉터리
pages-root=shared/pages

# 로그에 더 많은 정보 표시
log-verbose=true

더 많은 옵션을 보려면 internal/config/flags.go를 확인하거나 gitlab-pages --help를 실행하세요.

GitLab Pages 수동 실행#

make && ./gitlab-pages -config=gitlab-pages.conf

GDK를 사용하여 GitLab Pages 구성하기#

다음 단계에서 $GDK_ROOT는 GDK를 클론한 디렉터리입니다.

GDK 호스트명을 설정합니다.

gdk.yml에 GitLab Pages 호스트명을 추가합니다:

gitlab_pages:
  enabled: true         # GDK에서 GitLab Pages를 관리하도록 활성화
  port: 3010            # 기본 포트는 3010
  host: pages.gdk.test  # GitLab Pages 도메인
  auto_update: true     # gdk가 GitLab Pages git을 업데이트해야 하는 경우
  verbose: true         # 로그에 더 많은 정보 표시

GDK로 GitLab Pages 실행하기#

이 구성을 완료하면 GDK가 GitLab Pages 프로세스를 관리하며, 다음과 같은 명령으로 접근할 수 있습니다:

시작: gdk start gitlab-pages
중지: gdk stop gitlab-pages
재시작: gdk restart gitlab-pages
로그 확인: gdk tail gitlab-pages

GitLab Pages 수동 실행#

GDK 프로세스 관리와 독립적으로 앱을 빌드하고 시작할 수도 있습니다.

make && ./gitlab-pages -config=gitlab-pages.conf

FIPS 모드에서 GitLab Pages 빌드하기#

FIPS_MODE=1 make && ./gitlab-pages -config=gitlab-pages.conf

GitLab Pages 사이트 생성하기#

GitLab Pages 사이트를 로컬에서 빌드하려면 gitlab-runner 구성이 필요합니다.

자세한 내용은 사용자 매뉴얼을 참고하세요.

접근 제어 활성화하기#

GitLab Pages는 비공개 사이트를 지원합니다. 비공개 사이트는 해당 GitLab 프로젝트에 접근 권한이 있는 사용자만 접근할 수 있습니다.

GitLab Pages 접근 제어는 기본적으로 비활성화되어 있습니다. 활성화하려면 다음 단계를 따르세요:

GitLab 자체에서 GitLab Pages 접근 제어를 활성화합니다. 두 가지 방법이 있습니다:

GDK를 사용하지 않는 경우 gitlab.yml을 편집합니다:

# gitlab/config/gitlab.yml
pages:
  access_control: true

GDK를 사용하는 경우 gdk.yml을 편집합니다:

# $GDK_ROOT/gdk.yml
gitlab_pages:
  enabled: true
  access_control: true

GitLab을 재시작합니다(GDK로 실행 중인 경우 gdk restart를 실행합니다). gdk reconfigure를 실행하면 config/gitlab.yml의 access_control 값이 덮어써집니다.

로컬 GitLab 인스턴스의 브라우저에서 http://gdk.test:3000/admin/applications로 이동합니다.

api 스코프로 인스턴스 전체 OAuth 애플리케이션을 생성합니다.

인증 클라이언트 구성을 추가합니다:

GDK를 사용하는 경우, gdk.yml에서:

gitlab_pages:
  enabled: true
  access_control: true
  auth_client_id: $CLIENT_ID           # http://gdk.test:3000/admin/applications에서 생성한 OAuth 애플리케이션 ID
  auth_client_secret: $CLIENT_SECRET   # http://gdk.test:3000/admin/applications에서 생성한 OAuth 애플리케이션 시크릿

GDK는 무작위 auth_secret을 생성하고 GitLab Pages 호스트 구성을 기반으로 auth_redirect_uri를 빌드합니다.

GDK를 사용하지 않는 경우, gitlab-pages.conf에서:

## 다음은 비공개 프로젝트의 인증을 테스트하려는 경우에만 필요합니다
auth-client-id=$CLIENT_ID                         # http://gdk.test:3000/admin/applications에서 생성한 OAuth 애플리케이션 ID
auth-client-secret=$CLIENT_SECRET                 # http://gdk.test:3000/admin/applications에서 생성한 OAuth 애플리케이션 시크릿
auth-secret=$SOME_RANDOM_STRING                   # 최소 32바이트 이상이어야 합니다
auth-redirect-uri=http://pages.gdk.test:3010/auth # GitLab Pages의 인증 콜백 URL

GDK 내에서 Pages를 실행하는 경우 gdk.yml의 gdk 하위 protected_config_files 섹션을 사용하여 gitlab-pages.conf 구성이 덮어써지는 것을 방지할 수 있습니다:

gdk:
  protected_config_files:
  - 'gitlab-pages/gitlab-pages.conf'

오브젝트 스토리지 활성화하기#

gdk.yml을 편집하여 GitLab 자체에서 오브젝트 스토리지를 활성화합니다:

# $GDK_ROOT/gdk.yml
object_store:
  enabled: true

gdk reconfigure 및 gdk restart 명령을 실행하여 GitLab을 재구성하고 재시작합니다.

자세한 내용은 GDK 문서를 참고하세요.

린팅#

# 로컬에서 린터 실행
make lint

# 린터 실행 및 문제 수정 (린터에서 지원하는 경우)
make format

테스트#

테스트를 실행하려면 다음 명령을 사용할 수 있습니다:

# 코드베이스의 모든 테스트를 실행합니다
make test

# 특정 테스트 파일 실행
go test ./internal/serving/disk/

# 파일의 특정 테스트 실행
go test ./internal/serving/disk/ -run TestDisk_ServeFileHTTP

# acceptance_test.go를 제외한 모든 단위 테스트 실행
go test ./... -short

# acceptance_test.go만 실행
make acceptance
# 특정 acceptance 테스트 실행
# 여기서 `make`를 추가하는 이유는 acceptance 테스트가 마지막으로 컴파일된 바이너리를 사용하므로
# 테스트되는 빌드에 최신 변경 사항이 포함되도록 하기 위함입니다
make && go test ./ -run TestRedirect

기여하기#

피처 플래그#

새로 도입되는 모든 피처 플래그는 기본적으로 비활성화되어야 합니다.

internal/feature/feature.go에 피처 플래그를 생성합니다. 기본값은 반드시 off여야 합니다.
Feature flag 템플릿을 사용하여 피처 플래그를 추적할 이슈를 생성합니다.
피처 플래그를 처리하는 머지 리퀘스트에 ~"feature flag" 라벨을 추가합니다.

GitLab Pages 메인테이너 되기#

기대 사항#

이 문제를 해결하기 위해 코드베이스의 다음 영역에 익숙해져야 합니다:

주요 영역:

네임스페이스/프로젝트 해석
ZIP 서빙 및 가상 파일 시스템
인증

더 작은 영역:

리다이렉트
아티팩트 프록시
TLS 인증서 처리
속도 제한
메트릭 및 모니터링

리뷰어#

메인테이너가 되기 전에 먼저 프로젝트의 리뷰어가 되어야 합니다. 여기에는 문서를 포함한 코드베이스의 어느 부분에 대한 변경도 포함됩니다.

메인테이너#

메인테이너가 되려면 핸드북에 설명된 단계를 따르세요. 다음 사항이 사실로 느껴질 때 메인테이너가 될 준비가 된 것입니다:

리뷰한 머지 리퀘스트가 메인테이너 리뷰를 통과할 때 중요한 추가 변경 요청 없이 일관되게 통과됩니다
생성한 머지 리퀘스트가 리뷰어 및 메인테이너 리뷰를 거칠 때 중요한 변경 요청 없이 일관되게 통과됩니다
운영 작업을 처리하는 데 익숙합니다

이러한 주관적 요건이 충족되면, MR을 열어 메인테이너로 승격을 요청하고 기존 메인테이너들을 태그하세요.

GitLab Pages 개발에 기여하기

GitLab Pages 호스트명 구성#

와일드카드 없이, hosts 파일 편집하기#

DNS 와일드카드 대안 사용하기#

GDK 없이 GitLab Pages 구성하기#

GitLab Pages 수동 실행#

GDK를 사용하여 GitLab Pages 구성하기#

GDK로 GitLab Pages 실행하기#

GitLab Pages 수동 실행#

FIPS 모드에서 GitLab Pages 빌드하기#

GitLab Pages 사이트 생성하기#

접근 제어 활성화하기#

오브젝트 스토리지 활성화하기#

린팅#

테스트#

기여하기#

피처 플래그#

관련 주제#

GitLab Pages 메인테이너 되기#

기대 사항#

리뷰어#

메인테이너#

GitLab Pages 개발에 기여하기

GitLab Pages 호스트명 구성#

와일드카드 없이, hosts 파일 편집하기#

DNS 와일드카드 대안 사용하기#

GDK 없이 GitLab Pages 구성하기#

GitLab Pages 수동 실행#

GDK를 사용하여 GitLab Pages 구성하기#

GDK로 GitLab Pages 실행하기#

GitLab Pages 수동 실행#

FIPS 모드에서 GitLab Pages 빌드하기#

GitLab Pages 사이트 생성하기#

접근 제어 활성화하기#

오브젝트 스토리지 활성화하기#

린팅#

테스트#

기여하기#

피처 플래그#

관련 주제#

GitLab Pages 메인테이너 되기#

기대 사항#

리뷰어#

메인테이너#