# マージルール

マージルールでは、変更リクエストをマージする前に満たす必要がある要件を定義できます。たとえば、特定のユーザーによるレビューが必要であることや、変更リクエストに件名または説明が必要であることなどです。

これらのルールは、コンテンツの品質を維持し、ドキュメントワークフロー全体で適切なレビュー գործընթացを確保するのに役立ちます。

マージルールを設定すると、変更リクエストがマージされる前に自動的に評価されます。ルールが満たされていない場合、要件が満たされるまでマージはブロックされます。

これにより、チームのコラボレーションとレビュー基準を強制する自動化された方法が提供されます。

## マージルールの使用

チームのワークフローに合わせて、さまざまなレベルでマージルールを設定できます。

### 組織レベルの設定

組織は、すべてのスペースが継承する既定のマージルールを設定できます。これにより、複数のスペース間で一貫性を保ちながら、必要に応じて各スペースが独自のルールをカスタマイズできます。

組織のマージルールを設定するには、サイドバー上部の組織メニューを開き、 **設定** <picture><source srcset="broken-reference" media="(prefers-color-scheme: dark)"><img src="https://4217681718-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNkEGS7hzeqa35sMXQZ4X%2Fuploads%2FwkBqgOPry9HAcW4cxJk0%2Fsettings.svg?alt=media&#x26;token=67bdbb00-ebf3-4a2d-9df8-0c822406f71c" alt=""></picture>を選択します。設定画面で、サイドバーの **マージルール** の下にある **組織** セクションを選択します。ここで、組織全体のマージルールを指定できます。

制限なしのマージを選ぶか、プリセットの一覧から選択して組織全体の変更リクエストに適用できます。

### スペースレベルの設定

組織全体のマージルールを有効にしているかどうかにかかわらず、各スペースはコンテンツやチーム構成に合わせた独自のマージ要件を持つことができます。

これにより、重要なドキュメントにはより厳しいルールを適用し、下書きコンテンツにはより緩やかなルールを適用する柔軟性が得られます。

スペースのマージルールを設定するときは、次のいずれかを選択できます。

* **継承する** 組織のマージルールを
* **カスタムルールを定義する** そのスペース専用の
* **マージルールを無効にする** 完全に

{% hint style="info" %}
組織のルールを継承した場合、組織のマージルールへの変更は自動的にそのスペースに適用されます。
{% endhint %}

組織のマージルールを設定するには、 **アクションメニュー** <i class="fa-ellipsis">:ellipsis:</i> をエディタの左上で開き、次に **マージルール**を選択します。ここで、組織からマージルールを継承するか、そのスペース専用の新しいルールを設定するかを指定できます。

## ルールの評価

### ルールの仕組み

誰かが変更リクエストをマージしようとすると、GitBook は設定されたすべてのルールを順番に評価します。

* マージを許可するには、設定内のすべてのルールに合格する必要があります
* ルールは、設定に表示されている順序で評価されます
* いずれかのルールが失敗すると、適切なエラーメッセージとともにマージはブロックされます
* バイパス機能を持つルールは、以前の失敗を上書きできます

### バイパスルール

一部のルールにはバイパス機能があります（たとえば **指定したアクターに要件のバイパスを許可する**）。これらの特別なルールは他のルールの失敗を上書きできます。バイパスルールが true と評価されると、他のルールが失敗していてもマージは許可されます。

## ベストプラクティス

マージルールを設定する際は、次の推奨事項を検討してください。

* **シンプルに始める**：まずは、少なくとも 1 件のレビューを必須にするなどの基本的なルールから始めます。
* **段階的に拡張する**：チームが成長し、ワークフローが成熟するにつれて、より具体的な要件を追加します。
* **バイパスは慎重に使う**：信頼できる管理者にのみバイパス権限を付与してください。
* **定期的に見直す**：チームの実際のワークフローパターンに基づいてルールを調整します。
* **まずテストする**：可能であれば、本番スペースに適用する前にテストスペースでルール変更を試してください。

## 利用可能なルールの種類

### レビュー要件

