> ## Documentation Index
> Fetch the complete documentation index at: https://docs.augmentcode.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Integrate GitLab Cloud
## Introduction
In this page we’ll learn how to configure 3 things:
1. Get Gitlab to push events to Augment Cosmos via webhooks
2. How to configure an environment that auto git clones/fetches from Gitlab repo(s)
3. Get Augment Cosmos to interact with Gitlab via the `glab` cli\
For 2+3, below is the flow we’ll configure with a simple MR reviewer expert:
```mermaid theme={null}
sequenceDiagram
autonumber
participant GL as GitLab
participant A as Augment Cosmos
GL->>A: Webhook: Merge Request created (MR payload)
A->>A: Start Expert (spawn/run expert agent)
A->>A: Expert analyzes MR (diff + context)
A->>GL: POST MR comment (GitLab CLI: create comment)
GL-->>A: 201 Created (comment posted)
```
## Step 1 - Configure Gitlab to notify a Cosmos Webhook
Let’s create a new webhook in Cosmos (so Cosmos can listen to Gitlab events):
* Go to Cosmos ([https://app.augmentcode.com/app](https://app.augmentcode.com/app)) > Settings > Capabilities > Webhooks > Create Webhook
* That gives us a url to POST with a given Bearer token to pass as HTTP header. Curl request would look like:
```shell theme={null}
curl -X POST https://XXX.api.augmentcode.com/webhooks/XXX \
-H "Authorization: Bearer XXX" \
-H "Content-Type: application/json" \
-d '{"event": "test", "data": "your payload here"}'
```
**Create a new webhook config in Gitlab** (so Gitlab can POST to a given url when certain Gitlab events occur)
* Go to your Gitlab repo > Settings > Webhooks > Add new webhook
* Add
* Name
* URL: the Cosmos webhook url
* DO NOT FILL SECRET TOKEN (that for a separate X-Gitlab-Token header that Cosmos would ignore)
* Trigger: Merge request events
* Custom header > Add custom header
* Header name: Authorization
* Header value: Bearer THE\_SECRET\_PROVIDED\_BY\_COSMOS
* Keep Enable SSL verification selected
* Save changes
* Now run a test: in Gitlab go back to your list of Gitlab Webhooks (Settings > Webhooks) > click on the Test dropdown > Merge request events
Now go back to Cosmos and check that Cosmos received the event:
* [https://app.augmentcode.com/app](https://app.augmentcode.com/app) > Settings > Automations > Event Log. You should see your event with source “Custom”
* Click on the event:
At this point Gitlab can invoke Cosmos ✅.
## Step 2 - Create a Gitlab Service Account
For headless automation and to start agentic workflows based on gitlab events, we’ll create a dedicated Gitlab service account and its access token:
* Gitlab repo > Settings > Service accounts > Add service account > add a name
* Then next to that service account > 3 dots > manage access tokens
* Add new token
* Add token name
* Set a max expiration date (keep it mind that this access token would have to be rotated on the gitlab side, and its new value would have to also be updated in the Augment’s secret manager - that’s a common sec best practice)
* Select scope “api”
* Click on Generate token
* Click on the copy icon to copy the GITLAB\_TOKEN in your clipboard
Now go to Augment Agent Cloud’s secret manager: [https://app.augmentcode.com](https://app.augmentcode.com/) > Settings > Capabilities > Secrets > Add Secret > Environment Variable
* Name: GITLAB\_TOKEN
* Value: the value you copied from Gitlab
* Keep Visibility - Shared toggled off
* Keep “Automatically install in VMs” selected
* Click on Create Secret
Now get back to Gitlab and add your Gitlab service account with role=developer onto the repos where the service account should be able to read/post:
* Go to your Gitlab repo(s) > Manage > Members > Invite members > add your Gitlab service account and click on Invite
## Step 3 - Configure the environment to auto fetch code from Gitlab
Let’s create a new environment that will automatically fetch our gitlab repo(s).
* Go to [https://app.augmentcode.com/app/environments](https://app.augmentcode.com/app/environments) > New environment
* Add a title, select the base image, add GITLAB\_HOST = [https://gitlab.com](https://gitlab.com/) as env variable, toggle on “Scheduled refresh” then click on “Create Environment”:
* You should see this once the environment is created:
* Click on Customize (or if you already closed that window: open your environment > click on Terminal top right)
* You should see this:
* We’d need to git clone the gitlab repo using the “2 layers approach”. Edit and run this command:
```shell theme={null}
mkdir -p /workspace/augmentcode-sa && git clone https://oauth2:$GITLAB_TOKEN@gitlab.com/augmentcode-sa/ecomm-stack.git /workspace/augmentcode-sa/ecomm-stack && ls -d /workspace/*/*/.git
```
You should see this:
* Then double check the 2 layer structure was created:
* make sure you’re in `root /workspace` then install the glab CLI using this command:
```shell theme={null}
wget https://gitlab.com/gitlab-org/cli/-/releases/v1.93.0/downloads/glab_1.93.0_linux_amd64.deb && dpkg -i glab_1.93.0_linux_amd64.deb && glab auth status
```
You should that response indicating that glab is properly installed and authenticated:
* Now click on “Update environment” bottom right
## Step 4 - Configure an expert that interacts with Gitlab
Here we’ll create an expert agent that will interact with Gitlab. For this tutorial we’ll create an expert from scratch to cover some core concepts. Note: as you tackle more advanced use cases you can later leverage the “Expert Factory” expert.
For a code review type of automation, high level the expert will fetch and push data to gitlab via the glab CLI for every session:
Let’s create the expert:
* Go to Settings > Foundation > Experts > Create an expert
* Overview section:
* Name:
```shell theme={null}
GitLab MR Reviewer
```
* Description:
```shell theme={null}
Auto-reviews newly opened Merge Requests on augmentcode-sa/ecomm-stack using the glab CLI.
```
* User instructions:
```shell theme={null}
Triggered automatically when an MR is opened on augmentcode-sa/ecomm-stack.
Manual launches are not the intended use; if launched manually, paste a
GitLab MR URL and the agent will review it.
```
* System section:
* Environment: select the environment you created above
* Model: keep the default
* System prompt:
````shell theme={null}
# GitLab MR Reviewer
You auto-review a newly opened GitLab Merge Request on
`$REPO` (e.g. `augmentcode-sa/ecomm-stack`). You run unattended (no human in the loop).
All GitLab interactions go through the `glab` CLI in the shell.
## Inputs
You are launched by a custom webhook trigger. The triggering payload is
visible in the session input. Extract:
- `project.path_with_namespace` -> $REPO (e.g. `augmentcode-sa/ecomm-stack`)
- `object_attributes.iid` -> $MR_IID (the MR number)
- `object_attributes.source_branch` -> $SRC
- `object_attributes.target_branch` -> $TGT
- `object_attributes.url` -> $MR_URL
If the payload is missing or `object_attributes.action` is not `"open"`,
stop and report why.
## Bootstrap (do this first, fail loudly)
The VM image is the platform default — `glab` is pre-installed and
the repo is already pre-cloned. Stop with a clear message if any step fails. Never echo `$GITLAB_TOKEN`.
1. Verify the token is present:
`test -n "$GITLAB_TOKEN"` — if missing, stop and report that the
`gitlab-token` secret is not set in Settings → Secrets Manager.
2. Confirm auth (glab reads `$GITLAB_TOKEN` natively):
`glab auth status --hostname "$GITLAB_HOST"` — must show authenticated.
## Idempotency check (do this before posting anything)
You may be re-fired on the same MR. Before reviewing:
```
glab mr view "$MR_IID" -R "$REPO" --comments \
| grep -F "
[**Augment MR Reviewer**]({{session_url}}) — automated review
```
Followed by sections in this order, omitting any that are empty:
```
## Summary
<2-4 sentence synthesis of what the MR does and overall verdict>
## Blockers
-
## Suggestions
-
## Nits
-
```
If there are no findings, post the header + a one-line "No issues found."
## Hard rules (no exceptions)
- Allowed `glab` operations: `auth status`, `mr view`, `mr diff`,
`mr note`, and any read-only `glab api GET ...` you need. Allowed
local: `git`, ripgrep, file reads.
- **Forbidden**: `glab mr approve`, `glab mr merge`, `glab mr close`,
`glab mr update`, `glab mr revoke`, `git push`, `git commit` to
the remote, creating branches on the remote, deleting anything on
GitLab.
- Never echo `$GITLAB_TOKEN` or any value derived from it.
- One MR note per session. If the idempotency check finds a prior
marker, stop instead of posting a follow-up.
- Do not characterize the code as clean / well-structured / elegant.
Absence of findings is itself the positive signal.
## Stop conditions
Stop the session immediately after:
- Posting the single MR note, or
- Detecting a prior marker comment (idempotency hit), or
- Failing the environment self-check (with the failure message), or
- The trigger payload is malformed or not an `open` action.
````
* Tools section:
* Integrations: Select Web Fetch
* MCP Servers: don’t select any
* Triggers section:
* Click on + Add Trigger
* Add a name
* Webhook - select the webhook you created in Step #1
* Click on Add
* Top right click on Create Expert
## Step 5 - Test your expert end2end
Create a new MR on Gitlab, ex:
Gitlab would automatically notify Cosmos that this MR was created. Go to Cosmos > Settings > Automations > Event Log:
Then check that your expert was invoked and a session was created: Cosmos > Sessions
If you don’t see your session, switch to “All sessions” and toggle on “Archived” as your session may have already been completed and archived.
Click on your session to open it. You’ll see the trace of the Augment agentic loop:
Congratulation, you’ve build your first Gitlab \<> Cosmos core loop!