默认分支

当你创建一个新的项目时，极狐GitLab 会在仓库中创建一个默认分支。默认分支具有其它分支不具备的特殊配置选项：

不能被删除。
初始保护以防止强制推送。
当合并请求使用议题关闭模式关闭议题时，工作会被合并到该分支。

新项目的默认分支名称取决于极狐GitLab 管理员所做的任何实例级或组级配置更改。极狐GitLab 首先检查特定的自定义设置，然后检查更广泛的级别，仅在没有设置自定义时使用极狐GitLab 默认值：

项目特定的自定义默认分支名称。
项目直接子组中指定的自定义组默认分支名称。
项目顶级组中指定的自定义组默认分支名称。
实例级的自定义默认分支名称。
如果没有在任何级别设置自定义默认分支名称，GitLab 默认使用 main。

在极狐GitLab UI 中，你可以在任何级别更改默认设置。极狐GitLab 还提供了更新仓库副本所需的 Git 命令。

更改项目的默认分支名称

前提条件：

你拥有项目的所有者或维护者角色。

要更新单个项目的默认分支：

在左侧边栏，选择 搜索或前往 并找到你的项目。
选择 设置 > 仓库。
展开 分支默认值。对于 默认分支，选择一个新的默认分支。
可选。选择 自动关闭默认分支上的引用议题 复选框，以便在合并请求使用关闭模式时关闭议题。
选择 保存更改。

API 用户还可以在创建或编辑项目时使用项目 API的 default_branch 属性。

更改实例或组的默认分支名称

极狐GitLab 管理员可以在实例级或组级配置新的默认分支名称。

实例级自定义初始分支名称

私有化部署实例的极狐GitLab 管理员可以自定义该实例上托管的项目的初始分支。各个组和子组可以覆盖此实例范围的设置。

在左侧边栏底部，选择 管理员。
选择 设置 > 仓库。
展开 默认分支。
对于 初始默认分支名称，选择一个新的默认分支。
选择 保存更改。

在更改设置后创建的项目将使用自定义分支名称，除非组级或子组级配置覆盖了它。

组级自定义初始分支名称

具有组和子组所有者角色的用户可以配置组的默认分支名称：

在左侧边栏，选择 搜索或前往 并找到你的组。
选择 设置 > 仓库。
展开 默认分支。
对于 初始默认分支名称，选择一个新的默认分支。
选择 保存更改。

在更改设置后创建的项目将使用自定义分支名称，除非子组配置覆盖了它。

保护初始默认分支

GitLab 16.0 中引入的初始推送后的完全保护。

极狐GitLab 管理员和组所有者可以定义分支保护，以应用于每个仓库的默认分支，在实例级和组级使用以下选项之一：

完全保护 - 默认值。开发人员不能推送新提交，但维护者可以。没有人可以强制推送。
初始推送后的完全保护 - 开发人员可以推送仓库的初始提交，但之后不能。维护者始终可以推送。没有人可以强制推送。
保护推送 - 开发人员不能推送新提交，但可以接受合并请求到该分支。维护者可以推送到该分支。
部分保护 - 开发人员和维护者都可以推送新提交，但不能强制推送。
不保护 - 开发人员和维护者都可以推送新提交并强制推送。

警告：除非选择 完全保护，否则恶意开发人员可能会尝试窃取你的敏感数据。例如，恶意的 .gitlab-ci.yml 文件可能会被提交到受保护的分支，之后如果在该分支上运行管道，可能会导致组 CI/CD 变量的泄露。

实例级默认分支保护

此设置仅适用于每个仓库的默认分支。要保护其他分支，你必须：

在仓库中配置分支保护。
为组配置分支保护。

私有化部署实例的管理员可以自定义该实例上托管的项目的初始默认分支保护。各个组和子组可以覆盖此实例范围的设置。

在左侧边栏底部，选择 管理员。
选择 设置 > 仓库。
展开 默认分支。
选择 初始默认分支保护。
要允许组所有者覆盖实例的默认分支保护，选择允许所有者管理每个组的默认分支保护。
选择 保存更改。

防止覆盖默认分支保护

默认分支的实例级保护可以由组所有者在每个组的基础上覆盖。在极狐GitLab 专业或旗舰中，极狐GitLab 管理员可以禁用组所有者的此权限，强制执行实例级保护规则：

