Skip to content

Self-Hosted Server Release Runbook

This document describes the process for releasing Appcircle Server (self-hosted) and rolling the release out to deploy branches, documentation, and customer-facing channels.

Overview

  • Release flow: PR reviews and release work run on the release branch.
  • Release candidates: Release candidates are built from the release branches too. So, we can test the release candidates in the self-hosted test environment (https://my.self.appcircle.io).
  • Convergence point: Master is the single meeting point for release and deploy branches. All deploy branches are based from master.
  • Deploy branches: Each customer or environment has a deploy/<name> branch. After a release, you update these branches by merging master (and handling hotfixes as below).

Pre-Release Local Verification

After a version is released (e.g. 3.29.6), run a local instance and confirm on the master branch:

Check What to verify
Version Displayed version matches the release (e.g. 3.29.6).
Hotfixes Any expected hotfixes are included; none missing or unintended.
Docker images In the docker-images.txt, all relevant images are on latest except the hotfix tags.
Image Tags Image tags are correct for the release (e.g. 3.29.6) in the ./config/compose.yaml.tmpl and ./config/dmz/compose.yaml.tmpl files.

Fix any mismatch before proceeding to deploy-branch updates and customer communication.

Deploy Branch Update Workflow

Backend will signal when a release is ready to be distributed to customers (e.g. “3.29.6 released, you can distribute to customers”). Then:

  1. Process branches one by one: Switch to each deploy branch and update it; do not batch.
  2. Revert hotfixes that were applied only on that deploy branch. Do not revert hotfixes that are already part of master (i.e. that came with the release).
  3. Merge master into the deploy branch: 
    git merge master
  4. Resolve conflicts if any, then push.

Listing deploy branches (by last commit date)

Pull the latest master branch:

git checkout master && \
git pull

To see deploy branches and their latest commit (handy when deciding order or checking state):

git for-each-ref \
  --sort=-committerdate \
  --format='%(committerdate:iso8601)|%(refname:short)|%(objectname:short)|%(subject)' \
  refs/heads refs/remotes \
| grep deploy | grep -v "origin/" \
| head -n 20 \
| column -t -s '|'

Current customer deploy branches:

2026-02-12 14:05:22 +0300  deploy/cloud-providers                        7f62be91  Merge branch 'master' into deploy/cloud-providers
2026-02-12 14:02:33 +0300  deploy/ziraatteknoloji                        5fc56fde  Merge branch 'master' into deploy/ziraatteknoloji
2026-02-12 13:58:36 +0300  deploy/teb                                    e27d56f0  Merge branch 'master' into deploy/teb
2026-02-12 13:58:24 +0300  deploy/ptt                                    c336d5a4  Merge branch 'master' into deploy/ptt
2026-02-12 13:58:14 +0300  deploy/oregon-ha                              d7b9d51c  Merge branch 'master' into deploy/oregon-ha
2026-02-12 13:58:03 +0300  deploy/kkb-prod                               82ddca57  Merge branch 'master' into deploy/kkb-prod
2026-02-12 13:57:45 +0300  deploy/kkb                                    1ffc51c4  Merge branch 'master' into deploy/kkb
2026-02-12 13:57:22 +0300  deploy/intertech-test                         2fda8f58  Merge branch 'master' into deploy/intertech-test
2026-02-12 13:57:07 +0300  deploy/intertech-prod                         3cfed5b1  Merge branch 'master' into deploy/intertech-prod
2026-02-12 13:56:37 +0300  deploy/gib                                    1ed23a87  Merge branch 'master' into deploy/gib
2026-02-12 13:56:18 +0300  deploy/anadolu-sigorta                        8c8d080a  Merge branch 'master' into deploy/anadolu-sigorta
2026-02-12 13:55:58 +0300  deploy/alternatif-bank                        6f3bd58a  Merge branch 'master' into deploy/alternatif-bank
2026-02-12 13:55:41 +0300  deploy/albaraka-tech                          1af8fa63  Merge branch 'master' into deploy/albaraka-tech
2026-02-12 13:54:07 +0300  deploy/halkbank-chmod-400-hotfix-3.29.8       b402cc46  Merge branch 'master' into deploy/halkbank-chmod-400-hotfix-3.29.8
2026-02-12 13:53:15 +0300  deploy/halkbank-test-chmod-400-hotfix-3.29.8  c4249c5c  Merge branch 'master' into deploy/halkbank-test-chmod-400-hotfix-3.29.8
2025-12-26 09:38:49 +0300  deploy/halkbank-test-chmod-400-hotfix-3.29.4  3f4a035b  increase storage size to 5TB
2025-12-25 23:34:17 +0300  deploy/halkbank-chmod-400-hotfix-3.29.4       b790db7a  Upgrade license
2025-12-24 16:47:47 +0300  deploy/halkbank-test-chmod-400-hotfix         28bc83a7  Merge branch 'master' into deploy/halkbank-test-chmod-400-hotfix
2025-12-24 16:47:07 +0300  deploy/halkbank-chmod-400-hotfix              d1c3ab79  Merge branch 'master' into deploy/halkbank-chmod-400-hotfix

The “main” branch for a given customer may be a dedicated deploy branch (e.g. deploy/halkbank-test-chmod-400-hotfix). Use the same workflow: revert branch-only hotfixes, then merge master.

All ine one function for updating a deploy branch (in bash or zsh). Save this function in the ~/.bashrc or ~/.zshrc file and source it.

update_deploy_branch() {
    local branch_name="$1"

    # 1. Validate input
    if [ -z "$branch_name" ]; then
        echo "Error: No branch name provided."
        return 1
    fi

    # 2. Execute logic with strict exit on failure (set -e equivalent)
    git checkout "$branch_name" && \
    git pull && \
    if git --no-pager log -1 --pretty=format:"%B" | grep -q "Merge branch 'master' into"; then
        echo "Latest commit is master branch merge. No need to revert a hotfix."
    fi && \
    git merge master --no-edit && \
    git push
}

Then, you can update a deploy branch with:

update_deploy_branch "deploy/customer-name"

Customer-Specific Hotfix on an Older Version

If a customer needs a hotfix on an older version (not on current master):

  1. Check out that customer’s deploy branch.
  2. Reset the commit that corresponds to the previous version (before the release you don’t want to include).
  3. Apply the hotfix on top of that state.
  4. Push as a new branch (e.g. deploy/customer-name-hotfix-description). Do not force-push over the main deploy branch unless that’s the agreed process.

Cloud Providers Deploy Branch

Do not forget to maintain the cloud providers deploy branch (e.g. deploy/cloud-providers) with the same workflow: revert deploy-only hotfixes, then git merge master, and push.

Documentation (Update Server Page & Release Notes)

Version History and Update Server page

  • Version History: Keep the version history table up to date. If a version was not released for self-hosted (e.g. 3.29.5 was skipped and 3.29.6 is the next self-hosted release), use – or “N/A” for that row.
  • Release date: Use the self-hosted release date, not the cloud/SaaS release date.
  • Update server page: Keep the “Update server” / “Version history” content in sync with the actual self-hosted releases.

Docusaurus and release notes

  • Open a Docusaurus pull request with the documentation changes (version history, update server page, etc.).
  • Send the PR to Sarp for review.
  • Sarp will open/publish the release note tags for the self-hosted release (e.g. 3.29.6) so they appear in the release notes.

Zendesk & CSM (“Waiting for Self-Hosted Release”)

  • CSM: Notify that the self-hosted release is done and customers can now update. They will handle the Zendesk tickets.
  • Zendesk tickets in “waiting for self-hosted release” can be moved to the next step once the release is done.
  • CSM may wait for the release note and version history to be published; we must ping them when the doc/PR is ready so they can communicate to customers.

Linear: Issue Status Updates

  • In Linear, find issues that are in “Waiting for self-hosted deployment” (or equivalent) and update them to “Deployed to self-hosted” (or the correct “released” state) after the release is rolled out.

Version-Specific Notes (Examples)

Some releases have one-off rules.

Example (3.14.0):

Users should make a MinIO migration while updating to 3.14.0. Check the MinIO migration caution in the update document and it's own MinIO migration documentation.

Example (3.29.6):

The Appcircle server container images are hardened.

When in doubt, check release notes, Linear, or the team before publishing or pinging customers.