デフォルトブランチ

新しいプロジェクトを作成すると、GitLab はリポジトリにデフォルトブランチを作成します。デフォルトブランチには、他のブランチにはない特別な設定オプションがあります：

新しいプロジェクトのデフォルトブランチの名前は、GitLab管理者が行ったインスタンスレベルやグループレベルの設定変更に依存します。GitLabはまず特定のカスタマイズをチェックし、その後より広いレベルでチェックし、カスタマイズが設定されていない場合にのみGitLabのデフォルトを使用します：

  1. プロジェクト固有のカスタムデフォルトブランチ名。
  2. サブグループレベルのカスタムデフォルトブランチ名。
  3. グループレベルのカスタムデフォルトブランチ名。
  4. インスタンスレベルのカスタムデフォルトブランチ名。
  5. どのレベルでもカスタムデフォルトブランチ名が設定されていない場合、GitLab のデフォルトは次のようになります：
    • main:GitLab 14.0 以降で作成されたプロジェクト。
    • master:GitLab 14.0以前に作成されたプロジェクト。

GitLab UIでは、どのレベルでもデフォルトを変更することができます。GitLabはリポジトリのコピーを更新するために必要なGitコマンドも提供します。

プロジェクトのデフォルトブランチ名の変更

前提条件：

  • プロジェクトのオーナーまたはメンテナーのロールを持っていること。

個々のプロジェクトのデフォルトブランチを更新するには、以下の手順に従います：

  1. 左のサイドバーで「検索」または「移動」を選択してあなたのプロジェクトを検索します。
  2. 設定] > [リポジトリ]を選択します。
  3. ブランチのデフォルトを展開します。デフォルトブランチ］で、新しいデフォルトブランチを選択します。
  4. オプションです。デフォルトブランチで参照されているイシューを自動クローズする］チェックボックスを選択すると、マージリクエストがクローズパターンを使用している場合にイシューをクローズします。
  5. 変更を保存を選択します。

APIユーザーは、プロジェクトを作成または編集する際にProjects APIの default_branch 属性を使用することもできます。

インスタンスやグループのデフォルトブランチ名の変更

GitLab 管理者はインスタンスレベルまたはグループレベルで新しいデフォルトブランチ名を設定することができます。

インスタンスレベルのカスタム初期ブランチ名

セルフマネージドインスタンスの GitLab管理者は、そのインスタンスでホストされているプロジェクトの初期ブランチをカスタマイズできます。個々のグループやサブグループは、プロジェクトに対してインスタンス全体の設定を上書きすることができます。

  1. 左のサイドバーで、Search を選択するか、次のページに進んでください。
  2. Admin Areaを選択します。
  3. 設定] > [リポジトリ]を選択します。
  4. デフォルトブランチを展開します。
  5. 初期デフォルトブランチ名]で、新しいデフォルトブランチを選択します。
  6. 変更を保存を選択します。

設定を変更した後にこのインスタンスで作成されるプロジェクトでは、グループレベルまたはサブグループレベルの設定がそれを上書きしない限り、カスタムブランチ名が使用されます。

グループレベルのカスタム初期ブランチ名

GitLab 13.6で導入されました。

グループやサブグループのオーナーロールを持つユーザーは、グループのデフォルトブランチ名を設定することができます：

  1. 左のサイドバーで、Search（検索）を選択するか、Go to（移動）を選択してグループを探します。
  2. 設定] > [リポジトリ]を選択します。
  3. デフォルトブランチを展開します。
  4. 初期デフォルトブランチ名]で、新しいデフォルトブランチを選択します。
  5. 変更を保存を選択します。

設定を変更した後にこのグループで作成されたプロジェクトでは、サブグループの設定が上書きしない限り、カスタムブランチ名が使用されます。

初期デフォルトブランチの保護

GitLab 16.0で導入された初期プッシュ後の完全な保護。

