문서 검토 앱
만약 당신이 GitLab 팀 멤버이고 당신의 병합 요청에 문서 변경이 포함되어 있다면, GitLab Docs site에 배포된 것처럼 확인할 수 있는 검토 앱을 사용할 수 있습니다.
다음 프로젝트에서 검토 앱을 활성화할 수 있습니다:
또한, gitlab-docs 개발 가이드나 GDK 문서에서 로컬에서 문서를 렌더링하고 미리 볼 수 있습니다.
문서 검토 앱을 트리거하는 방법
만약 병합 요청에 문서 변경이 있다면, review-docs-deploy 수동 작업을 사용하여 병합 요청의 문서 검토 앱을 배포하세요.
review-docs-deploy* 작업은 cross 프로젝트 파이프라인을 트리거하고 여러분의 변경으로 docs site를 빌드합니다. 파이프라인이 완료되면, 검토 앱 URL이 병합 요청 위젯에 나타납니다. 앱을 사용하여 여러분의 변경 사항을 확인하세요.
review-docs-cleanup 작업은 병합 시 자동으로 트리거됩니다. 이 작업은 검토 앱을 삭제합니다.
프로젝트에 Developer 역할이 있어야 합니다. Developer 역할을 가지지 않은 사용자인 경우 외부 기여자 등은 수동 작업을 실행할 수 없습니다. 이 경우, GitLab 팀의 누군가에게 작업을 실행해달라고 요청하세요.
기술적 측면
더 깊이 들어가고 싶으시다면, 다음은 실제로 일어나는 일입니다:
- 병합 요청에서
review-docs-deploy작업을 수동으로 실행합니다. -
docs deploy플래그와 함께scripts/trigger-build.rb스크립트를 다운로드하고 실행하여,gitlab-org/gitlab-docs프로젝트에서 “$DOCS_BRANCH” (기본값은main)으로 “Triggered fromgitlab-org/gitlab‘review-docs-deploy’ job” 파이프라인 트리거를 발생시킵니다. - 미리 보기 URL은 작업 출력과 병합 요청 위젯에서 모두 표시됩니다. 또한 원격 파이프라인에 대한 링크도 제공받습니다.
-
gitlab-org/gitlab-docs프로젝트에서 파이프라인이 생성되고, 빌드 시간을 줄이기 위해 대부분의 테스트 작업을 건너뜁니다. - docs site가 빌드된 후, HTML 파일들이 Artifact로 업로드됩니다 (구현 세부 정보는
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을 병합할 때 브랜치가 삭제되면 review-docs-cleanup 작업이 실행되지 못하므로 레포를 클론하는 대신 스크립트를 다운로드해야 합니다.
- 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와 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을 확인합니다. MR UI에 표시된 URL이 작업 로그의 URL과 다르면 작업 로그의 URL을 시도해 보세요. - MR 작업 출력의 링크에서 원격 파이프라인 상태를 확인합니다. 파이프라인에 문제가 발생하거나 멈춰 있는 경우 GitLab 팀 멤버는
#docs내부 Slack 채널에서 도움을 요청할 수 있습니다. 기여자는 MR에서 기술 문서 작성자에게 ping을 보낼 수 있습니다.
도움말