Configure a supported tracking branch to get Discourse software updates

[Discourse]

This guide explains how to configure a supported tracking branch for your Discourse instance to manage software updates.

Required user level: System Administrator

Console access is required.

Managing your Discourse instance’s tracking branch determines the frequency and type of updates you receive. This guide explains the different tracking branches available and provides a step-by-step approach to changing the branch on your setup.

Summary

Discourse offers several branches and tags for tracking software updates: latest, release, and esr. This documentation explains the purpose of each, their key features, and how to configure them in your Discourse instance. For full details on the release model, see RFC: A new versioning strategy for Discourse.

Supported branches

latest

Recommended Default
This branch provides the latest bug fixes and compatibility updates for plugins. Every passing commit from the main branch is tested by the build server and added to the latest branch after successful verification.

• Suitable for sites that want to stay up to date.
• Sites can update manually at any time.

release

For Sites That Prefer Monthly Releases

The release tag tracks the most recent monthly release of Discourse. Each month, a release branch (e.g. release/2026.2) is cut from latest, providing a stable snapshot.

• Released approximately once per month.
• Each release receives critical fixes for two full release cycles.

esr

Extended Support Release

The esr tag tracks the latest Extended Support Release, intended for sites prioritizing long-term stability and security over frequent updates.

• Declared approximately every 6 months from the monthly releases.
• Receives security fixes and critical backports for an extended period.
• May have limited compatibility with community plugins and theme components.

Note: Not receiving regular maintenance updates can leave some features outdated or visually inconsistent.

Deprecated aliases

For backwards compatibility, the following old branch/tag names still work but are considered deprecated:

• tests-passed → latest
• beta → release
• stable → esr

Other branches or references

Tracking other branches (e.g., specific release/YYYY.M branches or commit SHAs) is possible but requires expertise. These branches only receive critical fixes for a limited period.

Instructions for configuring your tracking branch

Follow these steps to configure the desired branch in your Discourse instance:

1. Access the configuration file
   Open the app.yml configuration file by running the following commands in your console:

cd /var/discourse
git pull
nano containers/app.yml

The nano editor will open the configuration file.
2. Edit the tracking branch
Locate the version parameter by searching for the word “version” in the file:

params:  
## Which Git revision should this container use? (default: latest)  
#version: latest

• Uncomment the version line.
• Replace latest with your desired branch or tag name (e.g., esr).Example:

params:  
## Which Git revision should this container use? (default: latest)  
version: esr  

3. Save and exit

• Press Ctrl+O to save your changes.
• Press Enter to confirm.
• Use Ctrl+X to exit the editor.

4. Rebuild the container
   Once the changes are made and saved, rebuild the container to apply the new configuration:

git pull
./launcher rebuild app

This process might cause temporary downtime. Ensure to update the instance during non-working hours if possible.

Last edited by @mcwumbly 2025-09-29T13:24:13Z

Check document

Perform check on document:

[RBoy]

Something doesn’t appear to be right here. I was running v3.5.0 beta3 with the yml set to version: tests-passed

Then I noticed this versioning change so before rebuilding I changed the yml to version: esr and then did a rebuild from the CLI.

Now in discourse I see

Installed
2026.3.0-latest.1

This appears to be using the tests passed tag instead of the esr tag. I verified that app.yml is showing the version as esr , so why it it grabbing the latest build ?