변경 로그

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

변경 로그는 커밋 제목과 Git 트레일러를 바탕으로 생성됩니다. 변경 로그에 포함되려면 커밋은 특정 Git 트레일러를 포함해야 합니다. 변경 로그는 커밋 제목에서 생성되며, Git 트레일러 유형별로 분류됩니다. 추가 데이터로 병합 요청 링크나 커밋 작성자에 대한 세부 정보를 사용하여 변경 로그 항목을 풍부하게 할 수 있습니다. 변경 로그 형식은 사용자 정의할 수 있습니다 템플릿을 사용하여.

기본 변경 로그의 각 섹션에는 다음과 같은 버전 번호와 릴리스 날짜를 포함하는 제목이 있습니다:

## 1.0.0 (2021-01-05)

### Features (4 changes)

- [Feature 1](gitlab-org/gitlab@123abc) by @alice ([merge request](gitlab-org/gitlab!123))
- [Feature 2](gitlab-org/gitlab@456abc) ([merge request](gitlab-org/gitlab!456))
- [Feature 3](gitlab-org/gitlab@234abc) by @steve
- [Feature 4](gitlab-org/gitlab@456)

섹션의 날짜 형식은 사용자 정의할 수 있지만, 나머지 제목은 변경할 수 없습니다. 새로운 섹션을 추가할 때 GitLab은 이러한 제목을 구문 분석하여 파일에 새로운 정보를 추가할 위치를 결정합니다. GitLab은 버전 순서에 따라 섹션을 정렬하며, 날짜 순서는 따르지 않습니다.

각 섹션에는 카테고리별로 정렬된 변경 사항이 포함되어 있으며(예: Features), 이러한 섹션의 형식을 변경할 수 있습니다. 섹션 이름은 커밋을 포함하거나 제외하는 데 사용되는 Git 트레일러의 값에서 파생됩니다.

변경 로그를 위한 커밋은 미러에서 작업할 때 검색할 수 있습니다. GitLab 자체도 이 기능을 사용합니다. 패치 릴리스는 공개 프로젝트와 개인 보안 미러에서 모두 변경을 포함할 수 있기 때문입니다.

Git 커밋에 트레일러 추가하기

커밋 메시지를 작성할 때 트레일러를 수동으로 추가할 수 있습니다. 기본 트레일러인 Changelog를 사용하고 그것을 기능으로 분류하려면 커밋 메시지에 문자열 Changelog: feature를 추가하세요, 예를 들어:

<커밋 메시지 주제>

<커밋 메시지 설명>

Changelog: feature

변경 로그 생성하기

변경 로그는 명령 줄에서 API 또는 GitLab CLI를 사용하여 생성됩니다. 변경 로그 출력은 Markdown 형식으로 포맷되며, 사용자 정의할 수 있습니다.

API를 통한 생성

curl 명령을 사용하여 API로 변경 로그를 생성하려면 변경 로그 데이터를 변경 로그 파일에 추가하기에서 API 문서를 참조하세요.

GitLab CLI를 통한 생성

glab 버전 1.30.0에서 소개됨.

사전 요구 사항:

GitLab CLI를 설치하고 구성해야 하며, 버전 1.30.0 이상이어야 합니다.
리포지토리의 태그 명명 규칙은 예상 태그 명명 형식과 일치해야 합니다.
커밋에는 변경 로그 트레일러가 포함되어야 합니다.

변경 로그를 생성하려면:

git fetch로 리포지토리의 로컬 복사본을 업데이트합니다.
기본 옵션으로 현재 버전( git describe --tags로 결정됨)에 대한 변경 로그를 생성하려면:
- glab changelog generate 명령을 실행합니다.
- 출력을 파일로 저장하려면 glab changelog generate > <filename>.md 명령을 실행합니다.
사용자 정의 옵션으로 변경 로그를 생성하려면 glab changelog generate 명령을 실행하고 원하는 옵션을 추가합니다. 일부 옵션은 다음과 같습니다:
- --config-file [string]: 프로젝트의 Git 리포지토리에 있는 변경 로그 구성 파일의 경로입니다. 이 파일은 프로젝트의 Git 리포지토리에 존재해야 합니다. 기본값은 .gitlab/changelog_config.yml입니다.
- 커밋 범위:
  - --from [string]: 변경 로그 생성을 위해 사용할 커밋의 시작 범위(SHA). 이 커밋 자체는 변경 로그에 포함되지 않습니다.
  - --to [string]: 변경 로그 생성을 위해 사용할 커밋의 종료 범위(SHA). 이 커밋은 목록에 포함됩니다. 기본값은 기본 프로젝트 브랜치의 HEAD입니다.
