기능 개발에 참여할 수 있도록 GitLab Pages를 설정하는 방법을 설명합니다.

GitLab Pages 호스트명 설정#

GitLab Pages 사이트는 각각 서브도메인으로 접근하므로 호스트명이나 도메인이 필요합니다. GitLab Pages 호스트명은 다음 방법으로 설정할 수 있습니다.

• 와일드카드 없이 hosts 파일을 편집하는 방법.
• DNS 와일드카드 대안을 사용하는 방법.

와일드카드 없이 hosts 파일 편집#

/etc/hosts는 와일드카드 호스트명을 지원하지 않으므로 GitLab Pages 용 항목 하나와 각 Pages 사이트용 항목을 각각 설정해야 합니다.

127.0.0.1 gdk.test           # If you're using GDK
127.0.0.1 pages.gdk.test     # Pages host
# Any namespace/group/user needs to be added
# as a subdomain to the pages host. This is because
# /etc/hosts doesn't accept wildcards
127.0.0.1 root.pages.gdk.test # for the root pages

DNS 와일드카드 대안 사용#

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

• nip.io
• dnsmasq

GDK 없이 GitLab Pages 설정#

GitLab Pages 사이트 루트에 다음과 같은 gitlab-pages.conf를 만듭니다.

# Default port is 3010, but you can use any other
listen-http=:3010

# Your local GitLab Pages domain
pages-domain=pages.gdk.test

# Directory where the pages are stored
pages-root=shared/pages

# Show more information in the logs
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를 클론한 디렉터리입니다.

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

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

   gitlab_pages:
     enabled: true         # enable GitLab Pages to be managed by gdk
     port: 3010            # default port is 3010
     host: pages.gdk.test  # the GitLab Pages domain
     auto_update: true     # if gdk must update GitLab Pages git
     verbose: true         # show more information in the logs
   

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를 실행해 앱을 빌드해야 합니다. 앱을 시작하기 전에 항상 실행하는 편이 좋습니다. 빌드는 빠르게 끝납니다.

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 액세스 제어는 기본적으로 비활성화돼 있습니다. 활성화하는 방법은 다음과 같습니다.

1. 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
     

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

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

4. api 스코프를 가진 인스턴스 전역 OAuth 애플리케이션을 생성합니다.

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

6. 인증 클라이언트 설정을 추가합니다.

   • GDK를 사용하는 경우 gdk.yml에 추가합니다.

     gitlab_pages:
       enabled: true
       access_control: true
       auth_client_id: $CLIENT_ID           # the OAuth application id created in http://gdk.test:3000/admin/applications
       auth_client_secret: $CLIENT_SECRET   # the OAuth application secret created in http://gdk.test:3000/admin/applications
     

     GDK는 무작위 auth_secret을 생성하고 GitLab Pages 호스트 설정을 바탕으로 auth_redirect_uri를 만듭니다.

   • GDK를 사용하지 않는 경우 gitlab-pages.conf에 추가합니다.

     ## the following are only needed if you want to test auth for private projects
     auth-client-id=$CLIENT_ID                         # the OAuth application id created in http://gdk.test:3000/admin/applications
     auth-client-secret=$CLIENT_SECRET                 # the OAuth application secret created in http://gdk.test:3000/admin/applications
     auth-secret=$SOME_RANDOM_STRING                   # should be at least 32 bytes long
     auth-redirect-uri=http://pages.gdk.test:3010/auth # the authentication callback url for GitLab Pages
     

7. GDK 안에서 Pages를 실행하는 경우, gitlab-pages.conf 설정이 덮어써지지 않도록 gdk.yml의 gdk 아래 protected_config_files 섹션을 사용할 수 있습니다.

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

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

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

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

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

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

자세한 내용은 GDK 문서를 참고합니다.

린팅#

# Run the linter locally
make lint

# Run linter and fix issues (if supported by the linter)
make format

테스트#

테스트는 다음 명령으로 실행할 수 있습니다.

# This will run all of the tests in the codebase
make test

