GitLab (self-managed)
Whether a self-managed GitLab instance is serving, and whether the parts that quietly carry everything else are keeping up: Sidekiq’s queues, the CI/CD runners, database migrations left over from an upgrade, and — for GitLab Enterprise Edition — the licence.
Network ports to open
Section titled “Network ports to open”From the DumbMonit server (or its relay agent) to the device:
| Port | Protocol | Purpose |
|---|---|---|
| 443 | TCP | API (HTTPS, default) |
| 80 | TCP | Only with the http scheme option |
DumbMonit reads /api/v4/version with a personal access token, the only
call that must succeed: it is the proof that GitLab answers and that the
token is valid. Everything else — Sidekiq, runners, migrations, instance
statistics, the sign-up and two-factor settings, the licence, and the
readiness check in detail — is read from endpoints GitLab reserves to
administrator accounts, and is skipped without failing the probe when the
token belongs to an ordinary one.
The failure worth watching here: Sidekiq falling behind. GitLab keeps serving pages while its background worker queue grows, and nothing on the page says so until a notification, a webhook or a CI pipeline update is late by minutes or hours.
What it watches
Section titled “What it watches”All metrics are prefixed dumbmonit_gitlab_.
| Metric | What | Labels |
|---|---|---|
version_info | value 1 | version, revision |
readiness_check | 1 when a readiness component (database, cache, queues, shared state, Gitaly) is not ok; absent when GitLab does not expose it to DumbMonit (see below) | check |
sidekiq_queue_backlog, sidekiq_queue_latency_seconds | jobs waiting and their age, per Sidekiq queue | queue |
runners_total, runners_online, runners_offline | CI/CD runners known to the instance | |
runner_offline | value 1 per offline runner (at most 32) | runner |
migrations_pending | database migrations left to apply | |
migration_pending | value 1 per pending migration (at most 32) | migration |
projects, users, groups, forks, issues, merge_requests | instance-wide counts | |
signup_enabled | 1 while public sign-up is open | |
two_factor_required | 1 while every user must set up two-factor authentication | |
license_info | value 1 (Enterprise Edition only) | plan |
license_expired, license_expiry_seconds | whether the licence has expired, and the time left | |
pipelines_failed_recent, pipelines_pending | failed pipelines in the lookback window, and pipelines pending or running now — only for the projects listed in the “Projects watched for CI health” option | project |
scrape_errors | administrator-only calls that failed on the last probe (0 with an ordinary token’s ones never attempted) |
The built-in rules that apply: GitLab runners all offline, GitLab Sidekiq backlog high, GitLab migrations pending, GitLab license expiring, plus Monitor unreachable. A security score checks the two-factor and sign-up settings, and pending migrations: see Vendor updates and other checks.
What it does not watch
Section titled “What it does not watch”GitLab’s own REST API has no endpoint that says “a newer GitLab release is available”: unlike Nextcloud or Paperless-ngx, there is no self-reported update flag to read, so DumbMonit does not claim one. Compare the version above against GitLab’s release page by hand, or watch GitLab’s own update-check notice in the admin area.
CI pipeline health is read only for the projects you list: GitLab’s API has no instance-wide “all failing pipelines” endpoint, only a per-project one.
The monitor page
Section titled “The monitor page”The panel above the charts reads what the probe stored; opening the page never calls GitLab. It says what is wrong first (a readiness component failed, runners all offline, a large Sidekiq backlog), then the version, then the instance counts and the settings read from the administration API.
Create a personal access token on an administrator account
Section titled “Create a personal access token on an administrator account”-
On an administrator account, open avatar → Edit profile → Access → Personal access tokens → Generate token → Legacy token.
-
Name it as follows, set an expiry date you can renew, and tick only the scope listed below.
dumbmonit -
Generate the token and copy it: GitLab shows it only once.
-
In DumbMonit, enter GitLab’s address and paste the token.
-
To watch CI pipelines, list the numeric project IDs (shown on each project’s page) in the Projects watched for CI health option.
Required permissions
Section titled “Required permissions”- read_api: Token scope: reads the whole API, writes nothing
- Administrator account: Sidekiq, runners, migrations, statistics, settings and licence need it
Vendor documentation: https://docs.gitlab.com/ee/api/rest/
Why these permissions
Section titled “Why these permissions”read_api reads the whole API and writes nothing. Sidekiq queues, CI runners, pending migrations, instance statistics, the sign-up and two-factor settings and the licence are each read from an administrator-only endpoint: GitLab has no finer delegation for them. A token from an ordinary account still works; only the version is then read, and the rest is skipped without failing the probe.
On an older GitLab, the token page is avatar → Edit profile → Access tokens → Add new token. Set an expiration date you are comfortable renewing, and revoke the token if it ever leaks.
Readiness check
Section titled “Readiness check”GitLab answers /-/readiness with 404 to any client address that is not in
its monitoring allowlist (by default only 127.0.0.1; behind Docker or a
reverse proxy DumbMonit arrives from another address). DumbMonit treats that
404 as “not exposed”: the readiness panel stays empty and it is not counted in
scrape_errors. To enable it, add DumbMonit’s address in gitlab.rb and run
gitlab-ctl reconfigure:
gitlab_rails['monitoring_whitelist'] = ['127.0.0.0/8', '::1/128', '192.168.1.10/32']The licence endpoint likewise answers 404 on Community Edition, which is not an error either.
Checking the token by hand, from the DumbMonit host:
curl --header 'PRIVATE-TOKEN: YOUR-TOKEN' 'https://gitlab.example.com/api/v4/version'Credentials
Section titled “Credentials”| Credential | Fields |
|---|---|
| Personal access token | Sent as the PRIVATE-TOKEN header. |
Address: a host name (gitlab.example.com) or host:port. Options:
protocol (HTTPS by default), port (443), certificate check, request timeout
(15 s), the projects watched for CI health (none by default) and the failed
pipeline lookback window (24 h).
Validated against GitLab Enterprise Edition 17.5 (official API documentation).