- --date [string]: 릴리스의 날짜 및 시간, ISO 8601(2016-03-11T03:45:40Z) 형식입니다. 기본값은 현재 시간입니다.
- --trailer [string]: 커밋 포함에 사용할 Git 트레일러입니다. 기본값은 Changelog입니다.
- --version [string]: 변경 로그를 생성할 버전입니다.

GitLab CLI에서 사용할 수 있는 매개변수에 대해 자세히 알아보려면 glab changelog generate --help를 실행하세요. API 문서에서 정의 및 사용법을 확인하세요.

변경 로그 출력 사용자 정의

변경 로그 출력을 사용자 정의하려면 변경 로그 구성 파일을 편집하고 이러한 변경 사항을 프로젝트의 Git 리포지토리에 커밋합니다.

이 구성의 기본 위치는 .gitlab/changelog_config.yml입니다. 이 파일은 다음 변수를 지원합니다:

date_format: 새롭게 추가된 변경 로그 데이터의 제목에 사용되는 strftime 형식의 날짜 형식입니다.
template: 변경 로그 데이터를 생성할 때 사용할 사용자 정의 템플릿입니다.
include_groups: 프로젝트 멤버십에 관계없이 기여도를 인정받아야 하는 사용자를 포함하는 그룹 전체 경로 목록입니다. 변경 로그를 생성하는 사용자는 크레딧을 받기 위해 각 그룹에 대한 액세스 권한이 있어야 합니다.
categories: 원시 범주 이름을 변경 로그에서 사용할 이름에 매핑하는 해시입니다. 변경 로그에 표시되는 이름을 변경하려면 이러한 줄을 구성 파일에 추가하고 필요에 맞게 수정하세요. 이 예시는 범주 제목을 ### 기능, ### 버그 수정, 및 ### 성능 개선으로 렌더링합니다:
```
---
categories:
  feature: 기능
  bug: 버그 수정
  performance: 성능 개선
```

사용자 정의 템플릿

기본 템플릿이 변경됨 commit.reference와 merge_request.reference에서 commit.web_url과 merge_request.web_url로 GitLab 17.1에서.

범주 섹션은 템플릿을 사용하여 생성됩니다. 기본 템플릿:

{% if categories %}
{% each categories %}
### {{ title }} ({% if single_change %}1 change{% else %}{{ count }} changes{% end %})

{% each entries %}
- [{{ title }}]({{ commit.web_url }})\
{% if author.credit %} by {{ author.reference }}{% end %}\
{% if merge_request %} ([merge request]({{ merge_request.web_url }})){% end %}

{% end %}

{% end %}
{% else %}
변경 사항이 없습니다.
{% end %}

{% ... %} 태그는 명령문에 사용되며, {{ ... }}는 데이터를 출력하는 데 사용됩니다. 명령문은 {% end %} 태그로 종료되어야 합니다. if와 each 명령문 모두 단일 인수가 필요합니다.

예를 들어, valid라는 변수가 있을 때, 이 값이 참이면 “yes”를 표시하고, 그렇지 않으면 “nope”를 표시하려면 다음과 같이 합니다:

{% if valid %}
yes
{% else %}
nope
{% end %}

else의 사용은 선택 사항입니다. 값은 빈 값이 아니거나 불리언 true일 때 참으로 간주됩니다. 빈 배열과 해시는 거짓으로 간주됩니다.

반복은 each를 사용하여 수행되며, 루프 내의 변수는 해당 루프에 국한됩니다. 루프 내의 현재 값을 참조하는 것은 변수 태그 {{ it }}를 사용합니다. 다른 변수는 현재 루프 값에서 값을 읽습니다. 다음과 같은 템플릿을 참조하세요:

{% each users %}
{{name}}
{% end %}

users가 name 필드를 가진 객체의 배열이라고 가정할 때, 이는 모든 사용자의 이름을 출력합니다.

변수 태그를 사용하여 중첩된 객체에 접근할 수 있습니다. 예를 들어, {{ users.0.name }}는 users 변수에서 첫 번째 사용자의 이름을 출력합니다.

