正式なドキュメントは英語版であり、この日本語訳はAI支援翻訳により作成された参考用のものです。日本語訳の一部の内容は人間によるレビューがまだ行われていないため、翻訳のタイミングにより英語版との間に差異が生じることがあります。最新かつ正確な情報については、英語版をご参照ください。

変更履歴

  • プラン: Free、Premium、Ultimate
  • 提供形態: GitLab.com、GitLab 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は、日付ではなくバージョンに基づいてセクションをソートします。

各セクションは、カテゴリ（「機能」など）でソートされた変更を含んでおり、これらのセクションの形式は変更できます。セクション名は、コミットを含めるまたは除外するために使用するGitトレーラーの値から派生します。

変更履歴のコミットはミラーで操作するときに取得できます。パッチリリースに公開プロジェクトとプライベートセキュリティミラーの両方からの変更を含めることができるため、GitLab自体もこの機能を使用しています。

トレーラーをGitコミットに追加する

コミットメッセージを作成するときに、手動でトレーラーを追加できます。Changelogのデフォルトトレーラーを使用してコミットを含め、機能として分類するには、文字列Changelog: featureを次のようにコミットメッセージに追加します:

<Commit message subject>

<Commit message description>

Changelog: feature

マージリクエストに複数のコミットがある場合は、最初のコミットにChangelogエントリを追加してください。これにより、コミットをスカッシュしたときに、正しいエントリが生成されるようになります。

Changelogトレーラーは、次の値を受け入れます:

  • added: 新機能
  • fixed: バグ修正
  • changed: 機能変更
  • deprecated: 新規非推奨
  • removed: 機能削除
  • security: セキュリティ修正
  • performance: パフォーマンス改善
  • other: その他

変更履歴を作成する

変更履歴は、APIまたはGitLab CLIのいずれかを使用して、コマンドラインから生成します。変更履歴はMarkdown形式で出力されますが、カスタマイズできます。

APIから

APIを使用してcurlコマンドで変更履歴を生成するには、APIドキュメントの変更履歴データを変更履歴ファイルに追加するを参照してください。

GitLab CLIから

前提要件:

変更履歴を生成するには:

  1. git fetchでリポジトリのローカルコピーを更新します。

  2. デフォルトのオプションを使用して、（git describe --tagsによって決定された）現在のバージョンの変更履歴を生成するには:

    • コマンドglab changelog generateを実行します。
    • 出力をファイルに保存するには、コマンドglab changelog generate > <filename>.mdを実行します。

  3. カスタマイズしたオプションを使用して変更履歴を生成するには、コマンド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です。

パフォーマンスとセキュリティ上の理由から、変更履歴の設定の解析は2秒に制限されています。設定の解析でタイムアウトエラーが発生する場合は、設定のサイズを小さくすることを検討してください。このファイルは、次の変数をサポートしています:

  • date_format: 新しく追加される変更履歴データのタイトルに使用される日付形式（strftime形式）。

  • template: 変更履歴データを生成するときに使用するカスタムテンプレート。

  • include_groups: プロジェクトのメンバーシップに関係なく、コントリビュートを認める必要があるユーザーを含んでいるグループのフルパスのリスト。変更履歴を生成するユーザーのコントリビュートを認めるには、そのユーザーが各グループにアクセスできる必要があります。

  • categories: rawカテゴリ名を変更履歴で使用する名前にマップするハッシュ。変更履歴に表示する名前を変更するには、これらの行を設定ファイルに追加し、必要に応じて編集します。この例では、カテゴリタイトルが### Features、### Bug fixes、および### Performance improvementsとしてレンダリングされます:

    ---
categories:
  feature: Features
  bug: Bug fixes
  performance: Performance improvements

カスタムテンプレート

カテゴリセクションは、テンプレートを使用して生成されます。デフォルトテンプレートは次のとおりです:

{% 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 %}
No changes.
{% end %}

{% ... %}タグはステートメント用で、{{ ... }}はデータを出力するために使用されます。ステートメントは、{% end %}タグを使用して終了する必要があります。ifステートメントとeachステートメントの両方に、単一の引数が必要です。

たとえば、validという名前の変数の場合、次のように入力して、この値がtrueの場合は「yes」と表示し、それ以外の場合は「nope」と表示できます:

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

elseの使用はオプションです。値は、空でない値またはブール値trueの場合にtrueと見なされます。空の配列とハッシュはfalseと見なされます。

ループはeachを使用して行われ、ループ内の変数のスコーピングはそのループに制限されます。ループ内の現在の値を参照するには、変数タグ{{ it }}を使用します。他の変数は、現在のループ値から値を読み取ります。たとえば、次のテンプレートについて考えてみましょう:

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

usersがオブジェクトの配列で、それぞれにnameフィールドがあるとすると、この場合すべてのユーザーの名前が出力されます。

変数タグを使用すると、ネストされたオブジェクトにアクセスできます。たとえば、{{ users.0.name }}は、users変数の最初のユーザーの名前を出力します。

行がバックスラッシュで終わる場合、次の改行は無視されます。これにより、Markdown出力に不要な改行を追加せずに、コードを複数の行にわたって折り返すことができます。

{%および%}を使用するタグ（表現タグと呼ばれる）は、その直後に改行がある場合はその改行を消費します。これは、次のようになることを意味します:

---
{% 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 %}
  No changes.
  {% end %}

テンプレートを指定するときは、template: >ではテンプレート内の改行が保持されないため、template: |を使用する必要があります。

テンプレートデータ

トップレベルでは、次の変数を使用できます:

  • categories: オブジェクトの配列。変更履歴カテゴリごとに1つ。

カテゴリでは、次の変数を使用できます:

  • count: このカテゴリにあるエントリの数。
  • entries: このカテゴリに属するエントリ。
  • single_change: 変更が1つしかないか（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>を使用して参照できます。たとえば、次のコミットがあるとします:

    Add some impressive new feature

Changelog: added
Issue: https://gitlab.com/gitlab-org/gitlab/-/issues/1234
Status: important

    Changelog、Issue、およびStatusトレーラーには、テンプレートで次のようにアクセスできます:

    {% each entries %}
{% if commit.trailers.Issue %} ([link to issue]({{ commit.trailers.Issue }})){% end %}
{% if commit.trailers.Status %}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: Flowchart of 3 commits
    accDescr: Shows the flow of 3 commits, where commit C reverts commit B, but it contains no trailer
    A[Commit A<br>Changelog: changed] --> B[Commit B<br>Changelog: changed]
    B --> C[Commit C<br>Reverts commit B]

ただし、リバートコミット（コミットC）に変更履歴トレーラーも含まれている場合、コミットAとコミットCの両方が変更履歴に含まれます:

%%{init: { "fontFamily": "GitLab Sans" }}%%
graph LR
    accTitle: Flowchart of 3 commits
    accDescr: Shows the flow of 3 commits, where commit C reverts commit B, but both commits A and C contain trailers
    A[Commit A<br><br>Changelog: changed] --> B[Commit B<br><br>Changelog: changed]
    B --> C[Commit C<br>Reverts commit B<br>Changelog: changed]

コミットBはスキップされます。