문서 검토 앱
만약 GitLab 팀원이고 여러분의 병합 요청에 문서 변경 내용이 포함되어 있다면, GitLab Docs site에 배포될 때 어떻게 보일지 미리보기할 수 있는 검토 앱을 사용할 수 있습니다.
다음 프로젝트에서 검토 앱이 활성화되어 있습니다:
대안으로, gitlab-docs 개발 가이드나 GDK 문서를 확인하여 로컬에서 문서를 렌더링하고 미리보기할 수 있습니다.
문서 검토 앱을 트리거하는 방법
만약 병합 요청에 문서 변경 내용이 있다면, review-docs-deploy 수동 잡을 사용하여 해당 병합 요청을 위해 문서 검토 앱을 배포하세요.
review-docs-deploy* 작업은 교차 프로젝트 파이프라인을 트리거하고 여러분의 변경 사항으로 문서 사이트를 빌드합니다. 파이프라인이 완료되면, 검토 앱 URL이 병합 요청 위젯에 나타납니다. 이를 사용하여 여러분의 변경 사항으로 이동하세요.
review-docs-cleanup 작업은 자동으로 병합을 수행합니다. 이 작업은 검토 앱을 삭제합니다.
여러분은 프로젝트에서 개발자 역할을 할당받아야 합니다. 개발자 역할이 없는 사용자, 즉 외부 기여자 등은 수동 작업을 실행할 수 없습니다. 이 경우 GitLab 팀의 누군가에게 작업을 실행해 달라고 요청하세요.
기술적 측면
자세한 내용을 알고 싶다면, 다음과 같은 일이 실제로 일어나고 있습니다:
- 여러분은 병합 요청에서
review-docs-deploy작업을 직접 실행합니다. - 이 작업은
scripts/trigger-build.rb스크립트를docs deploy플래그와 함께 다운로드하여 실행합니다. 이것은$DOCS_BRANCH(기본값은main)를 위한gitlab-org/gitlab-docs프로젝트에서의 “Triggered fromgitlab-org/gitlab‘review-docs-deploy’ job” 파이프라인을 트리거합니다. - 미리보기 URL은 작업 결과와 병합 요청 위젯에 모두 표시됩니다. 또한 원격 파이프라인에 대한 링크도 제공됩니다.
-
gitlab-org/gitlab-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` 브랜치를 사용하여 Review App을 배포합니다.
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 and DOCS_GITLAB_REPO_SUFFIX are CI variables
# Discussion: 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 지정된 키가 없음
리뷰 앱에서 다음 메시지를 보면, 사이트가 아직 배포되지 않았거나 gitlab-docs의 다운스트림 파이프라인에 문제가 있는 것입니다.
NoSuchKeyThe specified key does not exist.No such object: <URL>
이 경우, 다음을 할 수 있습니다:
- 잠시 기다렸다가 리뷰 앱이 온라인에 나타날 것입니다.
-
review-docs-deploy작업 로그를 확인하고 URL을 확인하세요. 병합 요청 UI에 표시된 URL이 작업 로그의 URL과 다르다면, 작업 로그의 URL을 시도해 보세요. - 병합 요청 작업 출력의 링크에서 원격 파이프라인의 상태를 확인하세요. 파이프라인이 실패하거나 멈춘 경우, GitLab 팀 멤버는
#docs내부 Slack 채널에서 도움을 요청할 수 있습니다. 기여자는 병합 요청에서 기술 작가에게 문의할 수 있습니다.
도움말