GitLab 릴리스 노트는 gitlab 리포지터리에 저장됩니다.

릴리스 노트는 릴리스마다 하나의 디렉터리로 정리되며, 각 디렉터리에는 index.md 파일과 기능별 개별 파일이 있습니다. 예를 들어 구조는 다음과 비슷합니다.

doc/
└─ releases/
   └─ 19/
     └─ gitlab-19-0-released/
     │  ├── index.md
     │  └── featureA-Beta.md
     └─ gitlab-19-1-released/
        ├── index.md
        ├── featureB.md
        └── featureA-GA.md

각 릴리스에서 기능 릴리스 노트의 MR과 파일 생성은 프로덕트 매니저가 담당합니다. 그 밖의 모든 디렉터리와 파일 생성은 테크니컬 라이팅 팀이 담당합니다.

기능 릴리스 노트 생성#

기능 릴리스 노트를 만드는 방법은 다음과 같습니다.

1. 해당 릴리스의 디렉터리를 확인합니다. /doc/releases/19/gitlab-19-1-released/와 비슷한 형태입니다.
2. 이 디렉터리에 기능 릴리스 노트용 Markdown 파일을 만듭니다. 파일 이름 자체는 중요하지 않지만, 나중에 알아볼 수 있는 이름으로 지으면 좋습니다.
3. 아래의 템플릿을 Markdown 파일에 붙여 넣습니다.
4. 필요에 맞게 메타데이터를 조정합니다.
   • 문서 링크는 상대 경로여야 합니다.
   • 작업 항목 링크가 비공개가 아닌지 확인합니다.
5. 메타데이터 다음에 릴리스 노트 본문을 작성합니다.
   • 125단어 이하로 작성하며 이미지나 동영상은 넣지 않습니다.
   • 문서 링크는 허용되지만 상대 경로여야 합니다.
   • 다른 자료로 연결되는 링크도 허용됩니다.
6. 머지 리퀘스트를 만듭니다.
   • Release Notes Item 템플릿으로 설명을 채우고 진행 상황을 추적합니다.
   • 검토를 위해 머지 리퀘스트를 Engineering Manager와 테크니컬 라이터에게 할당합니다.

기능 릴리스 노트 편집 또는 삭제#

기능 릴리스 노트를 수정하거나 완전히 삭제해야 한다면 요청한 변경 사항을 담은 머지 리퀘스트를 만들고, 검토를 위해 테크니컬 라이터에게 할당합니다.

기능 릴리스 노트를 삭제할 때는 해당 파일만 삭제하면 됩니다. 다른 파일은 조정할 필요가 없습니다.

카테고리 검증 건너뛰기#

머지 리퀘스트가 릴리스 노트를 변경하면 docs-lint release-note-categories CI/CD job이 categories 값을 categories.yml과 대조해 검증합니다. 카테고리는 이름이 바뀌거나 삭제되기도 하므로 오래된 릴리스 노트가 더 이상 존재하지 않는 카테고리를 사용해 job이 실패할 수 있습니다.

이 검증을 건너뛰려면 머지 리퀘스트에 pipeline:skip-release-note-categories 레이블을 추가합니다.

주목할 만한 기여자 추가#

Developer Relations는 릴리스마다 주목할 만한 기여자에 대한 몇 문장을 추가하는 머지 리퀘스트를 만듭니다. 이 내용은 마이너 릴리스 인덱스 파일에 추가해야 합니다. 예를 들면 doc/releases/19/gitlab-19-1-released/index.md입니다.

기존 도입 문구 다음에 아래 템플릿을 사용합니다.

## Notable contributor

