Switching between Discourse release channels / versions

[Discourse]

This guide explains how to configure the release channel of your Discourse instance.

Required user level: System Administrator

Console access is required.

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

Summary

Discourse offers several channels 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 an illustration of the channels, see releases.discourse.org.

Supported channels

latest

Recommended Default
This channel 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 channel 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 channel

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
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:

./launcher rebuild app

Rebuilding will cause temporary downtime

Last edited by @david 2026-08-03T13:03:06Z

Check document

Perform check on document:

[ghorbani (Aref)]

@Discourse

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

Is git pull a necessary step, or is it redundant and remains from the legacy documentation, similar to the case of updating Discourse (Manually update Discourse and Docker image to latest )?

[merefield (Robert)]

In my experience git pull is occasionally useful - e.g. a must have when we switched from yarn to pnpm …

Normally you don’t need to bother for a regular rebuild.

[ghorbani (Aref)]

Good to know! Thank you for the info.

[merefield (Robert)]

what I usually do is try to rebuild, and if it fails for some not-so-obivous reason give git pull a go first - takes a moment.

[david (David Taylor)]

In theory it should never be needed. Launcher will automatically detect an out-of-date copy, and do the git pull itself:

launcher

[ghorbani (Aref)]

Thank you for the details. Indeed, it makes sense. I’ll give it a shot without git pul and let you know how it turns out.

[Ed_S]

That’s weird. The code in question dates from 2015, my forum dates from 2018, and yet I’m pretty sure there have been several instances discussed here where git pull was needed.

For myself, I will always git pull, if I remember - it costs me nothing.

[david (David Taylor)]

It does get mentioned a lot, I think because of these very-historic documents. I don’t think I’ve ever seen evidence of it actually helping.

But yes, there’s no harm in running it manually as well

[Ed_S]

@Discourse

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

As the yml file uses version and not supported tracking branch would it be good to add (version) to the topic title?

[ghorbani (Aref)]

I was also a bit shocked by the date at first. But checking the version history, the latest update is May 18.

[david (David Taylor)]

I made a pass on updating the OP to use our modern “channel” terminology, and remove some of the unnecessary git pull references.

[merefield (Robert)]

There must be at least an edge case because it’s definitely “got me over the hump” on very rare occasions

Could it be when the main script changes in limited circumstances?