Skip to content

feat: warn when src-cli is older than the instance's recommended version - #1403

Merged
marcleblanc2 merged 6 commits into
mainfrom
marc/version-check-warning
Nov 10, 2026
Merged

marcleblanc2 merged 6 commits into
mainfrom
marc/version-check-warning

Conversation

@marcleblanc2

@marcleblanc2 marcleblanc2 commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Closes #930. An alternative to #1347: this branch keeps @Montana's commit from #1347 and fixes it on top.

src now warns on stderr when it is older than the version your instance recommends (/.api/src-cli/version, the same lookup src version does):

⚠️  Warning: src-cli 6.4.1 is older than 7.6.0, the version recommended by https://sourcegraph.example.com. To upgrade, see https://github.com/sourcegraph/src-cli#installation. To silence this warning, set SRC_SKIP_VERSION_CHECK=1.

How it works

  • The check runs once per process from config.apiClient, so it uses the command's own endpoint and flags, such as -insecure-skip-verify. Commands that never talk to the instance, such as src search -h, do no lookup.
  • The recommended version is cached for 24 hours per endpoint, in a file under os.UserCacheDir()/sourcegraph/src-cli/. Failed lookups are cached too.
  • The lookup has a 3 second timeout and never fails the command.
  • src version always asks the instance, as before. It now warns from that answer and writes it to the cache, so the commands that follow warn about the same version. It still makes one request, and src version -client-only makes none.
  • There is no check for dev builds, or when SRC_SKIP_VERSION_CHECK is set.

Fixes on top of #1347

  • Panic. feat: warn when src-cli is older than the instance's recommended version #1347 built its client from &api.Flags{}, which internal/api dereferences, so every command in a release build crashed. Dev builds skip the check, which hid it.
  • Wrong instance. The check ran before flag.Parse(), so it ignored -endpoint, -config, and -insecure-skip-verify.
  • A request on every command. There was no cache, so an instance that does not answer delayed every command by 3 seconds.
  • src version and src search version skipped the check. src version now warns from its own lookup, and arguments are no longer scanned for version.
  • Version parsing now uses Masterminds/semver instead of a hand-written parser. It is already linked in through sourcegraph/lib; go.mod moves it from indirect to direct.
  • Tests now run the real API client against a fake instance. feat: warn when src-cli is older than the instance's recommended version #1347 tested only the helper functions.
  • Docs. A CHANGELOG.md entry. The warning itself names SRC_SKIP_VERSION_CHECK and links to the upgrade instructions.

Decisions to review

  • The check is a side effect of config.apiClient, the one place where the endpoint and a command's parsed flags meet.
  • The warning prints on every command while src is outdated, including in CI and when stderr is not a terminal.
  • A prerelease such as 7.4.0-rc.0 is warned when the instance recommends 7.4.0.
  • A failed lookup silences the check for 24 hours. That includes a command run against a self-signed instance without -insecure-skip-verify.
  • Without a writable cache directory there is no check.

Test plan

go test -race ./cmd/src and ./dev/go-lint.sh ./cmd/src/... pass.

Real instance. Built this branch with BuildTag set to 6.4.1 and to 7.6.0, and ran both against sourcegraph.sourcegraph.com, which recommends 7.6.0:

Run Result
src version (6.4.1) Prints Recommended version: 7.6.0 or later, then one warning on stderr
src version (7.6.0) No warning
src version -client-only (6.4.1) No warning
src repos list -first 1 (6.4.1, legacy command) One warning on stderr; the command succeeds
src api -query '...' (6.4.1, urfave/cli command) One warning on stderr; the command succeeds
src search -json '...' (6.4.1) One warning on stderr; stdout is still valid JSON
SRC_SKIP_VERSION_CHECK=1 src repos list -first 1 (6.4.1) No warning
src repos list -first 1 (7.6.0, same cache file) No warning
src repos list -h (6.4.1) No warning
SRC_ENDPOINT set to a dead endpoint, src -endpoint=<instance> repos list -first 1 (6.4.1) One warning that names the -endpoint instance; the command succeeds