We are excited to recognize [Name](https://gitlab.com/<username>)
as this month's [Notable Contributor](https://contributors.gitlab.com/notable-contributors)! ...

이 머지 리퀘스트는 릴리스 전 언제든 병합할 수 있지만, 작성자에게 확인해 볼 수도 있습니다.

기능 릴리스 노트 검토#

머지 리퀘스트가 생성되면 테크니컬 라이터가 메타데이터와 본문 텍스트를 검토해야 합니다. 이 과정은 다른 문서 변경과 비슷합니다.

릴리스 노트 게시#

릴리스 당일, 해당 릴리스를 맡은 테크니컬 라이터는 머지 리퀘스트 세 건을 만듭니다.

1. gitlab에서 현재 릴리스의 콘텐츠를 업데이트하고 다음 릴리스의 콘텐츠를 생성합니다. 릴리스 당일 전에 수행할 수 있습니다.
2. docs-gitlab-com에서 현재 릴리스를 내비게이션에 추가합니다. 릴리스 당일 전에 수행할 수 있습니다.
3. 가장 최근 스테이블 브랜치로 릴리스 노트를 백포트합니다. 예를 들어 19.1을 릴리스한다면 스테이블 브랜치는 19-1-stable-ee입니다. 반드시 릴리스 당일에 수행해야 합니다.

현재 릴리스의 콘텐츠 업데이트#

게시 과정의 일부로 마이너 릴리스 인덱스 파일을 업데이트해야 합니다.

현재 릴리스의 콘텐츠를 업데이트하는 방법은 다음과 같습니다.

1. 마이너 릴리스 인덱스 파일을 엽니다. 예를 들면 doc/releases/19/gitlab-19-0-released/index.md입니다.

2. 메타데이터에서 group 다음에 릴리스 날짜를 추가합니다. 예를 들면 다음과 같습니다.

   date: 2026-05-21
   

   이 항목을 추가하면 릴리스 날짜가 될 때까지 파이프라인이 실패합니다. 이 실패는 예상된 동작입니다.

3. description 메타데이터를 업데이트합니다.

   # Original
   description: Summary of features included in <version>
   
   # New
   description: GitLab <version> released with <top feature title>
   

   버전과 대표 기능 제목을 해당 정보로 바꿉니다.

4. title 메타데이터를 업데이트합니다.

   # Original
   title: GitLab <version> (Upcoming release)
   
   # New
   title: GitLab <version>
   

5. 도입 문구를 업데이트합니다.

   # Original
   The following features are being delivered for GitLab <version>.
   These features are now available on GitLab.com.
   
   # New
   On <release date>, GitLab <version> was released with the following features.
   

   날짜와 버전을 해당 정보로 바꿉니다.

다음 릴리스의 콘텐츠 생성#

게시 과정의 일부로 다음 릴리스의 디렉터리와 콘텐츠를 만들어야 합니다. 예를 들어 19.1을 게시할 때는 19.2의 디렉터리와 인덱스 파일을 만듭니다.

다음 릴리스의 콘텐츠를 만드는 방법은 다음과 같습니다.

1. /doc/releases/에서 메이저 버전 디렉터리를 확인합니다. 예를 들면 /doc/releases/19/입니다.

2. 다음 버전의 콘텐츠를 만듭니다.

   1. 다음 릴리스를 위한 새 디렉터리를 만듭니다. 예를 들면 19/gitlab-19-1-released/입니다.
   2. 새 디렉터리에 다음 릴리스를 위한 index.md 파일을 만듭니다. 예를 들면 19/gitlab-19-1-released/index.md입니다.
   3. 템플릿을 붙여 넣고 버전 번호를 업데이트합니다.

3. 메이저 버전 인덱스 페이지에 파일을 추가합니다.

   1. /doc/releases/의 메이저 버전 디렉터리로 이동합니다. 예를 들면 /doc/releases/19/입니다.
   2. _index.md에서 cards 쇼트코드가 다음 릴리스 파일을 참조하도록 업데이트합니다. 예를 들면 다음과 같습니다.

   
   
   - [GitLab 19.0](gitlab-19-0-released/index.md)
   - [GitLab 19.1](gitlab-19-1-released/index.md)
   
   
   

4. 다음 릴리스를 참조하도록 upcoming 리다이렉트 페이지를 업데이트합니다.

   1. doc/releases/upcoming.md에서 리다이렉트 메타데이터가 다음 릴리스 파일을 가리키도록 업데이트합니다. 예를 들면 다음과 같습니다.

      ---
      redirect_to: '19/gitlab-19-1-released/index.md'
      ---
      

5. 머지 리퀘스트를 만들고 검토를 위해 테크니컬 라이터에게 할당합니다.

현재 릴리스를 내비게이션에 추가#

docs-gitlab-com 리포지터리에서 data/en-us/navigation.yaml에 현재 릴리스를 추가합니다. 예를 들면 다음과 같습니다.

        - title: GitLab 19
          url: 'releases/19/'
          submenu:
            - title: GitLab 19.0
              url: 'releases/19/gitlab-19-0-released/'
            - title: GitLab 19.1
              url: 'releases/19/gitlab-19-1-released/'

이제 커밋을 푸시할 수 있습니다. 이 머지 리퀘스트는 완료된 상태입니다.

최종 릴리스 노트 백포트#

릴리스 노트가 게시된 다음에는 백포트해야 합니다. 이 작업은 릴리스 당일에 수행하며 그 전에는 하지 않습니다.

gitlab 리포지터리의 최종 마감은 릴리스 전 금요일입니다. 사용자가 문서 사이트 오른쪽 위에서 버전을 선택하면 최종 노트를 볼 수 없습니다. 백포트하면 사용자가 새로 릴리스된 버전을 선택했을 때 노트가 최신 상태로 표시됩니다.

1. "스테이블 브랜치"를 체크아웃합니다. 예를 들어 19.1을 릴리스한다면 19-1-stable-ee를 체크아웃합니다.
2. gitlab 리포지터리에서 최신 릴리스 노트를 열고 파일 내용을 복사합니다.
3. 로컬 버전의 릴리스 노트 위에 복사한 내용을 붙여 넣습니다.
4. 머지 리퀘스트를 열고 Stable branch 템플릿을 선택해 설명을 채웁니다. 대상 브랜치를 스테이블 브랜치(19-1-stable-ee)로 변경합니다.
5. Maintainer에게 검토와 병합을 요청합니다.(다른 테크니컬 라이터여도 됩니다.) 브랜치가 아직 잠겨 있다면 #release-post 채널에 도움을 요청하거나, 브랜치를 병합할 수 있을 때까지 몇 시간 기다립니다.
6. 병합 후 새 파이프라인을 생성합니다. Run for branch name or tag에서 배포할 버전을 선택합니다. 이 예시에서는 19.1을 선택한 다음 New pipeline을 선택합니다.

릴리스 후 콘텐츠 업데이트#

릴리스 마감 이후에 릴리스 노트를 수정·추가·삭제하는 방법은 다음과 같습니다.

1. gitlab 리포지터리를 업데이트합니다.
   1. gitlab 리포지터리의 Markdown 파일을 수정하는 머지 리퀘스트를 엽니다.
   2. 변경 사항을 작성합니다.
   3. 테크니컬 라이터에게 검토와 병합을 요청합니다.
2. 변경 사항을 백포트합니다.
   1. 스테이블 브랜치를 체크아웃합니다. 예를 들어 19.0을 업데이트한다면 19-0-stable-ee를 체크아웃합니다.
   2. 이 브랜치에서 변경 사항을 작성합니다.
   3. 머지 리퀘스트를 열고 대상 브랜치를 스테이블 브랜치(19-0-stable-ee)로 설정합니다.
   4. Maintainer에게 검토와 병합을 요청합니다. 다른 테크니컬 라이터여도 됩니다.
   5. 병합 후 테크니컬 라이터가 docs-gitlab-com의 해당 스테이블 브랜치에 대해 새 파이프라인을 실행해야 합니다. Run for branch name or tag에서 배포할 버전을 선택합니다. 이 예시에서는 19.0을 선택한 다음 New pipeline을 선택합니다.
3. https://docs.gitlab.com에서 오른쪽 위의 버전을 선택해 노트가 정상적으로 업데이트되었는지 확인합니다.

구성#

릴리스 포스트에서 각 기능 릴리스 노트는 해당 노트에 정의된 stage 메타데이터를 기준으로 섹션에 묶입니다. 각 stage는 다음 섹션 중 하나에 매핑됩니다.

섹션은 표에 나열된 순서대로 표시되며 Primary features가 가장 먼저 옵니다. 매핑되지 않은 stage는 Scale and Deployments 섹션에 표시됩니다. Primary features 섹션에 기능을 추가하려면 level 메타데이터를 사용합니다. Co-created contributions 섹션에 기능을 추가하려면 co_create 메타데이터를 사용합니다.

각 섹션에서 기능 릴리스 노트는 제목의 알파벳순으로 나열됩니다. 이 순서를 재정의하려면 weight 메타데이터에 값을 지정하며, 숫자가 작을수록 앞에 옵니다.

일반적으로는 나중에 삽입할 여지를 두기 위해 10의 배수(10, 20, 30 등)를 사용하고, 반드시 맨 앞에 와야 하는 노트가 아니라면 한 자리 숫자는 사용하지 않습니다.

메타데이터#

마이너 릴리스 인덱스 메타데이터#

기능 릴리스 노트 메타데이터#

템플릿#

마이너 릴리스 인덱스#

---
title: "GitLab <version> (Upcoming release)"
description: "Summary of features included in <version>"
group: Monthly Release
stage: Release Notes
---

The following features are being delivered for GitLab <version>.
These features are now available on GitLab.com.

## Notable contributor

기능 릴리스 노트#

---
title:
tier: [ Free, Premium, Ultimate ]
offering: [ gitlab_com, self_managed, gitlab_dedicated, gitlab_dedicated_for_government ]
stage: application_security_testing
documentation_link: "../../../user/permissions/#groups"
work_item: https://gitlab.com/groups/gitlab-org/-/work_items/<work-item-number>
categories: [ System Access, Permissions ]
level: primary or secondary
weight: 50
---

The text of the feature release note.

Explain the value of this improvement with 125 words or fewer.
Use phrases that start with, "In previous versions of GitLab, you couldn't... Now you can..."