在左侧边栏底部，选择 管理员。
选择 设置 > 仓库。
展开 默认分支部分。
清除 允许所有者管理每个组的默认分支保护 复选框。
选择 保存更改。

注意：极狐GitLab 管理员仍然可以更新组的默认分支保护。

组级默认分支保护

默认分支的实例级保护可以由组所有者在每个组的基础上覆盖。在极狐GitLab 专业或旗舰中，极狐GitLab 管理员可以强制保护初始默认分支，这将锁定组所有者的此设置。

在左侧边栏，选择 搜索或前往 并找到你的组。
选择 设置 > 仓库。
展开 默认分支。
选择 初始默认分支保护。
选择 保存更改。

更新仓库中的默认分支名称

警告：更改默认分支的名称可能会破坏测试、CI/CD 配置、服务、辅助工具和你的仓库使用的任何集成。在更改此分支名称之前，请与项目所有者和维护者协商。确保他们了解此更改的范围包括相关代码和脚本中对旧分支名称的引用。

在更改现有仓库的默认分支名称时，应通过重命名来保留默认分支的历史记录，而不是创建一个新分支。此示例重命名了 Git 仓库 (example) 的默认分支。

在本地命令行中，进入你的 example 仓库，并确保你在默认分支上：
```
cd example
git checkout master
```
将现有的默认分支重命名为新名称 (main)。参数 -m 会将所有提交历史转移到新分支：
```
git branch -m master main
```
将新创建的 main 分支推送到上游，并设置本地分支以跟踪具有相同名称的远程分支：
```
git push -u origin main
```
如果你计划删除旧的默认分支，请更新 HEAD 以指向新的默认分支 main：
```
git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main
```
使用至少具有维护者角色的帐户登录到极狐GitLab，并按照说明更改此项目的默认分支。选择 main 作为新的默认分支。
按照受保护分支文档中的描述保护新的 main 分支。
可选。如果你想删除旧的默认分支：
1. 验证没有任何内容指向它。
2. 删除远程上的分支：
```
 git push origin --delete master
```
  你可以在确认新的默认分支正常工作后再删除旧分支。
通知你的项目贡献者此更改，因为他们也必须采取一些步骤：
- 贡献者应将新的默认分支拉取到他们的本地仓库副本。
- 目标为旧默认分支的开放合并请求的贡献者应手动将合并请求重新指向 main。
在你的仓库中，更新代码中对旧分支名称的任何引用。
更新代码和脚本中对旧分支名称的引用，这些代码和脚本位于你的仓库之外，例如辅助工具和集成。

重命名默认分支重定向

项目中特定文件或目录的 URL 嵌入了项目的默认分支名称，通常出现在文档或浏览器书签中。当你更新仓库中的默认分支名称时，这些 URL 会更改，必须更新。

为了简化过渡期，每当项目的默认分支更改时，极狐GitLab 会记录旧默认分支的名称。如果该分支被删除，尝试查看其上的文件或目录时，将重定向到当前默认分支，而不是显示“未找到”页面。

故障排除

无法更改默认分支：重置为当前分支

我们正在议题 20474中跟踪此问题。当仓库中存在名为 HEAD 的分支时，通常会发生此问题。要解决此问题：

在你的本地仓库中，创建一个新的临时分支并推送它：
```
git checkout -b tmp_default && git push -u origin tmp_default
```
在极狐GitLab 中，继续更改默认分支为该临时分支。
从你的本地仓库中删除 HEAD 分支：
```
git push -d origin HEAD
```
在极狐GitLab 中，更改默认分支为你打算使用的分支。

查询 GraphQL 以获取默认分支

你可以使用 GraphQL 查询来检索组中所有项目的默认分支。

要在单个结果页面中返回所有项目，请将 GROUPNAME 替换为组的完整路径。极狐GitLab 返回结果的第一页。如果 hasNextPage 为 true，你可以通过将 after: null 中的 null 替换为 endCursor 的值来请求下一页：

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

新子组不会继承上级子组的默认分支名称

当你在包含另一个子组的子组中配置默认分支时，该默认分支不会被继承。

我们正在议题 327208中跟踪此问题。