Configure a supported tracking branch to get Discourse software updates

Documentation Self-Hosting
1

This guide describes how to change tracking branch for your Discourse instance, which determines how frequently updates are available to deploy and how you receive notifications about these updates.

Supported branches

tests-passed

:information_source: Tracking tests-passed is the recommended default to stay up to date with the bug fixes and remain compatible with the latest plugin versions.

When a new commit is pushed to the main branch, our build server automatically runs all our tests against the latest code. Once they all pass the commit is added to our tests-passed branch.

Sites will only be notified about available updates when a new beta version is available, but can update at any time to get the latest commits.

stable

:information_source: Tracking stable is an option for sites that value limiting change and which can tolerate known issues and only wish to receive security fixes between new releases.

Every 4-6 months we release a new stable build. Afterwards, this branch only receives updates for security fixes; bug fixes and other changes are not backported to stable, and community plugins and theme components may not maintain compatibility.

~2 weeks before pushing stable we release our last beta. We then watch closely to try and catch any lingering bugs that exist, and avoid adding any new features/risky changes. Once we’re satisfied with the state of the current beta, we push to stable.

beta

:information_source: Tracking beta is rarely preferred, as tracking tests-passed is recommended for sites that value staying up to date, and tracking stable is recommended for sites that wish to limit change.

Every few weeks we push the current commits on tests-passed to beta. We use beta as a “milestone” to notify sites on tests-passed or beta that a new collection of commits is available.

We also push a beta if we have an important security fix we want sites to receive. When a beta is pushed all sites running on tests-passed or beta receive the “new update available” email. Sites running tests-passed will update to the current tests-passed commits (including any new commits pushed after the beta), while those on beta will not.

Other branches or references

:warning: We do not recommend tracking any branches other than those listed above.

You can configure any other branch name or git reference as the version, but doing so is generally not recommended unless you know what you’re doing.

Steps to configure your tracking branch

Open configuration file app.yml. From console, run these commands:

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

Configuration file will open in nano editor. Search for version (with Ctrl+W) in the file:

params:
  ## Which Git revision should this container use? (default: tests-passed)
  #version: tests-passed

Uncomment the version line and change tests-passed to your preferred branch (e.g. stable):

You can also set it to a specific git SHA if you need to pin the version to a particular commit.

params:
  ## Which Git revision should this container use? (default: tests-passed)
  version: stable

After completing your edits, press Ctrl+O then Enter to save and Ctrl+X to exit.

Rebuild the container:

git pull
./launcher rebuild app

Last Reviewed by @mcwumbly on 2022-09-30T09:40:00Z

25 Likes