Skip to content

Rate versions with the GitLab version check service - #10

Merged
mxhash merged 3 commits into
mainfrom
feature/version-check-rewrite
Nov 10, 2026
Merged

mxhash merged 3 commits into
mainfrom
feature/version-check-rewrite

Conversation

@mxhash

@mxhash mxhash commented Nov 10, 2026

Copy link
Copy Markdown
Member

Rewrite of the plugin. The state is now based on the rating of the GitLab version check service (version.gitlab.com/check.json), the same service GitLab uses for the version badge in the Admin area. Before, the plugin compared the installed version with the Git tags on gitlab.com and reported every difference as CRITICAL.

Changes

  • Installed version from /api/v4/metadata; /api/v4/version is deprecated.
  • State from the version check service: OK if up to date, WARNING if an update is available, CRITICAL if the installed version is vulnerable, UNKNOWN on request or response errors and on usage errors.
  • Output without HTML: installed version and edition, latest patch release of the installed minor version, latest release, newer maintained releases, critical vulnerability yes/no.
  • Enterprise Edition instances work; before, they always ended as UNKNOWN.
  • Token from CHECK_GITLAB_VERSION_TOKEN or --token. It needs only the ai_features scope (group or project access token, role Guest) or read_user (personal access token), instead of read_api.
  • Only the version number is sent to version.gitlab.com. Redirects are never followed, so the token cannot leak to a redirect target. Response size is limited to 1 MiB.
  • Standard library only, the requests module is no longer needed. Python 3.9 or newer.
  • CHECK_GITLAB_VERSION_URL is replaced by --version-check-url. New option --timeout (default 10 s).

Breaking changes

Output format, states and the required token scope change. See "Upgrading from 0.1.0" in the README.

Tests

  • 43 unit tests against a local HTTP server, 100 % coverage (enforced with --fail-under 100).
  • CI: pylint, tests on Python 3.9 to 3.15.
  • Tested in production against GitLab 19.5 CE with an ai_features group access token.

Tag matching against gitlab-foss failed for every EE instance (revision
never matches a foss tag commit), read only the first 20 tags by update
date and reported any difference to the newest tag as CRITICAL.

- read the installed version from /api/v4/metadata instead of the
  deprecated /api/v4/version
- rate it with version.gitlab.com/check.json, as GitLab's own version
  badge does: success -> OK, warning -> WARNING, danger or
  critical_vulnerability -> CRITICAL
- print installed version, latest patch release of the installed minor
  and latest release; no HTML in the output
- read the token from CHECK_GITLAB_VERSION_TOKEN, reject tokens with
  characters invalid in HTTP headers so they never end up in an error
  message, document a read_user personal access token as least privilege
- never follow redirects, cap responses at 1 MiB, --timeout per request
  (default 10 s instead of 30 s), usage errors exit UNKNOWN (3)
- accept a base URL in --host besides a host name
- replace requests with urllib from the standard library
- test against a local HTTP server, including timeouts, redirects,
  invalid responses and running the plugin as a process; coverage 100 %
- CI: separate lint job, tests on Python 3.9 to 3.15, pylint 4.1.3

BREAKING CHANGE: new output format and states (an available non-security
update is WARNING instead of CRITICAL); CHECK_GITLAB_VERSION_URL is
replaced by --version-check-url; requests is no longer a dependency.
Assisted-by: claude-code:claude-opus-5-5
Signed-off-by: Marius Hein <marius.hein@netways.de>
actions/python-versions has no Python 3.9 build for Ubuntu 26.04
(ubuntu-latest), so the 3.9 job failed in setup-python and fail-fast
cancelled the other versions.

- run 3.9 on ubuntu-24.04, all other versions on ubuntu-latest
- set fail-fast: false so every version reports its result

Assisted-by: claude-code:claude-opus-5-5
Signed-off-by: Marius Hein <marius.hein@netways.de>
On GitLab CE, the REST API accepts ai_features only for
/api/v4/metadata and /api/v4/version, so a group or project access
token with this scope can read the version and nothing else. Verified
on GitLab 19.5 CE: projects, groups, users, search, GraphQL and Git
are denied.

- README: ai_features group/project access token (role Guest) as the
  recommended token, including an API call to create it; note that the
  scope also grants GitLab Duo API access on EE
- README: read_user personal access token as the alternative, warn
  against read_api and api (read access to all internal projects)
- --token help: name both scopes

Assisted-by: claude-code:claude-opus-5-5
Signed-off-by: Marius Hein <marius.hein@netways.de>
@mxhash
mxhash merged commit e3998cf into main Nov 10, 2026
16 checks passed
@mxhash
mxhash deleted the feature/version-check-rewrite branch November 10, 2026 09:48
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.

1 participant