GitLab 管理者とグループオーナーは、インスタンスレベルとグループレベルで、すべてのリポジトリのデフォルトブランチに適用するブランチ保護を以下のオプションのいずれかで定義できます：

  • 完全保護- デフォルト値。開発者は新しいコミットをプッシュできませんが、メンテナーはできます。強制プッシュはできません。
  • 完全保護- 開発者は最初のコミットをリポジトリにプッシュできますが、それ以降はできません。メンテナーは常にプッシュできます。誰もプッシュを強制できません。
  • プッシュに対する保護- 開発者は新しいコミットをプッシュできませんが、ブランチへのマージリクエストを受け付けることはできます。メンテナーはブランチにプッシュできます。
  • 部分的に保護される - 開発者もメンテナーも新しいコミットをプッシュできますが、強制的にプッシュすることはできません。
  • 保護されていない - 開発者とメンテナーの両方が新しいコミットをプッシュできます。
caution
Fully protectedを選択しない限り、悪意のある開発者が機密データを盗もうとする可能性があります。たとえば、悪意のある.gitlab-ci.yml ファイルが保護されたブランチにコミットされ、後でそのブランチに対してパイプラインが実行されると、グループの CI/CD 変数が流出する可能性があります。

インスタンスレベルのデフォルトブランチ保護

この設定は、各リポジトリのデフォルトブランチにのみ適用されます。他のブランチを保護するには、以下のいずれかを行う必要があります：

自己管理インスタンスの管理者は、そのインスタンスでホストされているプロジェクトの初期デフォルトのブランチ保護をカスタマイズできます。個々のグループおよびサブグループは、プロジェクトに対してこのインスタンス全体の設定をオーバーライドできます。

  1. 左のサイドバーで、Search を選択するか、次のページに進んでください。
  2. Admin Areaを選択します。
  3. 設定] > [リポジトリ]を選択します。
  4. デフォルトブランチを展開します。
  5. 選択 初期デフォルトブランチの保護.
  6. グループのオーナーがインスタンスのデフォルトのブランチ保護を上書きできるようにするには、以下を選択します。 オーナーがグループごとにデフォルトのブランチ保護を管理できるようにします。.
  7. 変更を保存を選択します。

デフォルトブランチプロテクションのオーバーライドの防止

GitLab 13.0から導入されました。

デフォルトブランチのインスタンスレベルの保護は、グループのオーナーによってグループ単位で上書きすることができます。GitLab PremiumまたはUltimateでは、GitLab管理者はグループオーナーに対してこの権限を無効にし、インスタンスレベルの保護ルールを強制することができます：

  1. 左のサイドバーで、Search を選択するか、次のページに進んでください。
  2. Admin Areaを選択します。
  3. 設定] > [リポジトリ]を選択します。
  4. デフォルトブランチセクションを展開します。
  5. オーナーがグループごとにデフォルトブランチの保護を管理できるようにする］チェックボックスをオフにします。
  6. 変更を保存を選択します。
note
GitLab 管理者は、グループのデフォルトブランチプロテクションを更新することができます。

グループレベルのデフォルトブランチ保護

デフォルトブランチのインスタンスレベルの保護は、グループのオーナーによってグループ単位で上書きすることができます。GitLab PremiumまたはUltimateでは、GitLab管理者はグループオーナーに対してこの設定をロックする初期デフォルトブランチの保護を強制することができます。

  1. 左のサイドバーで、Search（検索）を選択するか、Go to（移動）を選択してグループを探します。
  2. 設定] > [リポジトリ]を選択します。
  3. デフォルトブランチを展開します。
  4. 選択 初期デフォルトブランチの保護.
  5. 変更を保存を選択します。

リポジトリのデフォルトブランチ名を更新します。

caution
デフォルトブランチの名前を変更すると、テストや CI/CD 設定、サービス、ヘルパーユーティリティ、リポジトリが使用しているインテグレーションなどが壊れる可能性があります。ブランチ名を変更する前に、プロジェクトオーナーやメンテナーと相談してください。この変更の範囲には、関連するコードやスクリプトの古いブランチ名への参照も含まれることを理解してもらいましょう。