<table><thead><tr><th width="279.703125">ルール</th><th>説明</th></tr></thead><tbody><tr><td><strong>少なくとも 1 件のレビューを必須にする</strong></td><td>変更リクエストがマージされる前に、少なくとも 1 人のチームメンバーがそれをレビューしていることを保証します。</td></tr><tr><td><strong>すべてのレビューの承認を必須にする</strong></td><td>すべての <strong>完了済みの</strong> （要求されていない）レビューはすべて承認でなければなりません。レビュー担当者のいずれかが変更を要求したり、変更リクエストを却下した場合、マージはブロックされます。</td></tr><tr><td><strong>指定したアクターによるレビューを必須にする</strong></td><td>指定したすべてのユーザーからの承認が必要です。マージされる前に変更リクエストをレビューして承認しなければならない、特定のチームメンバーを選択できます。</td></tr><tr><td><strong>指定したアクターのいずれかによるレビューを必須にする</strong></td><td>指定したユーザーのうち少なくとも 1 人からの承認が必要です。これは、複数の適格なレビュワーがいるものの、グループから 1 件の承認だけでよい場合に便利です。</td></tr><tr><td><strong>Docs Agent のレビューを必須にする（近日公開）</strong></td><td>GitBook の AI エージェントによるレビューが必要です。これにより、マージ前にコンテンツ変更に対する自動品質チェックが実行されます。</td></tr></tbody></table>

### 変更リクエストの要件

<table><thead><tr><th width="279.703125">ルール</th><th>説明</th></tr></thead><tbody><tr><td><strong>最新の変更リクエストを必須にする</strong></td><td>変更リクエストは、主要なコンテンツブランチと最新でなければなりません。変更リクエスト作成後に主要コンテンツが更新された場合、マージ前に rebase または更新する必要があります。</td></tr><tr><td><strong>件名を必須にする</strong></td><td>変更リクエストには、説明的な件名/タイトルが必要です。空の件名ではマージはブロックされます。</td></tr><tr><td><strong>説明を必須にする</strong></td><td>変更リクエストには、どのような変更を行い、なぜ行ったのかを説明する内容が含まれていなければなりません。</td></tr></tbody></table>

### 詳細オプション

<table><thead><tr><th width="279.703125">ルール</th><th>説明</th></tr></thead><tbody><tr><td><strong>指定したアクターに要件のバイパスを許可する</strong></td><td>他のすべてのマージルール要件をバイパスできる特定のユーザーを指定できます。これは、管理者や、ルールを上書きする必要がある緊急時に便利です。</td></tr><tr><td><strong>カスタム式</strong></td><td>カスタム JavaScript 式を使用して、高度なマージルールを作成できます。これにより、変更リクエスト、レビュー、およびマージを試みているユーザーのプロパティにアクセスしながら、評価コンテキストに基づく複雑なロジックを定義できます。</td></tr></tbody></table>

#### カスタム式

カスタム式を作成すると、誰かが変更リクエストをマージしようとするたびに評価されます。式が `true`を返すと、マージは許可されます。 `false`を返すと、マージはブロックされます。

{% hint style="info" %}
カスタム式は標準の JavaScript 構文（ES2022）をサポートし、最大長は 1024 文字です。
{% endhint %}

**利用可能なコンテキスト変数：**

* `changeRequest.subject` - 変更リクエストの件名/タイトル
* `changeRequest.description` - 変更リクエストの説明
* `changeRequest.outdated` - 変更リクエストが古くなっているかどうか（真偽値）
* `changeRequest.createdBy.id` - 変更リクエストを作成したユーザーの ID
* `reviews` - レビューオブジェクトの配列。各オブジェクトには次が含まれます：
  * `reviews[].status` - レビューステータス（`"approved"` または `"changes_requested"`)
  * `reviews[].reviewer.id` - レビュー担当者の ID
* `actor.id` - マージを試みているユーザーの ID

**一般的な式の例：**

{% code title="複数の承認済みレビューを必須にする" %}

```javascript
reviews.filter(r => r.status === "approved").length >= 2
```

{% endcode %}

{% code title="特定ユーザーからの承認を必須にする" %}

```javascript
reviews.some(r => r.reviewer.id === "harry" && r.status === "approved")
```

{% endcode %}

{% code title="緊急変更に説明を必須にする" %}

```javascript
!changeRequest.subject.includes("[URGENT]") || !!changeRequest.description
```

{% endcode %}

{% code title="軽微な変更にのみ自己マージを許可する" %}

```javascript
changeRequest.createdBy.id === actor.id ? changeRequest.subject.startsWith("[minor]") : true
```

{% endcode %}