라인이 백슬래시로 끝나면 다음 줄바꿈은 무시됩니다. 이를 통해 불필요한 줄바꿈 없이 여러 줄에 걸쳐 코드를 감쌀 수 있습니다.

{%와 %}를 사용하는 태그(표현식 태그로 알려짐)는 그 뒤에 따라오는 줄바꿈을 소비합니다. 이는 다음과 같은 결과를 생성합니다:

---
{% if foo %}
bar
{% end %}
---

이는 다음과 같이 컴파일됩니다:

---
bar
---

이 대신 다음과 같지 않습니다:

---

bar

---

구성에서 사용자 정의 템플릿을 지정할 수 있습니다. 다음과 같이:

---
template: |
  {% if categories %}
  {% each categories %}
  ### {{ title }}

  {% each entries %}
  - [{{ title }}]({{ commit.web_url }})\
  {% if author.credit %} by {{ author.reference }}{% end %}

  {% end %}

  {% end %}
  {% else %}
  변경 사항이 없습니다.
  {% end %}

템플릿을 지정할 때는 template: |를 사용해야 하며, template: >는 사용하지 마세요. 후자는 템플릿에서 줄바꿈을 보존하지 않습니다.

템플릿 데이터

commit.web_url 및 merge_request.web_url는 GitLab 17.1에서 도입됨.

최상위 레벨에서 사용할 수 있는 변수는 다음과 같습니다:

categories: 모든 변경 로그 카테고리에 대한 객체 배열입니다.

카테고리에서는 다음 변수를 사용할 수 있습니다:

count: 이 카테고리에 있는 항목의 수입니다.
entries: 이 카테고리에 속하는 항목입니다.
single_change: 변경 사항이 하나만 있는 경우(true), 여러 개의 변경 사항이 있는 경우(false)를 나타내는 불리언입니다.
title: 카테고리의 제목(재매핑된 후)입니다.

항목에서는 다음 변수를 사용할 수 있습니다 (여기서 foo.bar는 bar가 foo의 하위 필드임을 의미합니다):

author.contributor: 작성자가 프로젝트 멤버가 아닐 경우 true로 설정되고, 그렇지 않으면 false로 설정되는 불리언입니다.
author.credit: author.contributor가 true일 때 또는 include_groups가 구성되어 있고 작성자가 그룹 중 하나의 멤버일 때 true로 설정되는 불리언입니다.
author.reference: 커밋 작성자에 대한 참조(예: @alice)입니다.
commit.reference: 커밋에 대한 참조, 예를 들어, gitlab-org/gitlab@0a4cdd86ab31748ba6dac0f69a8653f206e5cfc7입니다.
commit.web_url: 커밋에 대한 URL, 예를 들어, https://gitlab.com/gitlab-org/gitlab/-/commit/0a4cdd86ab31748ba6dac0f69a8653f206e5cfc7입니다.
commit.trailers: 커밋 본문에 존재했던 모든 Git 트레일러를 포함하는 객체입니다.

이러한 트레일러는 commit.trailers.<name>을 사용하여 참조할 수 있습니다. 예를 들어, 다음과 같은 커밋이 있다고 가정해 보겠습니다:
```
인상적인 새로운 기능 추가

변경 로그: 추가됨
문제: https://gitlab.com/gitlab-org/gitlab/-/issues/1234
상태: 중요
```
Changelog, Issue 및 Status 트레일러는 다음과 같이 템플릿에서 접근할 수 있습니다:
```
{% each entries %}
{% if commit.trailers.Issue %} ([문제 링크]({{ commit.trailers.Issue }})){% end %}
{% if commit.trailers.Status %}상태: {{ commit.trailers.Status }}{% end %}
{% end %}
```
merge_request.reference: 변경 사항을 처음 도입한 머지 요청에 대한 참조(예: gitlab-org/gitlab!50063)입니다.
merge_request.web_url: 변경 사항을 처음 도입한 머지 요청에 대한 URL(예: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/50063)입니다.
title: 변경 로그 항목의 제목(이는 커밋 제목입니다).

author 및 merge_request 객체는 데이터가 결정될 수 없었던 경우 존재하지 않을 수 있습니다. 예를 들어, 커밋이 해당 머지 요청 없이 생성된 경우, 머지 요청은 표시되지 않습니다.

