Auto Update with Cron

See Updating Companion Hub for the manual update steps for each install method.

What updates itself

Hub has two parts that update separately:

The stack update pulls the new Hub image and recreates only the Hub container. It leaves the database and queue containers alone, and your app data, settings, and installed apps carry over.

flowchart LR
    R["New Hub release"] --> C["Daily check<br/>on the Hub"]
    C -->|"Auto-update stack on,<br/>release-pinned Hub"| S["Hub pulls the image and<br/>recreates the Hub container"]
    C -->|"Off, or on a channel<br/>such as dev or latest"| N["No change"]
    S --> K["App data, settings, and<br/>installed apps preserved"]
    R --> D["Notice in the desktop window<br/>or the Settings → System cards"]
    D --> Y["You: Settings → System,<br/>cihub update, or your package manager"]
    Y --> P["Updated desktop app"]
    CR["cron"] -. "cihub update --check<br/>can tell you one is waiting" .-> Y

Your installed apps

Hub never updates your installed apps by itself. On the Hub machine, cihub app update-all asks the running Hub to update every app that has a newer version, taking a backup of each one first. Run it by hand once before you schedule it: it needs the Hub running and the device key that Hub keeps in state/settings.json, so a cron job must run as the account that runs Hub. See Update an installed app.

Which Hubs update themselves

Auto-update moves only a Hub that is pinned to a release image, such as ghcr.io/companionintelligence/ci-hub:0.3.0, and it moves the pin to the newest stable release. It leaves every other Hub alone:

• A Hub on a channel tag — :dev, :staging, or :latest
• A Hub pinned to an image digest
• A Hub running a local build or an image from another registry

To move a Hub between channels, change CI_HUB_IMAGE in the Hub env file and recreate the Hub.

Turn auto-update off

Use either of these:

• In Settings → System, turn off Auto-update stack
• Set "autoUpdates": false in <ROOT_FOLDER_HOST>/state/settings.json. The value must be the JSON boolean false, not the string "false".

Hub reads the file at each check, so the change applies without a restart.

Updating the desktop app from a script

The desktop app is never updated without a person. Two commands help, but neither is a full cron-driven update:

cihub update --check

Prints a CLI and Hub stack box that names the cihub version and the Hub stack version side by side, then asks the desktop app whether a newer version exists. It exits with status 1 when an update is available. It also exits 1 when the desktop app isn’t installed on the machine, so a script can’t tell those cases apart from the exit code alone.

cihub update

Downloads and installs the new desktop app, then relaunches it. On Linux, the install step asks for administrator authorization, so it isn’t suited to an unattended cron job. On a machine with no desktop app, a standalone cihub binary runs cihub self-update instead, which needs a GH_TOKEN or GITHUB_TOKEN in the environment and only replaces the CLI, not the Hub stack. For a package-manager install, cihub update tells you the command for the channel your cihub came from, such as brew upgrade --cask companion-hub or scoop update companion-hub, and exits 1.

The cihub CLI and the Hub stack are separate updates, and a machine can sit on an old CLI while the stack moves ahead. cihub doctor shows the mismatch on its CLI vs stack line, and cihub version prints the CLI version followed by the running Hub build.

If an update fails

• <ROOT_FOLDER_HOST>/logs/hub-stack-update.log has one block per attempt. It ends with result=ok or result=failed.
• Settings → Logs records every refused update as Hub stack update refused: and every skipped daily check as Auto-update skipped:. It also records each update the daily check starts, as Auto-update: updating the Hub image only, from <old> to <new>, which is a reminder that the desktop app update is yours to make in Settings.