ツイートシェアはてブ LINE Pocket

ブランチとマージ制限のセットアップ

プロジェクトロールを使用すると、リポジトリでの書き込み権限と読み取り権限を管理できますが、それだけではコードの品質と効率的なコラボレーションを確保するには不十分な場合があります。

ブランチ保護設定を使用すると、リポジトリ全体に過剰な制限を課すことなく、重要なブランチを不注意な操作や望ましくない変更から保護できます。

特定のブランチのセキュリティルールを作成すると、次のことが可能になります。

誤ってブランチが削除されるのを防ぎます。
ブランチをプッシュまたは強制的にプッシュできる人を制限します。
ブランチに変更をマージできる人を制限します。
品質ゲートを有効にして、テスト、レビュー、承認された変更のみがブランチに反映されるようにします。

例: main への直接プッシュを禁止し、main にマージする前に、すべての変更をマージリクエスト経由で送信し、特定の自動チェックに合格し、指定されたメンバーのグループから十分な承認を得ることを要求できます。

ブランチ保護ルールを設定するには:

リポジトリ設定ページを開きます。
保護されたブランチタブに移動します。
既存のルール (存在する場合) はこのページにリストされます。
- 既存のルールを編集するには、その横にあるをクリックします。
- 新しいルールを作成するには、「新規ルール」をクリックします。
以下の説明を参照して制限を設定し、完了したら保存を押します。

ブランチを指定してください

このルールの制限の影響を受けるブランチを指定します。特定のブランチを 1 つ追加することも、一度に複数のブランチを追加することも、すべてのブランチを追加することも、命名パターンに一致する任意のブランチを追加することもできます。次の構文を使用します。

ブランチ (例: +:refs/heads/main) を含めるには、+:<branch name> と入力します。
ブランチ (例: -:refs/heads/main) を除外するには、-:<branch name> と入力します。
* をワイルドカードとして使用します。例: +:* にはすべてのブランチが含まれます。
名前に特定の文字列が含まれるブランチを指定するには、その文字列をアスタリスクで囲みます。例: prod を含むすべてのブランチ (例: production、prod-1 など) を含めるには、+:*prod* と入力します。

マージコミットを禁止する

保護されたブランチへのマージコミットのプッシュを禁止するには、線形履歴を強制するを確認します。

このオプションは、機能ブランチを保護されたブランチにマージすることを完全に妨げるものではなく、マージコミットを禁止するだけです。他の条件があればそれが満たされていれば、リベースまたはスカッシュとリベースを介したマージは引き続き許可されます。

規制された行為

次のアクションの実行を許可するメンバー、ロール、アプリケーションを指定します。

新しいブランチを (このルールで指定された保護されたブランチから) 作成します。
保護されたブランチにプッシュします。
保護されたブランチに強制的にプッシュします。
保護されたブランチを削除します。

品質ゲート (後述) を有効にし、コミッターにマージリクエスト経由で変更を送信するよう要求する場合は、プッシュフィールドと強制プッシュフィールドからすべてのコミッターを削除し、制限をバイパスできるユーザーのみを追加します。

マージリクエストの品質ゲート

検証および承認されたコミットのみが保護されたブランチにマージされるようにするために、マージ前に満たす必要があるいくつかの要件と条件を設定できます。

クオリティゲートを有効にすると、コミッターはまず変更を別のブランチにプッシュし、保護されたブランチをターゲットとして指定してコミットのマージリクエストを作成する必要があります。コミットは、ここで指定された品質ゲート要件を満たす場合にのみマージできます。たとえば、選択した自動チェックに合格した後、トリガーされたか、指定されたメンバーから十分な数の承認を取得した後、その両方になります。

スイッチオンを回して、これらの設定を構成し、有効にします。

クオリティゲートを通過する必要があるメンバー

すべての条件が満たされた場合に、保護されたブランチへのマージを実行できるメンバーを指定します。ロール (例: プロジェクト管理者 ) を追加すると、そのロールを持つすべてのメンバーがマージする権利を取得します。

上記の規制された行為セクションでプッシュおよび強制プッシュアクションが制限されていることを確認してください。それ以外の場合、すべてのプロジェクトメンバーは、品質ゲート条件をバイパスして、保護されたブランチに直接プッシュできます。

要件:

承認
指定されたメンバーによってレビューおよび承認された場合にのみ、変更をマージできます。
- コード所有者の承認を必要とする : 特定のメンバーが所有するファイルに加えられた変更は、マージを許可するためにこれらのメンバーの承認が必要になります。ファイルの所有権は、CODEOWNERS ファイルで事前に定義する必要があります。CODEOWNERS ファイルの設定方法については、「コードの所有者」を参照してください。
- From: 承認が必要なメンバーを選択し、マージを許可するには選択したメンバーのうち何人が変更を承認する必要があるかを指定します (例: 選択した 5 人のメンバーのうち任意の 2 人)。
- 自己承認を許可する : このオプションが有効な場合、必要なメンバーまたはコード所有者からの自身の変更に対する承認は有効とみなされます。例: マージリクエストの作成者が承認が必要なメンバーの 1 人である場合、彼は自分の変更を承認することができます。このオプションを無効にすると、彼の承認は受け入れられません。
ジョブ
リポジトリ内のコミットで実行するように設定された自動化ジョブがある場合、それらはここにリストされます。品質ゲート条件として、それらのすべてまたは一部を選択できます。
選択したすべてのジョブがコミットによってトリガーされた場合、ゲートを通過するには正常に完了する必要があります。
外部チェック
リポジトリが外部 CI サービス (TeamCity、Jenkins など) からビルドステータスを受信する場合、コミットをマージできるようにする前に、コミットを渡すために 1 つ以上のステータスチェックを要求できます。
リポジトリに接続されている各サービスが、実行されるチェックとともにここにリストされます。品質ゲートを通過するために正常に完了する必要があるサービスを選択します。
安全なマージ
Safe Merge は、作成した仮想マージコミット時に事前定義された自動化ジョブまたは外部チェック (現在は TeamCity のみ) を実行し、チェックが成功した場合にのみ永続的にマージします。
安全なマージについて詳しくは、以下を参照してください。

安全なマージ

フィーチャーブランチコミットに対して実行される上記のマージ前の品質チェックとは対照的に、セーフマージではマージコミットに対して品質チェックを実行できますが、必ずしもマージを完了する必要はありません。作成した一時的なマージコミットをチェックし、チェックが成功した場合にのみマージを許可します。これは、機能ブランチがすでにマージされているかのように、将来のビルドステータスを垣間見ることができる小さなタイムマシンと考えてください。

安全なマージを使用する理由

Safe Merge は、メイン (保護された) ブランチに追加の保護層を追加し、機能ブランチがマージされた後に自動品質チェックに合格し、マージコミットによってビルドが失敗しないようにします。

マージ前チェック (ジョブと外部チェック) は未検証のコミットがメインにマージされるのを防ぎますが、次の理由により、それだけでは確実なマージを保証できません。

マージ前チェックは、マージ前の機能ブランチのヘッドコミットに対してのみ実行され、メインの現在の状態は考慮されません。
一方、メインのブランチは大幅に逸脱している可能性があり、マージ後に機能ブランチとセマンティックの競合を引き起こす変更が含まれる可能性があり、ビルドが損なわれる可能性があります。

これは、複数の開発者が同時にプロジェクトに取り組んでおり、有効期間の長い機能ブランチが通常のワークフローの一部である、ペースの速い開発環境に特に当てはまります。

Safe Merge を使用すると、有害な可能性のある変更を実際に main にマージすることなく、要求されたマージに対して統合チェックを実行することで、この課題に対処できます。これを達成するために、Safe Merge は、最新のメインリビジョンと機能ブランチリビジョンを組み合わせた一時的なマージコミットを作成し、事前定義された自動ジョブまたは TeamCity チェックを使用してこのコミットをテストします。すべて課題なければ、機能ブランチをメインに永久にマージできます。

安全なマージを設定して有効にする

安全なマージを設定するには、マージ時に実行するジョブや TeamCity チェックへの参照を含む構成ファイルをリポジトリに作成する必要があります。

オプションで、機能ブランチ内の特定のファイルがマージ前に変更された場合にのみ品質チェックがトリガーされるように設定できます。