버전 추출 시 태그 형식 사용자 지정

GitLab은 태그 이름에서 의미론적 버전을 추출하기 위해 정규 표현식을 사용합니다( re2 엔진 및 구문 사용). 기본 정규 표현식은 다음과 같습니다:

^v?(?P<major>0|[1-9]\d*)\.(?P<minor>0|[1-9]\d*)\.(?P<patch>0|[1-9]\d*)(?:-(?P<pre>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+(?P<meta>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$

이 정규 표현식은 공식 의미론적 버전 관리 정규 표현식에 기반하고 있으며, v로 시작하는 태그 이름에 대한 지원도 포함되어 있습니다.

프로젝트에서 다른 형식의 태그를 사용하는 경우 다른 정규 표현식을 지정할 수 있습니다. 사용되는 정규 표현식은 다음 캡처 그룹을 생성해야 합니다. 이러한 캡처 그룹 중 하나라도 누락되면 태그는 무시됩니다:

major
minor
patch

다음 캡처 그룹은 선택 사항입니다:

pre: 설정된 경우, 태그가 무시됩니다. pre 태그를 무시하면 릴리스 후보 태그 및 기타 사전 릴리스 태그가 변경 로그 생성을 위한 커밋 범위 결정 시 고려되지 않도록 합니다.
meta: 선택 사항. 빌드 메타데이터를 지정합니다.

이 정보를 사용하여 GitLab은 Git 태그와 그 릴리스 버전의 매핑을 생성합니다. 그런 다음 각 태그에서 추출된 버전을 기반으로 최신 태그를 결정합니다.

사용자 지정 정규 표현식을 지정하려면 변경 로그 구성 YAML 파일에서 tag_regex 설정을 사용하십시오. 예를 들어, 이 패턴은 version-1.2.3와 같은 태그 이름과 하지만 version-1.2는 일치하지 않습니다.

---
tag_regex: '^version-(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)$'

정규 표현식이 작동하는지 테스트하려면 regex101와 같은 웹사이트를 사용할 수 있습니다. 정규 표현식 구문이 유효하지 않으면 변경 로그 생성 시 오류가 발생합니다.

되돌린 커밋 처리

되돌린 커밋으로 처리되기 위해서는 커밋 메시지에

This reverts commit <SHA> 문자열이 포함되어야 하며, 여기서 SHA는 되돌릴 커밋의 SHA입니다.

범위에 대한 변경 로그를 생성할 때, GitLab은 해당 범위에서 추가되거나 되돌려진 커밋을 무시합니다. 이 예에서 커밋 C는 커밋 B를 되돌립니다. 커밋 C에는 다른 트레일러가 없기 때문에 커밋 A만 변경 로그에 추가됩니다:

%%{init: { "fontFamily": "GitLab Sans" }}%% graph LR accTitle: 3개의 커밋 흐름도 accDescr: 커밋 C가 커밋 B를 되돌리는 3개의 커밋 흐름을 보여주지만 트레일러가 없습니다 A[커밋 A 변경 로그: 변경됨] --> B[커밋 B 변경 로그: 변경됨] B --> C[커밋 C 커밋 B를 되돌림]

그러나 되돌린 커밋(커밋 C)도 변경 로그 트레일러를 포함하는 경우, 커밋 A와 C 모두 변경 로그에 포함됩니다:

%%{init: { "fontFamily": "GitLab Sans" }}%% graph LR accTitle: 3개의 커밋 흐름도 accDescr: 커밋 C가 커밋 B를 되돌리는 3개의 커밋 흐름을 보여주며, 커밋 A와 C 모두 트레일러를 포함합니다 A[커밋 A 변경 로그: 변경됨] --> B[커밋 B 변경 로그: 변경됨] B --> C[커밋 C 커밋 B를 되돌림 변경 로그: 변경됨]

커밋 B는 건너뜁니다.

변경 로그

Git 커밋에 트레일러 추가하기

변경 로그 생성하기

API를 통한 생성

GitLab CLI를 통한 생성

변경 로그 출력 사용자 정의

사용자 정의 템플릿

템플릿 데이터

버전 추출 시 태그 형식 사용자 지정

되돌린 커밋 처리

관련 주제

도움말

기능 사용 가능성과 제품 평가판

도움받기