GitLab integration

Cloud agents work natively with repositories hosted on GitLab.com. Connect your GitLab account when you create an environment in the Oz web app, select the projects agents need, and Warp handles the rest at runtime: repositories are cloned automatically, your GitLab credentials are injected into the run, the glab CLI is authenticated, and agents can push branches and open merge requests on your behalf. Merge requests the agent opens are reported as run outputs.

For self-managed GitLab instances, native connection isn’t available yet. Instead, grant agents access using a personal access token and Warp-managed secrets, as described in Self-managed GitLab instances.

Note

To route GitLab activity into a factory — merge request events and bot mentions triggering work — see the GitLab factory integration instead. This page covers standalone cloud agent environments.

---

Connect GitLab.com natively

1. In the Oz web app, create or edit an environment.
2. Choose GitLab as the repository source and authorize with your GitLab account when prompted. Warp requests the api and read_user scopes, which grant read and write access to your projects.
3. Select the projects the agent should clone, then finish configuring the environment (Docker image, setup commands).

At the start of each run, Warp clones the selected repositories and injects your GitLab token, so agents can fetch, push branches, and open merge requests without extra setup. Once configured, the environment works with any Automation Platform trigger—Slack, Linear, schedules, or the CLI.

Note

Native GitLab environment creation is available in the Oz web app only. The --repo flag on oz environment create accepts GitHub repositories; to script GitLab environments, use the web app or the setup-command approach below.

---

Self-managed GitLab instances

Native connection supports GitLab.com only. For a self-managed GitLab instance, generate a personal access token, store it securely, and configure an environment that clones your repository at runtime.

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 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-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 workflow requires the agent to push commits or open merge requests, you 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 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.

1. Run the following command:

oz environment create \
  --name "my-gitlab-env" \
  --docker-image <image> \
  --setup-command 'git clone https://oauth2:$GITLAB_TOKEN@gitlab.example.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)
   • gitlab.example.com/your-group/your-repo.git with your server’s hostname and repository path
   • 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 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:

• Slack — Tag @warp in a message to start an agent run against your GitLab repo. See Slack.
• Linear — Tag @warp on an issue to kick off a workflow. See Linear.
• Scheduled agents — Run agents on a recurring schedule. See Scheduled Agents.