セーフマージによってどの自動化ジョブや TeamCity 品質チェックがトリガーされるかを決定します。詳細については、品質ゲートのベストプラクティス: どのような自動チェックをいつ使用するかを参照してください。
Safe Merge 構成で TeamCity 品質チェックをトリガーする場合は、次のことを行う必要があります。
- Space プロジェクトを TeamCity と統合するは、TeamCity のステータス発行者のコミットからコミット (ビルド) ステータスを受け取ります。
- TeamCity で、プロジェクトの VCS ルートを編集します。プロジェクト設定→ VCS ルートに移動し、行 +:(refs/merge/*) をブランチ仕様に追加します。
リポジトリに .json 構成ファイルを作成します。
- ブランチ保護ルール設定の安全なマージセクションに移動します。
- 安全なマージをオンにして、作成をクリックします。
- リポジトリ内のファイル名と場所を編集できます。必ず .json 形式を維持してください。作成をクリックします。
  サイドパネルにコード例を含む空の構成ファイルが表示されます。
- 安全なマージ構成を作成します。以下は、1 つの自動化ジョブのみをトリガーする最も基本的な構成です。
  サイドパネルのサンプルコードを使用し、構成例と構文の説明を参照して独自の構成を作成します。
- 完了したら、構成ファイルの保存およびコミットをクリックします。ファイルはプッシュされ、ブランチ保護ルールで定義された保護されたブランチにリンクされます。
あるいは、IDE から Safe Merge 構成ファイルを作成することもできます。
- 固有の名前を持つ .json ファイルを作成し、それをリポジトリの保護されたブランチにプッシュします。
- ブランチ保護ルール設定の安全なマージセクションに移動します。
- 安全なマージをオンにして、選択をクリックします。
- 作成した構成ファイルを選択し、保存をクリックします。
- 構成ファイルは保護されたブランチにリンクされ、安全なマージ設定セクションに表示されます。

Safe Merge の構成例と構文の説明

構成を作成するには、次の例と構文の説明を参照してください。

例。ファイルにはオブジェクトの配列が含まれており、各オブジェクトは事前定義されたオートメーションジョブまたは TeamCity チェック (ビルド構成) への参照です。この例には、2 つのオートメーションジョブと 1 つの TeamCity ビルド構成があります。ジョブの 1 つには、そのジョブをトリガーする条件として、変更されたファイルへのパスも含まれています。

{
    "version": "1.0",
    "retry-policy": {
        "num-retries": 3,
        "reuse-merge": true
    },
    "builds": [
        {
            "job": {
                "name": "UI Tests"
            }

        },
        {
            "job": {
                "name": "Performance Tests"
            },
            "changed-files": [
                "/platform/**",
                "/deployments/**"
            ]
        },
        {
            "teamcity": {
                "configuration": "Integration_Tests",
                "url": "https://myteamcityserver.net",
                "token": "${teamcity-safe-merge}",
                "ssl-keystore": "TeamCityServer client"
            }
        }
    ]
}

パラメーター	説明
`"version":`	Safe Merge のバージョン番号。`"1.0"` である必要があります
`"retry-policy":`	オプション。不安定なテストが原因でビルドが失敗することがあります。失敗したビルドを再実行するには、「num-retries」および「reuse-merge」パラメーターを使用して再試行ポリシーを設定できます (以下を参照)。
`"num-retries":`	ビルドが失敗した場合（品質チェックに合格しなかった場合）の合計再試行回数を指定します。デフォルト値は 0 です。
`"reuse-merge":`	再試行時に同じ一時マージコミットを使用するか (true)、再試行のたびに新しい一時マージコミットを作成するか (false) を指定します。
`"builds":`	オートメーションジョブまたは TeamCity ビルド構成への参照を配列オブジェクトとしてリストします。
"job": { "name": }	安全なマージによってトリガーされ、マージコミット時に実行されるプロジェクト内のジョブの名前を指定します。
`"teamcity":`	安全なマージによってトリガーされ、マージコミット時に実行される TeamCity ビルド構成を指定します。必要なパラメーターをすべて指定します (構成、URL、トークン、SSL キーストア)。
`"configuration":`	TeamCity ビルド構成の ID。
`"url":`	TeamCity サーバーの URL。
`"token":`	TeamCity の認証に使用されるシークレットのキー。シークレットを調べるには: プロジェクトのサイドバーで、設定をクリックします。シークレットとパラメータータブに移動します。 TeamCity 側で作成されたトークンには、次の権限が必要です。 `Comment build` `Run build` `Stop / remove from queue any personal build` `Stop build / remove from queue` `View build configuration settings` `View build runtime parameters and data`
`"ssl-keystore":`	オプション。TeamCity 構成で SSL 証明書を使用する場合は、証明書キーストアの名前を指定します。これを調べるには、「管理」 -> 「SSL キーストア」にアクセスしてください。詳細については、SSL キーストアを参照してください。
`"changed-files":`	オプション。ジョブまたは TeamCity チェックは、指定されたフィールドが変更された場合にのみ実行されます。各行は、ファイルまたはディレクトリに一致するパターンを指定します。例 1 : "changed-files": [ "/tests/", "/clients/client.kts" ] ディレクトリ `tests` とそのサブディレクトリ内のファイル、およびディレクトリ `clients` 内のファイル `client.kts` と一致します。例 2** : "changed-files": [ "", "!/deployments/", "!/apps/app.kts" ] 以下を除くすべてのファイルに一致します。ディレクトリ `deployments` およびそのサブディレクトリ内のファイルディレクトリ `apps` にあるファイル `app.kts` パターンの形式と構文は、gitignore* ファイルで使用されるものと同じです。詳細な構文の説明(英語)を参照してください。

安全なマージの使用

Safe Merge を構成して有効にすると、あなたのチームがそれを使い始めることができます。

マージリクエストページのマージボタンは安全なマージに置き換えられます。このボタンを押すと、一時的なマージコミットが作成され、セーフマージ設定ファイルで指定された品質チェックが実行されます。チェックが成功すると、マージを完了するように求められます。

今後のマージをテストしたいだけで、マージを完了するつもりはない場合は、リハーサルを押します。この場合、すべてのチェックに合格したとしても、マージを完了するように求められることはありません。

品質ゲートのベストプラクティス: どのような自動チェックをいつ使用するか

Quality Gates を使用すると、コードベースの安全性を損なうことなく、また開発プロセスを遅らせることなく、特定のプロジェクトに最も効果的なマージ要件ポリシーを設定できます。

実際の設定は、どのような自動チェックとテストが使用されるか、どのような開発ワークフローがチームによって適応されるかなど、プロジェクトの詳細によって異なりますが、一般的なガイダンスとして次のルールを使用できます。

参加者が少ない小規模プロジェクトでは、安全なマージを使用せずに、品質ゲート要件をレビュー担当者の承認と、フィーチャーブランチヘッドで実行されるマージ前のジョブまたは TeamCity チェックに制限することができます。
多数の開発者が参加するアクティブなプロジェクト、毎日の大量のコミット、有効期間の長い機能ブランチの場合、Safe Merge が最適なソリューションです。ビルド構成と実行しているチェックのサイズに応じて、機能ブランチ (マージ前) チェックに加えて、またはその代わりにこれを設定できます。
開発をスピードアップするには、機能ブランチに対して軽いチェックのみを実行し、一度だけ実行される Safe Merge の重い統合チェックはすべて残しておくことが最善です。このアプローチを使用すると、マイナーな修正コミットごとに時間のかかる大規模なチェックを実行する必要がなくなり、マージリクエストの寿命が実質的に短くなります。

保護されたブランチ構成の例

リポジトリに多数のコントリビュータがあり、メインのブランチが実稼働用に予約されているという一般的なシナリオを考えてみましょう。メインのブランチを健全な状態に保つには、少なくとも 1 人の経験豊富な開発者によるレビューと承認がない限り、変更をプッシュしないでください。コミットでテストジョブを実行するように Space オートメーションを設定しているため、すべてのコミットが main に送信される前に自動ステータスチェックに合格することも必要です。

ブランチ保護設定を構成する方法は次のとおりです。

リポジトリ設定ページを開いて、保護されたブランチタブに移動します。
「新規ルール」をクリックしてフォームを開きます。
main を保護されたブランチとして指定します。
誰もプッシュと main への強制プッシュを許可しませんが、すべてのコミッターが main から新しいブランチを作成することを許可します。
main を誤って削除したくないのは明らかなので、この操作は誰にも許可しないでください。
品質ゲート設定をオンにします。
すべてのコミッターがすべての要件を満たした後、変更を main にマージできるようにしたいとします。
次の 3 人のメンバーの少なくとも 1 人によってレビューおよび承認されない限り、変更はマージされません。
最後に、すべてのコミットが main にマージされる前に自動チェックに正常に合格する必要があるため、ここにリストされているジョブを要件として選択します。
構成を保存することを忘れないでください。保護されたブランチタブのリポジトリ設定ページでいつでも表示および編集できます。