CLI reference

This page is generated from the CLI definition, so it always matches the released flags. Every flag also has an environment variable, listed in Configuration.

gitlab-achievements

Watches a self-hosted GitLab instance’s activity and automatically awards GitLab Achievements to users.

Usage:
  gitlab-achievements [flags]
  gitlab-achievements [command]

Available Commands:
  backfill    Walk the instance's history once, awarding achievements for past activity
  reconcile   Re-read recent instance activity once, healing anything the webhooks dropped
  uninstall   Remove the GitLab webhooks and achievements this app created

Flags:
      --achievements-namespace string     Full path of the namespace that owns the achievement definitions
      --allow-opt-out                     Let users leave themselves out through the API (needs --api-auth gitlab) (default true)
      --api-allowed-group string          Full path of a GitLab group; only its members (and instance admins) may use the API
      --api-auth string                   What the read API requires of callers (none, gitlab); gitlab verifies a GitLab token on every request (default "none")
      --api-auth-cache-ttl duration       How long a verified GitLab credential is trusted before asking GitLab again (also how long a revoked token keeps working); 0 disables (default 1m0s)
      --backfill string                   Whether the server walks the instance's history itself (auto, off, force) (default "auto")
      --backfill-rate float               Requests per second the historical backfill is allowed to issue (default 5)
      --backfill-since string             How far back the historical backfill reaches, as a date (2006-01-02) or duration (720h); empty walks everything
      --database-dsn string               Database connection string (postgres://, sqlite://, mysql://, or sqlserver://); defaults to "sqlite:///var/lib/gitlab-achievements/data.db"
      --exclude-bots                      Leave out accounts GitLab flags as bots: access token users, service accounts, GitLab's own bots (default true)
      --exclude-username-pattern string   Regular expression (RE2); users whose username matches are left out of achievements
      --exclude-users strings             Usernames or GitLab user IDs to leave out of achievements, comma-separated
      --frontend-csp string               Content Security Policy for --frontend-dir; empty uses the built-in frontend's, "off" sends none
      --frontend-dir string               Directory of a built static frontend to serve at /, on the same origin as the API
      --gitlab-read-token string          Read-only GitLab token (read_api scope)
      --gitlab-url string                 Base URL of the GitLab instance
      --gitlab-write-token string         Write-capable GitLab token (api scope), scoped down by role
  -h, --help                              help for gitlab-achievements
      --hook-rate float                   Groups or projects per second the webhook registration sweep works through (default 20)
      --hook-scope string                 Which webhooks to register for event ingestion (auto, group, project); auto picks group hooks where the license allows them (default "auto")
      --listen-addr string                Address the HTTP server listens on (default ":8080")
      --log-level string                  Log level (debug, info, warn, error) (default "info")
      --metrics-addr string               Address Prometheus metrics are served on, apart from --listen-addr; "off" serves none (default ":9464")
      --oauth-client-id string            Client ID of a hand-registered GitLab OAuth application; empty lets the app register a public one for itself
      --oauth-client-secret string        Client secret for --oauth-client-id, making it a confidential client; empty means PKCE alone
      --oauth-return-origins strings      Origins besides --public-url's that a login may return to, comma-separated, e.g. https://rankings.example.com
      --public-url string                 Externally reachable base URL of this app, used for GitLab OAuth redirects
      --reconcile string                  Whether the server re-reads recent activity on a timer to heal lost webhook deliveries (auto, off) (default "auto")
      --reconcile-interval duration       How often the reconciliation sync re-reads recent activity (default 24h0m0s)
      --reconcile-lookback duration       How far back each reconciliation pass reaches; must exceed --reconcile-interval so passes overlap (default 48h0m0s)
      --session-lifetime duration         How long a browser stays logged in; sessions renew their GitLab token as it runs out (default 168h0m0s)
      --session-secret string             Key for encrypting the GitLab tokens browser sessions hold, at least 32 characters; required when --api-auth is gitlab
  -v, --version                           version for gitlab-achievements
      --webhook-secret string             Secret token used to validate incoming GitLab webhook deliveries
      --webhook-url string                Base URL GitLab uses to deliver webhooks; defaults to --public-url

Use "gitlab-achievements [command] --help" for more information about a command.

gitlab-achievements backfill

Walks every project the read token can see and replays its history through the achievement engine, so activity that happened before this app existed still earns achievements.

Bootstrap runs first, exactly as it does when serving: the walk needs the achievement definitions it creates, and running it here keeps a one-off backfill job from depending on a serving instance having started first.

The walk resumes from wherever a previous run stopped, and does nothing at all if history has already been walked end to end. Pass –backfill=force to walk it again anyway.

Usage:
  gitlab-achievements backfill [flags]

Flags:
  -h, --help   help for backfill

It also takes every flag of gitlab-achievements.

gitlab-achievements reconcile

Re-reads the last –reconcile-lookback of instance activity through the Events API and replays it through the achievement engine, so activity whose webhook delivery was lost (GitLab downtime, a network blip, a deploy) still earns achievements.

Activity that was already counted is discarded rather than counted again: both paths derive the same dedup key for the same activity, so a pass over a window the webhooks covered correctly is a no-op.

Unlike the server and the backfill subcommand this does not bootstrap: it reads GitLab and writes awards, but registers no webhooks and creates no achievements, so running it on a schedule costs one sweep of recently active projects rather than a sweep of the whole instance.

The window widens on its own to cover everything since the last successful pass, so a run that was missed or that failed is made up by the next one rather than leaving a hole.

Usage:
  gitlab-achievements reconcile [flags]

Flags:
  -h, --help   help for reconcile

It also takes every flag of gitlab-achievements.

gitlab-achievements uninstall

Deletes every event ingestion webhook this app registered on the GitLab instance, and every achievement it created in the achievements namespace, using the records it kept of what it created and where.

Stop the serving deployment first: a running server re-registers the hooks on its next hourly reconciliation sweep, and recreates the achievements on its next start, so removing them underneath it accomplishes nothing.

Deleting the achievements takes the awards with them: GitLab removes an achievement from the profile of everyone holding it, and nothing brings those back. Pass –keep-achievements to remove only the hooks and leave people the badges they earned.

Hooks and achievements this app’s write token may not manage are left in place and reported, with their records kept, so re-running with a better-privileged token picks up exactly those.

Usage:
  gitlab-achievements uninstall [flags]

Flags:
      --dry-run             Report what would be removed without removing anything
  -h, --help                help for uninstall
      --keep-achievements   Remove only the webhooks, leaving the achievement definitions and the awards users earned in place
      --sweep               Also enumerate the instance and remove hooks pointing at this app, and achievements in the namespace matching its catalog, that it has no record of, for a lost or restored database

It also takes every flag of gitlab-achievements.

End-to-end catalog check