Connect GitLab behind a VPN
Run the open-source TrimCI Agent inside your network to analyze a self-hosted GitLab that trimci.com cannot reach — outbound only, your GitLab token never leaves your infrastructure.
Some GitLab instances live behind a VPN or inside a private network where trimci.com cannot reach them. For those, TrimCI ships an open-source agent: a small program you run inside your network. It reads pipeline data from your GitLab over the LAN and pushes it out to TrimCI over HTTPS — outbound only, no inbound ports, no firewall changes, and your GitLab token never leaves your infrastructure.
Simplified illustration — the real screens hold more detail, but the labels and steps match the app.
Step by step
-
Choose the agent path
In the sidebar, under SETUP, click Connectors, press "+ Add connection" and choose "Connect GitLab CI". Under "Choose a connection method", pick "Behind a VPN or private network — TrimCI Agent". The next screen lists what the agent sends (pipelines, jobs, timing, the last 8,000 characters of failed job logs) and what it never reads (your GitLab token, source code, CI YAML).
-
Name the connection
Enter a label such as "HQ GitLab" and the address of your GitLab as the agent will see it from inside your network — for example https://gitlab.internal.example.com — then press "Create connection and get the token". TrimCI never calls this address itself; only the agent does.
-
Copy the token — it is shown once
The next page shows your agent token exactly once. TrimCI stores only a hash of it, so if you lose it you rotate it from the Connectors page rather than retrieving it. The token can only push pipeline data for this one connection; it cannot read anything.
-
Run the agent inside your network
Copy the docker run command from the same page. It already contains your token and GitLab address; replace the GITLAB_TOKEN placeholder with a GitLab access token that has the read_api scope. That GitLab token stays on your machine — it is never sent to TrimCI. A Docker Compose variant is on the page too; the static binary and a systemd unit are documented in the agent repository.
-
Watch the page flip to Connected
The token page waits for the agent's first report. Within seconds of the container starting, it flips to "Agent connected" and shows your GitLab version. Press Continue: the agent has already sent its project list in the meantime.
-
Pick projects to track
On the picker, tick the projects to analyze and press "Save selection". A newly ticked project is picked up by the agent on its next check-in — about a minute — and backfills up to 60 days of history, then keeps syncing incrementally on your plan's cadence. "Refresh project list" asks the agent to send a fresh catalog the same way.
Managing the agent
On the Connectors page each agent connection shows whether the agent is online, when it last synced runs, its version, and a "Manage agent" dialog. From there you can pause and resume syncing (nothing is ever deleted), rotate the token (the old one keeps working for 24 hours so you can update the container without downtime — or revoke it immediately if it leaked), and update the GitLab address after a hostname change. Disconnecting removes the connection and revokes its tokens; your historical pipeline data stays.
When the agent goes quiet
A healthy agent checks in about once a minute. If it stops — the host was rebooted, the container removed, a VPN route changed — the Connectors page marks it "Agent offline" after half an hour, and organization managers receive one email after a day of silence. Nothing is lost in the meantime: your GitLab keeps its full history and the agent resumes exactly where it left off, because TrimCI, not the agent, remembers how far each project was synced. The same design means you can move the agent to another machine, or run a replacement, with no state to migrate.
The agent is open source (github.com/trimci-opensource/trimci-agent), so your security team can read every line before it runs — including the allowlist of the only GitLab endpoints it is able to call (the instance version, projects, pipelines, jobs, job traces). It has no third-party dependencies and ships as a single static binary or a minimal container image.
The trust boundary holds on both ends. Inside your network the agent can only request pipeline endpoints; on TrimCI's side the ingest API simply has no fields for file contents, diffs or CI YAML — the schema is the boundary, enforced where nobody outside TrimCI can change it. One address can be connected through exactly one path, so an agent and a cloud connection never compete for the same GitLab.