How to handle a git branch rename in Multibranch jobs?

Article ID:360045669372
2 minute readKnowledge base

Issue

  • I would like to rename a Git branch and retain the original branch build history within Jenkins.

  • Example: "We are changing our master branch to be named main."

Environment

Resolution

1) Stop Jenkins or otherwise ensure the associated jobs are disabled.

2) Take backups:

  • Backup your $JENKINS_HOME. See our Backup and Restore Guide for further information.

  • Backup your repository. Ensure you have a full clone of the current state of your repository prior to making any changes. This page has a few options detailed for creating backups of your Git repository.

3) Modify the git branches both on your local and on the remote repository.

  • Rename (move) your old branch to the a new branch:

    • git branch -m <old_name> <new_name>

  • Change your default branch on your remote repository:

    • For example, in GitHub UI: {repository} -> Settings -> Branches -> Default Branch

  • Delete the old branch from remote:

    • git push <remote> --delete <old_name>

  • Push your new branch to remote:

    • git push <remote> <new_name>

  • Reset the upstream branch for the new branch name:

    • git push <remote> -u <new_name>

4) Modify relevant files in the $JENKINS_HOME directory

  • Navigate to the associated directory:

    • cd $JENKINS_HOME/jobs/<job_name>/branches

  • Rename the old branch folder name to the new branch name:

    • mv <old_name> <new_name>

  • Navigate into the new branch’s directory:

    • cd $JENKINS_HOME/jobs/<job_name>/branches/<new_name>

  • Modify the various config files associated with this branch’s builds:

  • vi config.xml

    • Swap instances of <old_name> with <new_name>

    • Ensure commit hash matches new branches latest commit hash

  • vi scm-last-seen-revision-hash.xml

    • Swap instances of <old_name> with <new_name>

    • Ensure commit hash matches new branches latest commit hash

  • vi scm-revision-hash.xml

    • Swap instances of with

    • Ensure commit hash matches new branches latest commit hash

5) Restart Jenkins

6) Run index scan for impacted Multibranch job

7) Verify your newly renamed branch contains your build history from before the rename.

References

This article is part of our Knowledge Base and is provided for guidance-based purposes only. The solutions or workarounds described here are not officially supported by CloudBees and may not be applicable in all environments. Use at your own discretion, and test changes in a safe environment before applying them to production systems.