문서 배포

배포 환경

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

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

릴리스 프로세스의 부분

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

  • main 및 관련 stable 브랜치에 변경사항을 적용하기 위한 병합 요청.
  • 관련 stable 브랜치에 대해 Docker 이미지를 빌드하고 배포하기 위한 파이프라인.
  • 안정적인 버전 및 최신 문서를 포함하여 온라인 문서 모두를 빌드하고 배포하는 Docker 이미지.

문서 배포는 다음과 같은 파이프라인 및 Docker 이미지에 의존합니다:

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

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

안정적인 브랜치

문서 프로젝트의 안정적인 브랜치에 대한 파이프라인은 포함된 프로젝트의 관련 stable 브랜치를 사용합니다. 예를 들어, 안정 버전 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의 stable 브랜치를 대상으로 병합 요청이 병합되면 해당 안정적인 문서를 빌드하고 레지스트리에 배포합니다. 예를 들어:

특히, 각 파이프라인의 image:docs-single job은 자동으로 실행됩니다. 빌드된 내용을 가져와 container registry에 푸시합니다.

graph TD A["14.4 MR merged"] B["14.3 MR merged"] C["14.2 MR merged"] D["13.12 MR merged"] E["12.10 MR merged"] 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 브랜치에 이후 병합된 변경 사항을 안정 버전 14.4 Docker 이미지에 다시 빌드함.
  • gitlab-docs 프로젝트 자체에서 안정 브랜치에 대한 변경 사항을 포함하기 위함. 예를 들어:

최신 문서

우리는 다음을 포함하는 도커 이미지(태그가 latest로 표시됨)를 빌드합니다:

  • 온라인 최신 버전의 문서.
  • 상위 프로젝트의 안정적인 브랜치에서의 문서.

image:docs-latest 작업:

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

예를 들어, image:docs-latest 작업을 포함하는 파이프라인:

graph TD A["Latest gitlab, gitlab-runner<br>omnibus-gitlab, and charts"] subgraph "Container registry on gitlab-docs project" 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 job<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{{"Container registry on gitlab-docs project"}} G--"최신 gitlab-docs:latest 이미지<br>올림"-->H

페이지 배포 작업

GitLab Docs는 페이지 사이트이며 업데이트된 문서는 배포되어야 합니다.

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

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

예를 들어, 파이프라인에 있는 pages 작업.

graph LR A{{"Container registry on gitlab-docs project"}} B[["예약된 파이프라인<br>`pages`와<br>`pages:deploy` job"]] C([docs.gitlab.com]) A--"gitlab-docs:latest<br>다운로드됨"-->B B--"해제된 문서가 업로드됨"-->C

수동으로 프로덕션에 배포

문서 빌드 예약 파이프라인이 매 시간 실행될 때마다 GitLab Docs가 프로덕션에 배포됩니다. 기본적으로 이 파이프라인은 매 시간 실행됩니다.

유지보수자는 다음을 수행하여 프로덕션에 배포를 강제로 실행할 수 있습니다:

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

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

이 작업을 수행할 Maintainer 역할이 없는 경우, #docs Slack 채널에서 도움을 요청하세요.

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)

더 많은 정보는 내부 기술 문서 작성 팀 문서를 참조하고 Slack의 #docs 채널에서 기술 문서 팀 회원에게 도움을 요청하세요.