문서 배포

배포 환경

GitLab 문서 사이트는 GitLab Pages에 의해 호스팅되는 정적 사이트입니다. 배포는 Pages deploy job에 의해 수행됩니다.

웹사이트는 현재 지원되는 정책에 한해서만 문서를 호스팅합니다. 이전 버전에 대한 문서는 Docker 이미지로 빌드되어 GitLab Docs archives에서 다운로드할 수 있습니다.

릴리즈 프로세스의 부분

문서 릴리즈 프로세스에는 다음이 포함됩니다:

  • 변경 사항을 main 및 관련 안정적인 브랜치에 반영하기 위한 Merge Request
  • 안정적인 브랜치용 Docker 이미지를 빌드하고 배포하기 위한 파이프라인
  • 안정 버전 및 최신 문서를 포함하여 온라인 문서를 빌드하고 배포하는 데 사용되는 Docker 이미지

문서 배포에는 다음과 같은 의존성이 있습니다:

  • 최신 문서 파이프라인 및 이미지는 안정적인 문서 파이프라인 및 이미지에 의존합니다.
  • Pages 배포 파이프라인은 최신 문서 이미지에 의존합니다 (이때 안정적인 파이프라인 및 이미지에 의존됨).

CI/CD 파이프라인에서 Docker를 사용하는 일반 정보에 대해서는 Docker 통합을 참조하십시오.

안정적인 브랜치

문서 프로젝트의 안정적인 브랜치에 대한 파이프라인은 해당되는 프로젝트의 안정적인 브랜치를 가져옵니다. 예를 들어, 안정 버전 14.4의 문서는 gitlab-docs 프로젝트의 14.4 브랜치에서 빌드되며, 해당 브랜치는 다음을 포함합니다:

  • gitlab 프로젝트의 14-4-stable-ee 브랜치
  • gitlab-runner 프로젝트의 14-4-stable 브랜치
  • omnibus-gitlab 프로젝트의 14-4-stable 브랜치
  • charts/gitlab 프로젝트의 5-4-stable 브랜치 charts/gitlab 버전은 GitLab 버전에 매핑됩니다.

기술 문서 작성 팀은 다른 팀에 의해 생성된 안정적인 브랜치를 활용하는 gitlab-docs 프로젝트용 안정적인 브랜치를 생성합니다.

안정 버전 문서

gitlab-docs의 안정적인 브랜치를 대상으로 하는 Merge Request이 Merge되면, 해당 안정적인 문서가 빌드되어 레지스트리에 배포됩니다. 예를 들어:

특히 각 파이프라인의 image:docs-single 작업은 자동으로 실행됩니다. 빌드된 내용을 가져와 컨테이너 레지스트리에 푸시합니다.

graph TD A["14.4 MR Merge됨"] B["14.3 MR Merge됨"] C["14.2 MR Merge됨"] D["13.12 MR Merge됨"] E["12.10 MR Merge됨"] F{{"gitlab-docs 프로젝트의 컨테이너 레지스트리"}} A--"image:docs-single<br>작업 실행 및<br>gitlab-docs:14.4 이미지 푸시"-->F B--"image:docs-single<br>작업 실행 및<br>gitlab-docs:14.3 이미지 푸시"-->F C--"image:docs-single<br>작업 실행 및<br>gitlab-docs:14.2 이미지 푸시"-->F D--"image:docs-single<br>작업 실행 및<br>gitlab-docs:13.12 이미지 푸시"-->F E--"image:docs-single<br>작업 실행 및<br>gitlab-docs:12.10 이미지 푸시"-->F

안정 버전 문서 이미지 재빌드

안정 버전 문서 이미지를 다시 빌드하려면 이미지의 안정적인 브랜치에 대한 새 파이프라인을 생성합니다. 이를 수행하는 이유는 다음과 같습니다:

  • 상위 안정 브랜치에서의 새 문서 변경 사항을 안정 버전 Docker 이미지에 포함하기 위해. 예를 들어, gitlab 프로젝트의 14-4-stable-ee 브랜치에 이후 Merge된 변경 사항을 받아들이는 14.4 Docker 이미지를 다시 빌드합니다.
  • gitlab-docs 프로젝트 자체에서 안정 브랜치에 대한 변경 사항을 통합하기 위해. 예를 들어:

최신 문서

우리는 최신 버전의 온라인 문서를 포함하고:

  • 상위 프로젝트의 안정적인 브랜치에서 문서
  • Docker 이미지를 빌드합니다. (latest로 태그됨)

