문서 리뷰 앱
GitLab 팀원이라면 병합 요청에 문서 변경 사항이 포함되어 있는 경우, 리뷰 앱을 사용하여 GitLab Docs 사이트에 배포될 경우 어떻게 보일지 미리 볼 수 있습니다.
리뷰 앱은 다음 프로젝트에 대해 활성화되어 있습니다:
또는 gitlab-docs 개발 가이드
또는 GDK 문서를 확인하여
로컬에서 문서를 렌더링하고 미리 볼 수 있습니다.
리뷰 앱을 트리거하는 방법
병합 요청에 문서 변경 사항이 있는 경우, review-docs-deploy 수동 작업을 사용하여
병합 요청에 대한 문서 리뷰 앱을 배포하세요.
review-docs-deploy* 작업은 크로스 프로젝트 파이프라인을 트리거하고
변경 사항으로 docs 사이트를 빌드합니다. 파이프라인이 완료되면, 리뷰 앱 URL이
병합 요청 위젯에 표시됩니다. 앱을 사용하여 변경 사항으로 이동하세요.
review-docs-cleanup 작업은 병합 시 자동으로 트리거됩니다. 이 작업은 리뷰 앱을 삭제합니다.
프로젝트에 대한 개발자 역할이 있어야 합니다. 외부 기여자와 같은 개발자 역할이 없는 사용자는 수동 작업을 실행할 수 없습니다. 이 경우, GitLab 팀의 누군가에게 작업을 실행해 달라고 요청하세요.
기술적 측면
더 깊은 세부 정보를 알고 싶다면, 실제로 일어나는 일은 다음과 같습니다:
-
병합 요청에서 수동으로
review-docs-deploy작업을 실행합니다. -
이 작업은
scripts/trigger-build.rb스크립트를docs deploy플래그와 함께 다운로드하고 실행하며,$DOCS_BRANCH(기본값은main)에 대해gitlab-org/gitlab프로젝트의 “Triggered fromgitlab-org/gitlab‘review-docs-deploy’ job” 파이프라인 트리거를 발생시킵니다. -
미리 보기 URL은 작업 출력 및 병합 요청 위젯 모두에 표시됩니다. 원격 파이프라인에 대한 링크도 제공됩니다.
-
gitlab-org/gitlab-docs프로젝트에서 파이프라인이 생성되며, 대부분의 테스트 작업을 건너뜁니다 빌드 시간을 단축하기 위해서입니다. -
docs 사이트가 빌드된 후, HTML 파일은 원자산으로 GCP 버킷에 업로드됩니다 (구현 세부 사항은 이슈
gitlab-com/gl-infra/reliability#11021를 참조하세요).
다음은 사용되는 GitLab 기능입니다:
새 문서 리뷰 앱 추가 방법
문서 프로젝트 중 하나에 문서 리뷰 앱이 누락된 경우 다음 CI/CD 템플릿을 사용하여 수동으로 트리거된 리뷰 앱을 추가할 수 있습니다:
# 문서 리뷰 앱 설정
# https://docs.gitlab.com/ee/development/documentation/review_apps.html
.review-docs:
image: ruby:3.1-alpine
needs: []
before_script:
- gem install gitlab --no-doc
# 리뷰-문서 청소 작업은 브랜치가 삭제될 때 실행할 수 없기 때문에
# 레포를 클론하는 대신 스크립트를 다운로드해야 합니다. (MR을 병합할 때).
- apk add --update openssl
- wget https://gitlab.com/gitlab-org/gitlab/-/raw/master/scripts/trigger-build.rb
- chmod 755 trigger-build.rb
variables:
GIT_STRATEGY: none
DOCS_REVIEW_APPS_DOMAIN: docs.gitlab-review.app
# 기본적으로 `gitlab-org/gitlab-docs` 프로젝트의 `main` 브랜치를 사용하여 리뷰 앱 배포
DOCS_BRANCH: main
when: manual
allow_failure: true
# gitlab-docs에서 문서 빌드 트리거하기
# 문서 변경 사항을 실시간으로 미리 보는 데 유용
# https://docs.gitlab.com/ee/development/documentation/index.html#previewing-the-changes-live
review-docs-deploy:
extends:
- .review-docs
environment:
name: review-docs/mr-${CI_MERGE_REQUEST_IID}
# DOCS_REVIEW_APPS_DOMAIN 및 DOCS_GITLAB_REPO_SUFFIX는 CI 변수입니다
# 논의: https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/14236/diffs#note_40140693
auto_stop_in: 2 weeks
url: https://${DOCS_BRANCH}-${DOCS_GITLAB_REPO_SUFFIX}-${CI_MERGE_REQUEST_IID}.${DOCS_REVIEW_APPS_DOMAIN}/${DOCS_GITLAB_REPO_SUFFIX}
on_stop: review-docs-cleanup
script:
- ./trigger-build.rb docs deploy
# gitlab-docs의 원격 환경 청소
review-docs-cleanup:
extends:
- .review-docs
environment:
name: review-docs/mr-${CI_MERGE_REQUEST_IID}
action: stop
script:
- ./trigger-build.rb docs cleanup
작업이 실행될 때 몇 가지 규칙을 추가해야 할 수 있으며, 이는 프로젝트에 따라 다릅니다.
현재 구현을 찾을 수 있습니다:
리뷰 앱 문제 해결
NoSuchKey The specified key does not exist
리뷰 앱에서 다음 메시지가 표시되면 사이트가 아직 배포되지 않았거나
gitlab-docs의 다운스트림 파이프라인에 문제가 발생한 것입니다.
NoSuchKeyThe specified key does not exist.No such object: <URL>
이 경우, 다음을 수행할 수 있습니다:
- 몇 분 기다리면 리뷰 앱이 온라인에 나타납니다.
-
review-docs-deploy작업의 로그를 확인하고 URL을 검증합니다. 병합 요청 UI에 표시된 URL이 작업 로그의 URL과 다르면, 작업 로그의 URL을 사용해 보세요. - 병합 요청의 작업 출력 링크에서 원격 파이프라인의 상태를 확인합니다.
파이프라인이 실패했거나 정체된 경우, GitLab 팀 구성원은
#docs내부 Slack 채널에서 도움을 요청할 수 있습니다. 기여자는 기술 작가에게 병합 요청에서 연락할 수 있습니다.
도움말