Local fake instance, only for what the real instance cannot show: request counts, a changing answer, an untrusted certificate, and an instance that hangs. Built as 6.4.1; the fake recommends 6.5.0:

Run Result
src repos list, then src users list One request to /.api/src-cli/version, from the first command
src version on an empty cache One version request
src version -client-only No version request
Fake changes its answer to 99.0.0, then src repos list Still warns about the cached 6.5.0; no version request
Then src version, then src repos list Both warn about 99.0.0; one version request, from src version
Self-signed instance, src users list -insecure-skip-verify One warning
Self-signed instance, src users list Certificate error from the command, no warning
Instance that never answers the version lookup, src users list twice 3.02 s the first time, 0.02 s the second

Montana and others added 2 commits November 9, 2026 17:33
Before running a command, src does a best-effort check of the running version against the version recommended by the configured instance (/.api/src-cli/version) and prints a single stderr warning when behind. Fail-open, 3s timeout, stderr only so --json is unaffected. Skips version/help/no-arg, dev builds, and SRC_SKIP_VERSION_CHECK. Compares major/minor/patch only. Adds unit tests. Closes #930. Supersedes #1339, #1343.
- Fix a nil pointer panic on every command in release builds: the check
  built its API client from a zero-value api.Flags.
- Run the check after flags and config are resolved, so -endpoint and
  -config are honored and the right instance is asked.
- Ask the instance at most once every 24 hours per endpoint, caching the
  answer, including a failed lookup, under the user cache directory, so
  an instance that does not answer cannot delay every command.
- Compare versions with Masterminds/semver, which is already linked into
  the binary, instead of a hand-written parser.
- Skip 'src version' by its parsed subcommand instead of scanning every
  argument for the word.
- Test the check end to end against a fake instance.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1c29c-9f51-7761-a4ba-4d4f46dcd4ef
Co-authored-by: Amp <amp@ampcode.com>
@github-actions

github-actions Bot commented Nov 9, 2026 •

Copy link
Copy Markdown

marcleblanc2 and others added 4 commits November 9, 2026 17:56
The check ran before the subcommand's flags were parsed, so it ignored
-insecure-skip-verify and never warned on instances with an untrusted
certificate. It also ran twice for nested legacy commands such as
'src repos list', which printed the warning twice.

Run it once per process from config.apiClient instead, using the client
the command asked for. Commands that never talk to the instance, such as
'src search -h', no longer trigger a lookup.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1c29c-9f51-7761-a4ba-4d4f46dcd4ef
Co-authored-by: Amp <amp@ampcode.com>
'src version' was the one command that never warned. It now prints the
warning from the answer it just got from the instance, and caches that
answer, so the commands that follow warn about the same version.

It still makes a single request, and 'src version -client-only' still
makes none: the check that other commands get from config.apiClient
keeps skipping 'src version'.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1c29c-9f51-7761-a4ba-4d4f46dcd4ef
Co-authored-by: Amp <amp@ampcode.com>
The warning already names SRC_SKIP_VERSION_CHECK and links to the
upgrade instructions, and CHANGELOG.md describes the feature.

This reverts commit 71363c8.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1c29c-9f51-7761-a4ba-4d4f46dcd4ef
Co-authored-by: Amp <amp@ampcode.com>
@marcleblanc2
marcleblanc2 marked this pull request as ready for review November 10, 2026 00:49
@marcleblanc2
marcleblanc2 enabled auto-merge (squash) November 10, 2026 00:49
@marcleblanc2
marcleblanc2 requested review from a team and removed request for burmudar November 10, 2026 00:49
@marcleblanc2
marcleblanc2 merged commit 61d7456 into main Nov 10, 2026
11 checks passed
@marcleblanc2
marcleblanc2 deleted the marc/version-check-warning branch November 10, 2026 10:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Warn on any command if not on latest version

3 participants