문서 리뷰 앱
만약 GitLab 팀 구성원이며 Merge Request에 문서 변경이 포함되어 있다면, 문서 변경 내용을 미리보기할 수 있는 리뷰 앱을 사용할 수 있습니다. 그것들이 GitLab Docs site에 배포된다면 어떻게 보일지 미리 볼 수 있습니다.
리뷰 앱은 다음 프로젝트에서 활성화되어 있습니다.
또는, 로컬에서 문서를 변환하고 미리보려면, gitlab-docs 개발 가이드 또는 GDK 문서를 확인하세요.
리뷰 앱을 트리거하는 방법
Merge Request에 문서 변경이 있는 경우, review-docs-deploy 매뉴얼 작업을 사용하여 Merge Request에 대한 문서 리뷰 앱을 배포하세요.
review-docs-deploy* 작업은 교차 프로젝트 파이프라인을 트리거하고 변경 사항으로 문서 사이트를 빌드합니다. 파이프라인이 완료되면, 리뷰 앱 URL이 Merge Request 위젯에 표시됩니다. 변경 사항을 확인하는 데 사용하세요.
review-docs-cleanup 작업은 자동으로 Merge시에 트리거됩니다. 이 작업은 리뷰 앱을 삭제합니다.
이 프로젝트에서 개발자 역할이 있어야 합니다. 개발자 역할이 없는 사용자, 예를 들어 외부 기여자는 매뉴얼 작업을 실행할 수 없습니다. 그 경우 GitLab 팀의 누군가에게 작업을 실행해 달라고 요청하세요.
기술적 측면
자세한 내용을 알고 싶다면, 실제로 무엇이 일어나는지 여기에 있습니다:
- Merge Request에서
review-docs-deploy작업을 매뉴얼으로 실행합니다. - 작업은
scripts/trigger-build.rb스크립트를$DOCS_BRANCH(기본값은main)에 대해 트리거하는docs deploy플래그와 함께 다운로드하고 실행합니다. 이 스크립트는gitlab-org/gitlab-docs프로젝트에서 “Triggered fromgitlab-org/gitlab‘review-docs-deploy’ job” 파이프라인 트리거를 활성화합니다. - 미리보기 URL은 작업 출력 및 Merge Request 위젯에 표시됩니다. 또한 원격 파이프라인 링크를 받게 됩니다.
-
gitlab-org/gitlab-docs프로젝트에서 파이프라인이 만들어지며 대부분의 테스트 작업을 건너뛰도록 설정하여 빌드 시간을 줄입니다. - 문서 사이트가 빌드된 후, HTML 파일은 GCP 버킷으로 아티팩트로 업로드됩니다 (이슈
gitlab-com/gl-infra/reliability#11021에서 구현 세부사항 확인).
다음과 같은 기능을 사용합니다:
새로운 문서 리뷰 앱을 추가하는 방법
문서 프로젝트 중 하나에서 문서 리뷰 앱이 누락된 경우, 다음의 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을 Merge할 때 브랜치가 삭제되면 실행할 수 없을 것이기 때문에 레포를 클론하는 것보다 스크립트를 다운로드해야 합니다.
- 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
이러한 작업이 실행될 때 어떤 규칙을 추가해야 하는지는 프로젝트에 따라 다를 수 있습니다. 현재 구현 내용은 다음에서 찾을 수 있습니다:
Review App 문제 해결
NoSuchKey The specified key does not exist
만약 리뷰 앱에서 다음 메시지를 보게 된다면, 사이트가 아직 배포되지 않았거나 gitlab-docs의 다운스트림 파이프라인에 문제가 발생한 것입니다.
NoSuchKey The specified key does not exist. No such object: <URL>
이 경우, 다음을 할 수 있습니다:
- 잠시 기다렸다가 리뷰 앱이 온라인으로 표시될 때까지 기다립니다.
-
review-docs-deploy작업 로그를 확인하고 URL을 검증합니다. Merge Request UI에 표시된 URL이 작업 로그와 다르다면, 작업 로그에 나온 URL을 시도해 봅니다. - Merge Request의 작업 출력에서 링크된 원격 파이프라인의 상태를 확인합니다. 파이프라인이 실패했거나 멈춰있다면, GitLab 팀 멤버는
#docs내부 Slack 채널에서 도움을 요청할 수 있습니다. 기여자는 Merge Request에서 기술 문서 작성자에게 연락할 수 있습니다.
도움말