既存のリポジトリのデフォルトブランチ名を変更する場合は、新しいブランチを作成するのではなく、デフォルトブランチの名前を変更して履歴を残しておくようにしましょう。この例では、Git リポジトリ (example) のデフォルトブランチの名前を変更しています。

  1. 内部のコマンドラインでexample リポジトリに移動し、デフォルトブランチにいることを確認します：

    cd example
git checkout master

  2. 既存のデフォルトブランチを新しい名前 (main) に変更します。引数-m は、すべてのコミット履歴を新しいブランチに転送します：

    git branch -m master main

  3. 新しく作成したmain ブランチをアップストリームにプッシュし、同じ名前のリモートブランチを追跡するように内部ブランチを設定します：

    git push -u origin main

  4. 古いデフォルトブランチを削除する場合は、HEAD を更新して新しいデフォルトブランチmain を指すようにします：

    git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main
  5. GitLab にメンテナー以上のロールでサインインし、指示に従ってこのプロジェクトのデフォルトブランチを変更します。main を新しいデフォルトブランチとして選択します。
  6. 保護されたブランチの説明に従って、main ブランチを保護します。
  7. オプションです。古いデフォルトブランチを削除したい場合：
    1. そのブランチを指すものがないことを確認してください。

    2. リモートのブランチを削除します：

      git push origin --delete master

      ブランチを削除するのは、新しいデフォルトブランチが期待通りに動作することを確認した後でもかまいません。

  8. プロジェクトの貢献者にもこの変更を知らせておきましょう：

    • 貢献者は、リポジトリのローカルコピーに新しいデフォルトブランチをプルする必要があります。
    • 古いデフォルトブランチをターゲットとしたマージリクエストを開いている貢献者は、手動でマージリクエストをmain に書き換えてください。
  9. リポジトリで、古いブランチ名への参照を更新してください。
  10. ヘルパーユーティリティやインテグレーションなど、リポジトリの外にある関連コードやスクリプトの古いブランチ名への参照を更新してください。

デフォルトのブランチ名のリダイレクト

GitLab 14.1で導入されました。

プロジェクト内の特定のファイルやディレクトリの URL は、プロジェクトのデフォルトブランチ名を埋め込むもので、ドキュメントやブラウザのブックマークによく見られます。リポジトリのデフォルトブランチ名を更新すると、これらの URL も変更されるため、更新する必要があります。

移行期間を簡単にするために、プロジェクトのデフォルトブランチが変更されるたびに、GitLab は古いデフォルトブランチの名前を記録します。そのブランチが削除された場合、そのブランチ上のファイルやディレクトリを表示しようとすると、”not found” ページが表示されるのではなく、現在のデフォルトブランチにリダイレクトされます。

トラブルシューティング

デフォルトブランチを変更できません: 現在のブランチにリセットされます

この問題はイシュー20474 で追跡中です。このイシューは、HEAD という名前のブランチがリポジトリに存在する場合によく発生します。この問題を修正するには

  1. ローカルリポジトリで、新しい一時ブランチを作成し、それをプッシュしてください：

    git checkout -b tmp_default && git push -u origin tmp_default
  2. GitLab では、デフォルトブランチをその一時ブランチに変更します。

  3. 内部リポジトリから、HEAD ブランチを削除します：

    git push -d origin HEAD
  4. GitLab で、デフォルトブランチを使用するブランチに変更します。

GraphQLでデフォルトブランチをクエリします。

グループ内のすべてのプロジェクトのデフォルトブランチを取得するには、GraphQL クエリを使用します。

すべてのプロジェクトを1ページの結果で返すには、GROUPNAME をグループへのフルパスに置き換えてください。GitLab は結果の最初のページを返します。hasNextPage がtrueの場合は、after: null のnull をendCursorの値に置き換えることで、次のページをリクエストすることができます：

{
 group(fullPath: "GROUPNAME") {
   projects(after: null) {
     pageInfo {
       hasNextPage
       endCursor
     }
     nodes {
       name
       repository {
         rootRef
       }
     }
   }
 }
}