Integrate GitLab Self-Hosted

Introduction

In this page we’ll learn how to configure those items:

Get Gitlab to push events (ex: “new MR created”) to Augment Cosmos via webhooks
Configure a Cosmos Daemon on a AWS EC2 instance/VM (where the Gitlab local repos will be cloned locally)
Get Augment Cosmos to interact with Gitlab via the glab cli
Deploy your first Cosmos MR experts

Below is the flow we’ll configure with a simple MR reviewer expert: Below is a high level architecture diagram of the components at play:

Prerequisites

To configure the one-time connectivity between Cosmos and Gitlab: Cosmos

must be an admin to create a Augment service account and webhooks

Gitlab Self-Hosted

must have at least Maintainer or Owner role on a given project, or be Owner of a group that has access to given projects
allow inbound connections from other VMs on your VPC (inbound calls will come from within your network)

AWS

must have the ability to deploy EC2 instances in a VPC that has network connectivity to your Gitlab self-hosted. Must enable outbound network connectivity to *.augmentcode.com (see https://docs.augmentcode.com/setup-augment/network-configuration)

Step 1 - Configure Gitlab to notify a Cosmos Webhook

Webhook receiver in Cosmos

Let’s create a new webhook in Cosmos (so Cosmos can listen to Gitlab events):

As an admin go to Cosmos (https://cosmos.augmentcode.com) > Settings > Webhooks > Create a webhook > Select type: GitLab > Enter Description: GitLab MR events

Make sure to copy the provided Webhook URL and the Secret token, then click on Create. You’ll get a confirmation that the webhook is ready to use.

Run this curl request (with your own parameters) to do a quick test:

curl -i -X POST "https://XXX.api.augmentcode.com/webhooks/XXX" \
  -H "Content-Type: application/json" \
  -H "X-Gitlab-Event: Push Hook" \
  -H "X-Gitlab-Token: whsec_XXX" \
  -d '{"event": "test", "data": "your payload here"}'

You should get this response:

text

HTTP/2 200
content-length: 30
content-type: application/json
date: Sun, 02 Aug 2026 23:23:23 GMT
via: 1.1 google
alt-svc: h3=":443"; ma=2592000

{"message":"Webhook accepted"}%

Webhook sender in Gitlab

Create a new webhook config in Gitlab** **(so Gitlab can POST to a given url when certain Gitlab events occur): as a Maintainer or Owner, go to your Gitlab repo > Settings > Webhooks > Add new webhook > Add those details:

Name: Notify Cosmos on MR created/updated/merged/commented
URL: the webhook url provided by Cosmos
Secret token: the secret provided by Cosmos
Trigger: Comments and Merge request events
Custom header: leave empty
Enable SSL verification: keep it selected
Click on Add webhook

Now run a test: in Gitlab go back to your list of Gitlab webhooks (Settings > Webhooks) > click on the Test dropdown > Merge request events

You should see this banner at the top:

Now go back to Cosmos and check that Cosmos received the event: Cosmos (https://cosmos.augmentcode.com) > Settings > Automations > Events Log. You should see your event with source “Webhook · GitLab”:

Click on the event to inspect the test payload:

At this point Gitlab will automatically notify Cosmos whenever a MR is created/updated/commented on ✅

Step 2 - Create a Gitlab Service Account

For headless automation and to start agentic workflows based on Gitlab events, you’ll create a dedicated Gitlab service account and its access token: Gitlab repo > Settings > Service accounts > Add service account > Add a name (ex: Cosmos-XXX) and username (ex: cosmos-xxx):

Then next to that service account > 3 dots > Manage access tokens

Click on Add new token:

Enter a token name (ex: Cosmos01)
Set a max expiration date as far out as possible
Select scope api
Click on Generate token

Click on the copy icon to copy the GITLAB_TOKEN in your clipboard

Now get back to Gitlab and add your Gitlab service account with role=Maintainer onto the repos where the service account should be able to read/post (add it per repo or add it to the group that manages all the repos): Go to your Gitlab repo(s) > Manage > Members > Invite members > add your Gitlab service account and click on Invite:

Now your Gitlab service account has permissions to collaborate across your repos.

Step 3 - Create a Augment service account

Before we start the websocket tunnel from your AWS EC2 instance to Cosmos, you’ll need to create a dedicated Augment service account, which will be used to authenticate and start the tunnel. As an admin go to https://app.augmentcode.com/ > Service Accounts > + Add Service Account > Add:

Then click on + Add API Token:

Enter an API Token Name (ex: Token01):

Click on Download JSON:

You’ll obtain a session.json, it will be used to authenticate the Cosmos daemon later on.

Step 4 - Create a Cosmos daemon pool

Since you’ll be leveraging a AWS EC2 VM to host your daemon, it’s important to think about uptime and resilience: your VM could loose network connectivity or have an outage. The best practice is to create a daemon pool and attach your daemons to that daemon pool. Then you can later have N daemons (1 per VM) all tied to the same daemon pool, and Cosmos will use that pool which will automatically route to the next available daemon. In this guide you’ll create 1 daemon pool and 1 daemon running in 1 VM, but you can extend that approach to spin up 2 more VMs (and their respective daemons) for max resilience. Go to Cosmos (https://cosmos.augmentcode.com) > Settings > Environments > Create an environment > Daemon Pool:

Configure the pool with:

Name: Team01-Pool-Gitlab-SelfHosted
Daemon connector: select the dedicated service account you created in the section earlier
Shared: toggle on
Workspace behavior: Isolated workspace

Then click on Create Pool:

You’ll get the confirmation that the pool has been created, note the pool-id:

Go back to your list of environments, you should see your pool (with no daemon online yet):

Step 5 - Configure your VM with local Gitlab repos, glab cli and Cosmos daemon

In this section you’ll configure a AWS EC2 VM with the following:

locally cloned Gitlab repos
glab cli so Cosmos local agents can communicate to Gitlab
a Cosmos pool + daemon (to establish an outbound websocket tunnel from AWS to Cosmos)

Create the VM, with git and NVM/node

Create a new AWS EC2 Linux instance (ex: Ubuntu x86_64 - ami-091138d0f0d41ff90) in a AWS VPC that will be able to reach your Gitlab Self-Hosted instance. Minimum config recommended: 4 vCPU, 16 GB RAM, 100 GB SSD

Then SSH onto the AWS EC2 instance. Install git

sudo apt update && sudo apt install git -y

Verify the installation

which git
git --version

Install NVM

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

Refresh the terminal profile

source ~/.bashrc

Install the latest Long-Term Support (LTS) version of Node & NPM

nvm install --lts

Verify the node install

node -v
npm -v

Git clone your Gitlab repos locally

Create a local ~/workspace/ folder In that workspace folder create folders for your Gitlab organizations In the corresponding organization folders, git clone your repos (you need at a minimum an empty git repo with at least one commit for the git worktree configuration to be valid and for the agent to start) You should have a “2 layers” folder structure like this:

~/workspace/augmentcode-sa1/REPO_A/.git
~/workspace/augmentcode-sa1/REPO_B/.git
~/workspace/augmentcode-sa2/REPO_C/.git
~/workspace/augmentcode-sa2/REPO_D/.git

Note: at this moment you have to own making sure that the git repos are locally cloned and are kept up to date regularly. In a future release, daemons will be able to handle that on your behalf - stay tuned

Install and authenticate the glab CLI

Install the glab cli: make sure you’re in your root folder, install the glab cli using this command:

LATEST_TAG=$(curl -s "https://gitlab.com/api/v4/projects/gitlab-org%2Fcli/releases" | grep -o '"tag_name":"[^"]*' | head -n 1 | cut -d'"' -f4) && LATEST_VER="${LATEST_TAG#v}" && wget "https://gitlab.com/gitlab-org/cli/-/releases/${LATEST_TAG}/downloads/glab_${LATEST_VER}_linux_amd64.deb" -O /tmp/glab_latest.deb && sudo dpkg -i /tmp/glab_latest.deb && rm /tmp/glab_latest.deb

Then authenticate the glab cli, run:

echo "<YOUR_GITLAB_PAT_TOKEN>" | glab auth login --hostname gitlab.yourdomain.com --stdin

You should see:

text

✓ Logged in as cosmos-xxx
✓ Stored your credentials in the configuration file.

Start the daemon

cd into ~/workspace/ run

nano session.json

Paste in there the content of session.json you retrieved earlier when creating the Augment service account. Then CTRL-O + RETURN to save the file and CTRL-X + RETURN to exit Install Auggie

npm install -g @augmentcode/auggie

Start the Cosmos daemon using the Augment service account and attach the daemon to the pool, run:

auggie daemon --augment-session-json "$(cat /path/to/session.json)" --pool-id <YOUR-POOL-ID> --discover-workspaces=2 --allow-indexing

That will start the daemon, note in your daemon logs:

“Launch dir is a non-git container; adopting N discovered git repo(s) as workspaces […]” ⇒ check that all your local git repos have been discovered
“Git worktree support: supported”
“Joining daemon pool: <YOUR-POOL-ID>”
“Indexing enabled for workspace: […]”
“Starting Auggie Daemon […]”
“Connecting to Cosmos…”

You can now see the daemon running from Cosmos: Cosmos (https://cosmos.augmentcode.com) > Settings > Environments:

If you click on the pool, then top right you can set this pool as default environment to run your agents:

Step 6 - Connectivity test

Now you’ll create a session in Cosmos (cloud) and verify it can connect to the VM, make sense of the local repos and from that VM reach out to Gitlab via the glab CLI. Go to Cosmos > New Session (https://cosmos.augmentcode.com/home) Under the prompt, click on the dropdown list with the cloud icon > select Daemon > select your daemon pool:

Prompt the session with What are those repos about?, you should see a response powered by the Augment Context Engine that already made sense of your repos:

The connectivity between Cosmos (cloud) and your local VM has been verified ✅ Now prompt the session with: Use the glab cli to look up <INSERT-LINK-TO-ONE-OF-YOUR-GITLAB-MR>

Observe that the Cosmos session was able to use the glab cli to lookup the MR.

Step 7 - Create your Cosmos Experts

Now that connectivity is established, you can focus on deploying your Cosmos experts. You can follow the steps in https://docs.augmentcode.com/cosmos/gitlab-cloud#step-3-create-a-mr-deep-reviewer-expert to create a MR author, MR Deep Code Reviewer etc. The only key difference is you’ll have to explicitly instruct Cosmos Advisor to do the following when deploying those experts:

use the glab cli (instead of the native Gitlab Cloud integration)
use your daemon pool (instead of the cloud environment)
use the Gitlab webhook (instead of the native Gitlab Cloud integration)

Congratulations, you’ve integrated Cosmos with Gitlab Self-Hosted and deployed your first MR experts! 🎉

Getting Started

Cosmos

Auggie CLI

Other clients

Admin

Models & Pricing

Troubleshooting

Integrate GitLab Self-Hosted

Introduction

Prerequisites

Step 1 - Configure Gitlab to notify a Cosmos Webhook

Webhook receiver in Cosmos

Webhook sender in Gitlab

Step 2 - Create a Gitlab Service Account

Step 3 - Create a Augment service account

Step 4 - Create a Cosmos daemon pool

Step 5 - Configure your VM with local Gitlab repos, glab cli and Cosmos daemon

Create the VM, with git and NVM/node

Git clone your Gitlab repos locally

Install and authenticate the glab CLI

Start the daemon

Step 6 - Connectivity test

Step 7 - Create your Cosmos Experts

​Introduction

​Prerequisites

​Step 1 - Configure Gitlab to notify a Cosmos Webhook

​Webhook receiver in Cosmos

​Webhook sender in Gitlab

​Step 2 - Create a Gitlab Service Account

​Step 3 - Create a Augment service account

​Step 4 - Create a Cosmos daemon pool

​Step 5 - Configure your VM with local Gitlab repos, glab cli and Cosmos daemon

​Create the VM, with git and NVM/node

​Git clone your Gitlab repos locally

​Install and authenticate the glab CLI

​Start the daemon

​Step 6 - Connectivity test

​Step 7 - Create your Cosmos Experts

Introduction

Prerequisites

Step 1 - Configure Gitlab to notify a Cosmos Webhook

Webhook receiver in Cosmos

Webhook sender in Gitlab

Step 2 - Create a Gitlab Service Account

Step 3 - Create a Augment service account

Step 4 - Create a Cosmos daemon pool

Step 5 - Configure your VM with local Gitlab repos, glab cli and Cosmos daemon

Create the VM, with git and NVM/node

Git clone your Gitlab repos locally

Install and authenticate the glab CLI

Start the daemon

Step 6 - Connectivity test

Step 7 - Create your Cosmos Experts