문서 검토 앱
만약 당신의 Merge Request이 문서 변경을 포함하고 있다면, GitLab 팀 구성원은 리뷰 앱을 사용하여 그 변경 사항이 GitLab Docs 사이트에 배포될 경우 어떻게 보일지 미리 볼 수 있습니다.
리뷰 앱은 다음 프로젝트에서 활성화되어 있습니다:
다른 방법으로, 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 deploy플래그와 함께 다운로드하고 실행합니다. 이것은$DOCS_BRANCH(기본값은main)에 대해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에서 구현 세부 정보를 확인하세요).
다음과 같은 다른 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
# 우리는 review-docs-cleanup 작업이 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
이 작업들이 실행될 때 일부 규칙을 추가해야 할 수 있습니다. 이는 프로젝트에 따라 다릅니다. 현재 구현 사항을 찾을 수 있습니다:
리뷰 앱의 문제 해결
NoSuchKey 지정된 키가 없습니다
만약 리뷰 앱에서 다음 메시지를 본다면, 사이트가 아직 배포되지 않았거나 gitlab-docs의 다운스트림 파이프라인에 문제가 있습니다.
NoSuchKeyThe specified key does not exist.No such object: <URL>
이 경우, 다음을 할 수 있습니다:
- 몇 분을 기다리면 리뷰 앱이 온라인에 표시됩니다.
-
review-docs-deploy작업 로그를 확인하고 URL을 검증하세요. Merge Request UI에 표시된 URL이 작업 로그의 것과 다르다면, 작업 로그의 것을 시도해보세요. - Merge Request의 작업 출력에 나타난 링크에서 원격 파이프라인의 상태를 확인하세요. 파이프라인이 실패하거나 멈춘 경우, GitLab 팀 구성원은
#docs내부 Slack 채널에서 도움을 요청할 수 있습니다. 기여자들은 Merge Request 내에서 기술 라이터에게 언급할 수 있습니다.
도움말