doc/user/project/repository/branches/default.md
{{< details >}}
{{< /details >}}
When you create a new project, GitLab creates a default branch in the repository. A default branch has special configuration options not shared by other branches:
The name of your new project's default branch depends on any configuration changes made to your instance or group by your GitLab administrator. GitLab checks first for specific customizations, then checks at a broader level, using the GitLab default only if no customizations are set:
main.In the GitLab UI, you can change the defaults at any level. GitLab also provides the Git commands you need to update your copy of the repository.
Prerequisites:
To update the default branch for an individual project:
You can also use the default_branch attribute of the projects API.
When you create a project with the API and set initialize_with_readme to true,
you can specify the default_branch parameter as either:
main.refs/heads/main.The API strips the refs/heads/ prefix if you provide a fully qualified reference.
{{< details >}}
{{< /details >}}
Administrators of GitLab Self-Managed can customize the initial branch for projects hosted on that instance. Individual groups and subgroups can override the instance default for their projects.
Projects created on this instance after you change the setting use the custom branch name, unless a group or subgroup configuration overrides it.
Prerequisites:
To change the default branch name for new projects in a group:
Projects created in this group after you change the setting use the custom branch name, unless a subgroup configuration overrides it.
{{< details >}}
{{< /details >}}
{{< history >}}
{{< /history >}}
GitLab administrators and group owners can define branch protections to apply to every repository's default branch for the instance, or for individual groups, with one of these options:
[!warning] Unless Fully protected is chosen, a malicious developer could attempt to steal your sensitive data. For example, a malicious
.gitlab-ci.ymlfile could be committed to a protected branch and later, if a pipeline is run against that branch, result in exfiltration of group CI/CD variables.
{{< details >}}
{{< /details >}}
This setting applies only to each repository's default branch. To protect other branches, you must either:
Administrators of GitLab Self-Managed instances can customize the initial default branch protection for projects hosted on that instance. Individual groups and subgroups can override the instance default setting for their projects.
{{< details >}}
{{< /details >}}
Group owners can override protections for default branches set for an entire instance on a per-group basis. In GitLab Premium or Ultimate, GitLab administrators can disable this privilege for group owners, enforcing the protection rule set for the instance:
[!note] GitLab administrators can still update the default branch protection of a group.
{{< details >}}
{{< /details >}}
Group owners can override protections for default branches set for an entire instance on a per-group basis. In GitLab Premium or Ultimate, GitLab administrators can enforce protection of initial default branches which locks this setting for group owners.
[!warning] Changing the name of your default branch can potentially break tests, CI/CD configuration, services, helper utilities, and any integrations your repository uses. Before you change this branch name, consult with your project owners and maintainers. Ensure they understand the scope of this change includes references to the old branch name in related code and scripts.
When you change the default branch name for an existing repository, don't create a new branch.
Preserve the history of your default branch by renaming it. This example renames a Git repository's
(example) default branch:
On your local command line, go to your example repository, and ensure
you're on the default branch:
cd example
git checkout master
Rename the existing default branch to the new name (main). The argument -m
transfers all commit history to the new branch:
git branch -m master main
Push the newly created main branch upstream, and set your local branch to track
the remote branch with the same name:
git push -u origin main
If you plan to remove the old default branch, update HEAD to point to your new default branch, main:
git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main
Sign in to GitLab with at least the Maintainer
role and follow the instructions to
change the default branch for this project.
Select main as your new default branch.
Protect your new main branch as described in the protected branches documentation.
Optional. If you want to delete the old default branch:
Verify that nothing is pointing to it.
Delete the branch on the remote:
git push origin --delete master
You can delete the branch at a later time, after you confirm the new default branch is working as expected.
Notify your project contributors of this change, because they must also take some steps:
main instead.In your repository, update any references to the old branch name in your code.
Update references to the old branch name in related code and scripts that reside outside your repository, such as helper utilities and integrations.
URLs for specific files or directories in a project embed the project's default branch name, and are often found in documentation or browser bookmarks. When you update the default branch name in your repository, these URLs change, and must be updated.
To ease the transition period, whenever the default branch for a project is changed, GitLab records the name of the old default branch. If that branch is deleted, attempts to view a file or directory on it are redirected to the current default branch, instead of displaying the "not found" page.
We are tracking this problem in issue 20474.
This issue often occurs when a branch named HEAD is present in the repository.
To fix the problem:
In your local repository, create a new temporary branch and push it:
git checkout -b tmp_default && git push -u origin tmp_default
In GitLab, proceed to change the default branch to that temporary branch.
From your local repository, delete the HEAD branch:
git push -d origin HEAD
In GitLab, change the default branch to the one you intend to use.
You can use a GraphQL query to retrieve the default branches for all projects in a group.
To return all projects in a single page of results, replace GROUPNAME with the
full path to your group. GitLab returns the first page of results. If hasNextPage
is true, you can request the next page by replacing the null in after: null
with the value of endCursor:
{
group(fullPath: "GROUPNAME") {
projects(after: null) {
pageInfo {
hasNextPage
endCursor
}
nodes {
name
repository {
rootRef
}
}
}
}
}
When you configured a default branch in a subgroup that contains another subgroup that contains a project, the default branch is not inherited.
We are tracking this problem in issue 327208.