Release Branch in Git — what it is, purpose and workflow

What is a Release Branch in Git

Release Branch is a temporary branch in Git Flow, created from develop when the team decides that the current set of features is ready for release. It exists exactly as long as the final release preparation takes — from a few hours to a few days.

The main purpose of a release branch is to freeze a specific set of features for release without stopping development of subsequent versions. While the release branch is being prepared for deployment, other developers can continue merging feature branches into develop for the next release.

No new features are created in the release branch — only bug fixes, app version updates, localization, and documentation. After all work is complete, the release branch is merged into main (marked as a release) and back into develop (so bugfixes make it into future versions).

According to Atlassian, 2024, release branches are critically important for projects with regular release cycles — they ensure predictability and stability of the release process.

Release Branch Lifecycle

The lifecycle of a release branch from creation to deletion includes several stages. Understanding each stage helps the team synchronize actions and avoid mistakes.

1. Creation — a branch named release/2.5.0 is created from the latest develop commit. develop continues accepting feature branches for the next version.
2. Preparation — the app version is updated in build.gradle, Info.plist, and other configuration files on the release branch.
3. Bugfixing — critical errors found during final testing are fixed. Only bugs — no new features.
4. Final testing — the QA team conducts regression testing on the release branch. New bugs are sent for fixing in the same branch.
5. Merge into main — the release branch is merged into main with the --no-ff flag. A release tag is created: v2.5.0.
6. Merge into develop — the release branch is merged back into develop so that bugfixes from the release make it into current development.
7. Deletion — the release branch is deleted locally and remotely since its task is complete.

Step 6 — merge back into develop — is often forgotten but critically important. Without it, bugfixes made in the release branch won't reach develop, and the same errors may reappear in the next release.

Typical Durations of Release Branch Stages

The lifespan of a release branch depends on release complexity and code quality in develop. On average, preparation takes 2 to 5 working days for a medium-sized mobile application.

What Happens in a Release Branch

A strictly limited set of tasks is performed in the release branch. Any deviation from this list violates the Git Flow model and creates risks for release stability.

The no new features rule is the most important one in a release branch. If a feature didn't make it for the release, it waits for the next cycle. Trying to push an unfinished feature into the release branch is the main cause of missed deadlines and production bugs.

Updating Version in a Mobile Project

The app version number must be updated in the release branch. For Android, these are the versionCode and versionName fields in build.gradle; for iOS — CFBundleShortVersionString in Info.plist.

// build.gradle (app-level) — updating version in release branch
android {
    defaultConfig {
        versionCode 42
        versionName "2.5.0"
    }
}

// For iOS — updating Info.plist
// CFBundleShortVersionString = 2.5.0
// CFBundleVersion = 42

Release vs Hotfix Differences

Beginner developers often confuse release and hotfix branches, although their purpose is fundamentally different. Choosing the wrong branch type can delay a critical fix or disrupt the release process.

• Source — release is created from develop, hotfix from main. This is the main difference that determines everything else.
• Urgency — release is planned: the team decides when to start preparation. Hotfix is urgent: a production problem requires immediate fixing.
• Content — release may include multiple fixes and a version update. Hotfix contains only one critical fix.
• Merge — release merges into main and develop. Hotfix also merges into main and develop, but as a priority.
• Lifespan — release lives from 1 to 7 days. Hotfix lives from 30 minutes to 1 day.

If a bug is found during release preparation (in the release branch) — it's a regular bugfix. If a bug is found in production (on main) — it's a hotfix, and it's created from main, even if a release branch already exists.

Release Branch Naming Conventions

A unified release branch naming standard simplifies repository navigation and allows CI/CD systems to automatically detect that a branch belongs to the release process.

• release/X.Y.Z — standard Git Flow format, where X.Y.Z is the release version. Example: release/2.5.0.
• release/name — alternative format with a release codename. Example: release/merlin.
• release/date — format with the release date. Rarely used since version is more important than date. Example: release/2024-12-01.

The release/X.Y.Z format is preferred because it explicitly links the branch to the version number that will be assigned to the release. This simplifies searching and automatic processing by CI/CD scripts.

Merge Back Strategy into develop

Merge back of the release branch into develop is one of the most important and simultaneously most frequently skipped operations. Without it, all bugfixes made in the release branch remain only in the release version and won't make it into the next release cycle.

The merge back process is performed after the release branch has already been merged into main. First, release is merged into develop, then deleted. This guarantees that develop contains all fixes made during release preparation.

After merge back, conflicts may occur — especially if new feature branches that modified the same files have already appeared in develop. The developer responsible for the release resolves these conflicts and pushes develop to the server.

Some teams use rebase instead of merge for back merging to keep the history linear. However, merge is safer for develop because it doesn't rewrite the commit history that may already be used by other developers.

Example Commands for Working with Release

Let's look at the full release branch workflow: from creation to deletion after a successful release of a mobile application version 2.5.0.

# 1. Create release branch from develop
git checkout develop
git pull origin develop
git checkout -b release/2.5.0

# 2. Update version and bugfixes
git add build.gradle
git commit -m "Bump version to 2.5.0"

# 3. Fix bugs (bugfixes only)
git add src/fix/
git commit -m "Fix crash on payment screen"

# 4. Push release branch to server
git push origin release/2.5.0

# 5. Merge release into main
git checkout main
git pull origin main
git merge --no-ff release/2.5.0
git tag -a v2.5.0 -m "Release 2.5.0"
git push origin main --tags

# 6. Merge back into develop
git checkout develop
git merge --no-ff release/2.5.0
git push origin develop

# 7. Delete release branch
git branch -d release/2.5.0
git push origin --delete release/2.5.0

Commands 5 and 6 — the double merge — are critically important. First, main receives the release code and tag, then develop synchronizes with bugfixes from the release. If step 6 is skipped, fixes from the release won't make it into the next development cycle.

Automating the Release Process

For mobile projects with regular releases, the process of creating a release branch and updating the version can be automated via CI/CD scripts. GitHub Actions allows creating a workflow that creates a release branch with automatic version update at the click of a button.

For mobile projects with regular releases, the process of creating a release branch and updating the version can be automated via CI/CD scripts. GitHub Actions allows creating a workflow that creates a release branch with automatic version update at the click of a button.

# GitHub Actions — automating release branch creation
name: Create Release Branch

on:
  workflow_dispatch:
    inputs:
      version:
        description: 'Release version (e.g. 2.5.0)'
        required: true

jobs:
  create-release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Create release branch
        run: |
          git checkout develop
          git checkout -b release/${{ inputs.version }}
          git push origin release/${{ inputs.version }}