Managing tools in the portal

Tool distribution delivers nullctl, its plugins and tenant images to your tenant. Everything you can do with nullctl tools has a place in the portal, or the portal shows you the command to run.

What to expect

Each tool follows a channel: stable (default), beta or edge. New releases land on edge first and reach stable only when Null Autos promotes them. Your tenant's upgrade policy decides what happens when the channel moves:

Policy	What happens
notify (default)	Nothing changes until a tenant admin adopts the new version. nullctl prints one line a day, for example update available: nullctl 1.4.0; run `nullctl tools update` .
auto	The tenant adopts the new version on its own, after the optional hold days have passed. nullctl downloads it in the background and swaps it in on the next run (nullctl updated 1.3.2 -> 1.4.0). Rollbacks of the channel apply immediately.
manual	Nothing changes and nothing is printed until you act.

Whatever the policy, a tool you install for the first time gets the current channel release, and a release that no longer fits the adopted nullctl (a plugin's requires) is moved to one that does.

Everyone in the tenant moves to the adopted version, newer or older. Adopting an older release is how you roll back.

Updating

On your machine:

nullctl tools status            # what is adopted and available
nullctl tools update            # nullctl and installed plugins
nullctl tools update --check    # report only
nullctl tools plugins install infra
nullctl tools plugins update

nullctl tools update moves each tool to the version your tenant adopted, checks its checksum and signature, and keeps the previous binary as <name>.old. It never replaces a nullctl inside a container image or in a directory it cannot write; it prints what to do instead. Set NULLCTL_NO_UPDATE_CHECK=1 to silence the daily check.

A plugin that needs a newer nullctl refuses to start and says so:

nullctl-infra 0.3.0 requires nullctl >= 1.4.0 but 1.3.2 is installed; run `nullctl tools update` or see `nullctl tools status`

To change versions for the whole tenant, a tenant admin adopts a release (below, or nullctl tools adopt <tool> [version]); members then pick it up with nullctl tools update.

In your pipelines

Your GitLab group's CI variable NULLCTL_IMAGE always points at the adopted nullctl image, pinned by digest and mirrored into your own registry, and other image tools get NULL_TOOL_IMAGE_<TOOL>. Jobs that use image: $NULLCTL_IMAGE follow your adoptions without edits. Don't edit these variables by hand: they are reset within minutes.

Overview

Organization > Tools lists every tool your tenant can receive, with its channel, upgrade policy, adopted and available versions, status and who adopted it. Filter by All / CLI / Plugins / Images, and select a tool name to open its page. Statuses:

Status	Meaning
Current	Running the version the channel offers.
Update available	A newer release is on the channel. Adopt it.
Rollback available	The channel head is older than what is adopted.
Ahead of channel	Adopted is newer than the channel head. Nothing to do.
Pinned	Held at one version; the channel is ignored until you unpin.
Incompatible	The available release conflicts with other adopted tools.

Tenant defaults (channel, policy, hold days, mirroring) and per-tool overrides are edited here too (CLI: nullctl tools config).

Tool page

/org/tools/<tool> shows the tool's effective settings, adoption details and mirror reference, plus the release history (CLI: nullctl tools releases <tool>). Each release shows its state, publish date, the channels pointing at it, requirements, artifact count and expandable release notes.

Tenant admins can:

• Adopt any published release (CLI: nullctl tools adopt <tool> [version]). Adopting an older version is a rollback; clients following notify or manual move back on their next nullctl tools update.
• Pin a release, or Unpin (CLI: nullctl tools config set --pin/--unpin).
• Edit override for the tool's channel, policy and mirroring.

Members see the same information read-only.

On your machine

Installing and updating run locally, so the portal gives copyable commands instead: nullctl tools update, nullctl tools plugins install <name> and nullctl tools plugins update. The tool page lists the ones that apply.

Plugins

The Install nullctl page lists the plugins available to your tenant with the install command for each, for example nullctl tools plugins install infra for nullctl-infra.

---

Last updated: 2026-10-22 · commit d04d27b (dirty)