# Run a specific test file
go test ./internal/serving/disk/

# Run a specific test in a file
go test ./internal/serving/disk/ -run TestDisk_ServeFileHTTP

# Run all unit tests except acceptance_test.go
go test ./... -short

# Run acceptance_test.go only
make acceptance
# Run specific acceptance tests
# We add `make` here because acceptance tests use the last binary that was compiled,
# so we want to have the latest changes in the build that is tested
make && go test ./ -run TestRedirect

기여#

기능 플래그#

사소하지 않은 변경에는 기능 플래그 추가를 검토합니다. 기능 플래그를 쓰면 변경의 릴리스와 롤백이 쉬워져 장애와 다운타임을 피할 수 있습니다. GitLab Pages에 새 기능 플래그를 추가하는 방법은 다음과 같습니다.

1. 기능 플래그를 internal/feature/feature.go 에 만들며, 기본값은 꺼진 상태여야 합니다.
2. Feature flag 템플릿으로 기능 플래그를 추적할 이슈를 생성합니다.
3. 기능 플래그를 다루는 모든 머지 리퀘스트에 ~"feature flag" 레이블을 추가합니다.

GitLab Pages에서 기능 플래그는 전역 수준의 환경 변수로 제어합니다. 기능 플래그 상태를 바꾸려면 서비스 수준의 배포가 필요합니다. GitLab Pages 기능 플래그를 활성화한 머지 리퀘스트 예시는 다음과 같습니다. Enforce GitLab Pages rate limits

관련 주제#

• GitLab 개발에서의 기능 플래그

GitLab Pages 메인테이너가 되는 방법#

이 문서는 GitLab Pages 프로젝트의 메인테이너가 되려는 GitLab 팀원을 위한 지침입니다. 메인테이너는 GitLab Pages 코드베이스를 깊이 이해하고 있어야 합니다. 프로젝트 메인테이너에 지원하기 전에 코드베이스에 충분히 익숙해지고, 하나 이상의 기능에 전문성을 갖추며, 코딩 표준을 깊이 이해해야 합니다.

기대 사항#

GitLab에서 메인테이너가 되는 절차는 핸드북에 정의돼 있으며, 이 절차의 기준선이 됩니다. 그중 하나로 많은 리뷰 건수가 기대되지만, GitLab Rails 프로젝트에 비하면 GitLab Pages의 변경 빈도는 매우 낮습니다.

이 문제를 보완하려면 코드베이스의 다음 영역에 익숙해야 합니다.

주요 영역:

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

그 밖의 영역:

• 리디렉션
• 아티팩트 프록시
• TLS 인증서 처리
• 속도 제한
• 메트릭과 모니터링

이를 위해 위에 언급한 주요 영역 전부와 그 밖의 영역 2~3곳에 관련 기여를 해 보면서 해당 기능을 더 깊이 이해하는 것이 좋습니다. 관련 기여로는 버그 수정, 성능 개선, 새 기능, 대규모 리팩터링 등이 있습니다.

리뷰어#

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

리뷰어가 되려면 핸드북에 정리된 절차를 따릅니다. 메인테이너가 되기 전 리뷰어로 얼마나 활동해야 하는지 정해진 기간은 없지만, 이 문서의 기대 사항 섹션에 언급된 영역에서 충분한 경험을 쌓아야 합니다.

메인테이너#

메인테이너가 되려면 핸드북에 정리된 절차를 따릅니다. 다음 항목이 모두 해당된다면 메인테이너가 될 준비가 된 것입니다.

• 리뷰한 MR 이 메인테이너 리뷰에서 추가 수정 요구 없이 꾸준히 통과합니다
• 작성한 MR 이 리뷰어와 메인테이너 리뷰에서 큰 수정 요구 없이 꾸준히 통과합니다
• 운영 작업을 수행하는 데 불편함이 없습니다

이러한 주관적 요건을 충족했다면 MR을 생성해 메인테이너로 승격을 요청하고 기존 메인테이너를 태그합니다.