Docs · Connectors

Connect self-managed
GitLab to Kaldros.

Kaldros supports every GitLab flavour — gitlab.com, on-prem, private cloud, and air-gapped. This guide walks your GitLab admin through the OAuth app registration, then shows the user flow in Kaldros.

01 — Register an OAuth application

What you need from your GitLab admin

Your GitLab instance administrator creates an OAuth application once. All Kaldros users in your organisation share it.

  1. Navigate to Admin Area → Applications → New Application (or Settings → Applications at the group level if the admin prefers a group-scoped app).
  2. Fill in the application:
    • Name: Kaldros
    • Redirect URI: https://app.kaldros.com/api/v1/connectors/gitlab/callback
    • Confidential: Yes
    • Expire access tokens: Yes
    • Trusted: Optional — check if you want to skip per-user consent.
  3. Select these scopes (all read-only):
    read_apiread_userread_repositoryopenidprofileemail
  4. Save, then copy the Application ID (the client_id) and the Secret — the secret is shown exactly once. Store both somewhere the installing user can reach.
02 — Connect the workspace

Connect in Kaldros

  1. In Kaldros, open Connectors and click Install on the GitLab card.
  2. Pick Self-managed in the dialog.
  3. Paste the instance URL (e.g. https://git.yourcompany.com), then the Application ID and Secret from step 01.
  4. Continue to your GitLab. Sign in, accept the scopes, and GitLab redirects you back to Kaldros. Kaldros persists the tokens AES-256-GCM-encrypted with your organisation’s data key.
  5. Pick the projects Kaldros should index. Every subsequent MR, issue, pipeline event, and push arrives via signed webhook.
03 — Network, SSL, version, webhooks

Gotchas we see in the field

Network reachability

Your GitLab instance must be reachable from the Kaldros servers in Hetzner Helsinki. Fully air-gapped instances cannot connect directly — they need a VPN tunnel or a Direct Connect, which is out-of-scope for the self-serve flow. Reach out to support for a scoped engagement.

SSL certificates

Enterprise GitLab often runs on an internal CA. Node.js rejects self-signed certificates by default. Kaldros requires a publicly-chained HTTPS cert on the instance URL you paste at install time; if you terminate TLS at a reverse proxy with a valid cert, you’re fine. We do not accept verify_ssl: false in production.

GitLab version

Kaldros captures the instance version at install time from GET /api/v4/version. v14 and above expose every endpoint the connector needs. v12/v13 instances can install, but pipeline and merge-request reads may 404 on unsupported fields — upgrade the instance before relying on those.

Webhook delivery

GitLab webhooks fire from the customer’s instance to app.kaldros.com. Corporate firewalls sometimes drop outbound POSTs silently. Kaldros tracks lastWebhookReceivedAt per install and falls back to a 60-second poller if webhooks go quiet — so the dashboard won’t look empty even if delivery is blocked. Ask your networking team to allow POST to app.kaldros.com/api/v1/connectors/gitlab/webhook.

04 — Scope + data

What Kaldros reads and stores

Every scope is read-only. Kaldros never writes to your GitLab instance — no pushes, no comments, no pipeline triggers. The tokens are encrypted with your organisation’s data-encryption key (AES-256-GCM, per-org DEK wrapped with the platform KEK), and revocation clears them immediately + hard-deletes the derived events within 24 hours. Webhook secrets are per-install, issued at subscription time, and never reused across orgs.

Contact

Still stuck?

Email hello@kaldros.com with the GitLab version and the exact error the install dialog surfaces. We respond inside a business day.