image:docs-latest 작업:

  • 관련 상위 프로젝트의 기본 브랜치에서 최신 문서를 가져옵니다.
  • 이전에 image:docs-single 작업에 의해 빌드된 Docker 이미지를 가져옵니다.
  • 예약된 파이프라인에서 매뉴얼으로 실행해야 합니다.

예를 들어, 파이프라인에는 image:docs-latest 작업이 포함됩니다.

graph TD A["최신 gitlab, gitlab-runner<br>omnibus-gitlab, 및 charts"] subgraph "gitlab-docs 프로젝트의 컨테이너 레지스트리" B["14.4 버전화된 문서<br>gitlab-docs:14.4"] C["14.3 버전화된 문서<br>gitlab-docs:14.3"] D["14.2 버전화된 문서<br>gitlab-docs:14.2"] E["13.12 버전화된 문서<br>gitlab-docs:13.12"] F["12.10 버전화된 문서<br>gitlab-docs:12.10"] end G[["예약된 파이프라인<br>image:docs-latest 작업<br>이들을 결합"]] A--"기본 브랜치에서<br>다운로드됨"-->G B--"gitlab-docs:14.4 이미지에서<br>다운로드됨"-->G C--"gitlab-docs:14.3 이미지에서<br>다운로드됨"-->G D--"gitlab-docs:14.2 이미지에서<br>다운로드됨"-->G E--"gitlab-docs:13.12 이미지에서<br>다운로드됨"-->G F--"gitlab-docs:12.10 이미지에서<br>다운로드됨"-->G H{{"gitlab-docs 프로젝트의 컨테이너 레지스트리"}} G--"최신 gitlab-docs:latest 이미지<br>푸시됨"-->H

페이지 배포 작업

GitLab Docs는 페이지 사이트이며 사용 가능하도록 문서 업데이트가 배포되어야 합니다.

pages 작업은 파이프라인이 기본 브랜치(main)에서 실행될 때 자동으로 실행됩니다. 필요한 명령을 실행하여 다음을 결합합니다.

  • gitlab-docs 사이트 코드의 매우 최신 빌드입니다.
  • 상위 프로젝트의 기본 브랜치의 최신 문서입니다.
  • image:docs-latest의 문서입니다.

예를 들어, 파이프라인에는 pages 작업이 포함되어 있습니다.

graph LR A{{"gitlab-docs 프로젝트의 컨테이너 레지스트리"}} B[["예약된 파이프라인<br>`pages`와<br>`pages:deploy` 작업"]] C([docs.gitlab.com]) A--"gitlab-docs:latest<br>풀됨"-->B B--"해제된 문서 업로드됨"-->C

매뉴얼으로 본 프로덕션 배포

Build docs.gitlab.com every hour 예약 파이프라인이 실행될 때마다 GitLab Docs가 프로덕션으로 배포됩니다. 기본적으로 이 파이프라인은 매 시간 실행됩니다.

유지 관리자는 이 파이프라인을 강제로 실행하여 프로덕션으로 배포하게 할 수 있습니다:

  1. gitlab-docs에 대한 예약된 파이프라인으로 이동합니다.
  2. Build docs.gitlab.com every hour 옆에서 실행 ()을 선택합니다.

새로 업데이트된 문서는 새로운 파이프라인에서 pages 및 pages:deploy 작업이 완료된 후 프로덕션에서 사용할 수 있습니다.

이 작업을 수행할 유지 관리자 권한이 없는 경우 #docs 슬랙 채널에서 도움을 요청하세요.

Docker 파일

dockerfiles 디렉터리에는 https://docs.gitlab.com를 빌드, 테스트 및 배포하는 데 필요한 Dockerfile이 포함되어 있습니다.

문제 해결

@gitlab-org/gitlab-svg에 알려진 아이콘이 아님

UI 또는 문서에서 아이콘을 사용하려고 시도하고 docs-lint links 작업에서 이 오류를 받으면 html-lint 도커 이미지를 업데이트해야 합니다. 

ArgumentError: example-image is not a known icon in @gitlab-org/gitlab-svg
926lib/helpers/icons_helper.rb:22:in `icon':
example-image is not a known icon in @gitlab-org/gitlab-svg (ArgumentError)

더 많은 정보는 내부 기술 문서 팀 문서를 참조하거나 #docs 채널에서 기술 문서 팀의 멤버에게 도움을 요청하세요.