> For the complete documentation index, see [llms.txt](/llms.txt).
> Markdown versions of each page are available by appending .md to any URL.

# GitLab integration

Connect Oz cloud agents to GitLab repos using personal access tokens and Warp-managed secrets.

Oz cloud agents work with any Git repository, including those hosted on GitLab. Unlike GitHub, GitLab does not have a native Warp integration, but you can grant agents access to your GitLab repositories using a personal access token and Warp-managed secrets. Once configured, your environment works with any Oz trigger—Slack, Linear, schedules, or the CLI.

This page explains how to generate a GitLab personal access token, store it securely, and configure a cloud agent environment that clones your repository at runtime.

Note

This approach works for both GitLab.com and self-hosted GitLab instances.

* * *

## Prerequisites

-   A Warp account ([create an account at oz.warp.dev](https://oz.warp.dev))
-   A repository hosted on GitLab (cloud or self-hosted)
-   The [Oz CLI](/reference/cli/) installed and authenticated

* * *

## Step 1: Generate a personal access token

Note

These steps generate a personal access token tied to your GitLab account. If your team prefers a shared bot user, [GitLab project access tokens](https://docs.gitlab.com/user/project/settings/project_access_tokens/) work the same way.

1.  Sign in to GitLab.
2.  Click your avatar in the top-right corner, then click **Edit profile**.
3.  In the left sidebar, click **Access**, then click **Personal access tokens**.
4.  Click **Add new token**.
5.  Enter a descriptive name for the token (e.g. `warp-oz-agent`), and choose an expiration date that matches your team’s rotation policy.
6.  Under **Select scopes**, select **read\_repository**.
7.  Click **Generate token**.
8.  Copy the token value immediately. GitLab will not show it again.

Note

**read\_repository** is the minimum required scope to clone a repository. If a future workflow requires the agent to push commits or open merge requests, you will also need **write\_repository**.

* * *

## Step 2: Store the token as a Warp-managed secret

Warp injects managed secrets as environment variables at runtime and never exposes them in logs or configuration files. See the [Secrets](/agent-platform/cloud-agents/secrets/) documentation for full details on scoping and managing secrets.

1.  Run the following command:

```
oz secret create --team GITLAB_TOKEN
```

2.  When prompted, paste the token.

The value is stored and encrypted, and cannot be retrieved after creation.

Note

Use `--team` to create a shared token available to all teammates and automated triggers (schedules, Slack, Linear). Use `--personal` if each team member should authenticate with their own GitLab token. Personal secrets work with all triggers and take precedence over a team secret of the same name when both exist.

If you need to update a secret value, run:

```
oz secret update --value GITLAB_TOKEN
```

* * *

## Step 3: Create an environment with a clone setup command

Create an environment that uses your token to clone the repository at the start of each agent run. Because the `--repo` flag in `oz environment create` is designed for GitHub repositories, you clone your GitLab repo via a setup command instead.

1.  Run the following command:

```
oz environment create \  --name "my-gitlab-env" \  --docker-image <image> \  --setup-command 'git clone https://oauth2:$GITLAB_TOKEN@gitlab.com/your-group/your-repo.git' \  --setup-command 'cd your-repo && <install dependencies>'
```

Caution

Use single quotes around setup commands that reference secrets. Double quotes cause your shell to expand `$GITLAB_TOKEN` immediately (to nothing), rather than letting Warp inject the secret at runtime inside the container.

2.  Replace the following placeholders:
    -   `<image>` with your Docker image (for example, `node:22`, `python:3.12`, or a [Warp prebuilt dev image](https://github.com/warpdotdev/oz-dev-environments))
    -   `gitlab.com/your-group/your-repo.git` with your actual repository URL
    -   For a self-hosted GitLab instance, replace `gitlab.com` with your server’s hostname.
    -   The second `--setup-command` with any dependency install or build steps your project requires. For example, `npm ci` or `pip install -r requirements.txt`.

Caution

Setup commands run on a fresh container for every agent run. Write them to be idempotent — commands that assume existing state (such as a partially cloned repo or a pre-built cache) can fail unpredictably. See [Environment design and best practices](/agent-platform/cloud-agents/environments/#environment-design-and-best-practices) for guidance.

3.  Note the environment ID returned. You will need it in the next step.

* * *

## Step 4: Test your environment

Before connecting to integrations, verify the environment works by running a one-off agent.

1.  Run the following command, replacing `<ENV_ID>` with the environment ID from Step 3:

```
oz agent run-cloud --environment <ENV_ID> --prompt "Your task here"
```

* * *

## Next steps

With your environment configured, you can connect it to any Warp trigger exactly as you would with a GitHub-backed environment:

-   **Slack** — Tag **@Oz** in a message to start an agent run against your GitLab repo. See [Slack](/agent-platform/cloud-agents/integrations/slack/).
-   **Linear** — Tag **@Oz** on an issue to kick off a workflow. See [Linear](/agent-platform/cloud-agents/integrations/linear/).
-   **Scheduled agents** — Run agents on a recurring schedule. See [Scheduled Agents](/agent-platform/cloud-agents/triggers/scheduled-agents/).

Note

Native support for opening GitLab merge requests from agent-generated changes is planned as a future enhancement.