> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rootly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Private Agent for GitLab (Early Access)

> Give AI SRE bounded, read-only access to a private GitLab instance's projects, repositories, merge requests, pipelines, deployments, and releases.

<Warning>
  **Early Preview:** Rootly Private Agent is under active development and available only to approved customers. Features, configuration, limits, and APIs may change before general availability. Confirm the approved agent and backend versions with your Rootly representative before production use.
</Warning>

Registered capabilities from this provider can also be used by the Rootly Agent in Slack on approved teams, subject to the requesting user's Rootly permissions and the agent's local policy. Slack access requires AI SRE to be enabled for the selected team.

The native GitLab provider gives AI SRE read-only access to a GitLab instance
that is not reachable from the internet. It connects directly to the GitLab API
inside your network and exposes only bounded read operations. It works the same
way against gitlab.com when you want agent-side allowlisting and bounded
results.

One agent can connect to multiple GitLab instances. Each entry has its own
stable provider ID, base URL, token, TLS trust, group and project scope,
health, and execution capacity. Choose an ID that is unique across every
provider in the Rootly account so registration and routing remain unambiguous.
Rootly routes a tool call to one exact registered instance; it cannot
substitute another host or credential.

<Info>
  GitLab support requires matching early-access agent and Rootly backend builds. Confirm availability with your Rootly representative before rollout.
</Info>

## Create a read-only GitLab token

Use a dedicated GitLab identity. The provider accepts a personal access token,
a group access token, or a project access token with the `read_api` scope.
`read_api` is the only scope the agent needs; do not grant `api`, `write`, or
`sudo`. A group or project access token scopes upstream access even further and
composes cleanly with the local allowlist below.

The token is sent as `PRIVATE-TOKEN` or `Authorization: Bearer`, so treat it
like a password: prefer an expiry and rotate the projected Secret before it
expires. The agent rereads the token file for every request, so a rotated
Secret takes effect without editing the agent YAML or restarting. Write only
the token value to the Secret described in
[Configure instances with Helm](#configure-instances-with-helm).

## Configure instances with Helm

Create the GitLab token Secret separately. The `rootly-private-agent` namespace
must already exist; on a first install, run this after the base Helm installation
has created the namespace.

```bash theme={null}
kubectl create secret generic rootly-private-agent-gitlab \
  --namespace rootly-private-agent \
  --from-file=token=./gitlab-token \
  --from-file=ca.pem=./gitlab-ca.pem
```

Omit both `--from-file=ca.pem` and `ca_bundle_file` when the GitLab certificate
chains to a CA already trusted by the agent image.

<Warning>
  The agent image runs as UID/GID `65532`. For Kubernetes Secret volumes using
  mode `0440`, set Pod-level `securityContext.fsGroup: 65532` so the process can
  read the token and optional TLS files. Do not make these files world-readable.
</Warning>

Add the provider and mount to your Helm values:

```yaml theme={null}
providers:
  gitlab:
    - id: gitlab-production
      url: https://gitlab.corp.internal
      token_file: /run/secrets/gitlab-production/token
      ca_bundle_file: /run/secrets/gitlab-production/ca.pem
      policy:
        allowed_groups: [infra, payments]
        allowed_projects: []
        maximum_concurrency: 2
        maximum_result_bytes: 1048576
        maximum_items: 100
        maximum_file_bytes: 262144
        maximum_diff_bytes: 65536
        maximum_timeout_seconds: 20

extraVolumes:
  - name: gitlab-production
    secret:
      secretName: rootly-private-agent-gitlab
      defaultMode: 0440
extraVolumeMounts:
  - name: gitlab-production
    mountPath: /run/secrets/gitlab-production
    readOnly: true
```

The API base is `url` plus `/api/v4`. `url` must use HTTPS unless you set
`allow_insecure_http: true`, which is intended only for local testing. Mount a
private CA with `ca_bundle_file` when needed; mutual TLS is supported with the
paired `client_certificate_file` and `client_key_file` paths. There is no
skip-certificate-verification option. The client certificate and key are
reread on each new TLS handshake. The CA bundle is read once at startup, so
restart the agent after replacing `ca_bundle_file`.

### Scope and policy

* `allowed_groups` lists full group paths (for example `infra` or
  `platform/observability`). Each allowed group includes all of its subgroups
  and the projects beneath them.
* `allowed_projects` lists full project paths (`group/sub/project`). It can
  narrow the scope further or add individual projects outside the allowed
  groups.
* When both lists are empty, the provider permits every group and project the
  token itself can see. Either way, the agent rejects a call for a project
  outside the allowlist before any network request, and list results are
  filtered to the allowlist.
* `maximum_concurrency`, `maximum_result_bytes`, `maximum_items` per list
  call, `maximum_file_bytes` for `get_file` content, `maximum_diff_bytes` per
  diff, and `maximum_timeout_seconds` bound every call. Hard maxima are
  listed in [Private Agent limits](/private-agent-limits#gitlab). Lower
  values tighten the provider; Rootly uses the advertised values to narrow
  tool limits.

## Available tools

Every tool is a sensitive read. `project` inputs are always full paths such as
`infra/api`, never numeric IDs, and the agent URL-encodes them itself.

| Tool | Inputs | Diagnostic |
| - | - | - |
| `gitlab.list_projects` | `group?`, `search?`, `limit?` | List projects the token can see, filtered to the allowlist |
| `gitlab.list_commits` | `project`, `ref?`, `path?`, `since?`, `until?`, `limit?` | Review recent commits in a project |
| `gitlab.get_commit` | `project`, `sha`, `include_diff?` | Read one commit and optionally its bounded diff |
| `gitlab.compare` | `project`, `from`, `to`, `include_diff?` | Compare two refs and read a bounded diff |
| `gitlab.list_merge_requests` | `project`, `state?`, `target_branch?`, `updated_after?`, `limit?` | Find open or recently updated merge requests |
| `gitlab.get_merge_request` | `project`, `iid`, `include_changes?` | Read one merge request and optionally its bounded changes |
| `gitlab.get_file` | `project`, `file_path`, `ref` | Read one bounded repository file at a ref |
| `gitlab.search_blobs` | `project`, `query`, `ref?`, `limit?` | Search code inside one project (project scope only) |
| `gitlab.list_deployments` | `project`, `environment?`, `status?`, `updated_after?`, `limit?` | Review deployments to each environment |
| `gitlab.list_releases` | `project`, `limit?` | Review recent releases |
| `gitlab.list_pipelines` | `project`, `ref?`, `status?`, `updated_after?`, `limit?` | Find recent or failing pipelines |
| `gitlab.get_pipeline` | `project`, `pipeline_id`, `include_jobs?` | Read one pipeline and bounded job metadata (name, stage, status, timestamps only) |

There are no write operations, no CI job logs or traces, and no access to
issues, wikis, snippets, or CI/CD variables.

## Data redaction and limits

Before a result leaves your network, the agent removes:

* token, credential, password, and secret fields (for example runner tokens) from API metadata;
* user email addresses (results keep `username` and `name`);
* avatar URLs and URL query strings;
* CI job logs and traces.

<Warning>
  Redaction applies to GitLab API metadata, not repository contents. `gitlab.get_file`, `gitlab.search_blobs`, and diffs return file text as committed, so a secret committed to an allowed project can reach AI SRE. Keep `allowed_groups` and `allowed_projects` narrow and keep secrets out of repositories.
</Warning>

Diffs and file contents are truncated to the configured policy limits and carry
`truncated: true` when cut. List results always carry `items` and `truncated`.
A result that remains too large is rejected so AI SRE can narrow the request.

Results can enter AI model context, evaluation traces, and investigation or
conversation history under the [Private Agent retention model](/ai/data-privacy-for-rootly-ai#how-is-private-agent-data-logged-and-retained).

## Health, compatibility, and routing

Each configured instance reports independent health. An invalid token, TLS
failure, or unavailable GitLab API marks only that instance unhealthy; other
instances remain registered and routable.

In **AI SRE → Atlas → Private agents** (**AI & Agents → Private agents** if
your sidebar doesn't have an **AI SRE** item), verify the provider ID, health,
last check, and advertised capabilities.

Compatibility CI runs the provider against GitLab CE 19.4. Other self-managed
versions and GitLab.com use the same stable `/api/v4` endpoints but are not
certified; confirm your version with your Rootly representative before
rollout.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.