> ## 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.

# Advanced Expert Configuration — Connecting GitLab or Jira

> Connect GitLab and Jira to Cosmos using custom webhooks and MCP servers for code reviews and ticket-to-PR automation.

The built-in integrations cover GitHub, Slack, and Linear. For everything else — GitLab, Jira, your internal ticket tracker — the recipe is the same two pieces:

* A **custom webhook** for the upstream service to POST into.
* An **MCP server** so your Expert can write back.

Below: the end-to-end version for GitLab merge requests and Jira tickets.

## Connect GitLab to a Code Review Expert

Use this flow when you want Cosmos to receive GitLab MR events, run a code review, and post the results back onto the MR.

### Step 1: Create a Cosmos webhook URL for GitLab

You need an HTTPS endpoint GitLab can POST to. Cosmos provisions one for you.

1. Go to **Configuration → Webhooks** and click **Create a new webhook**.
2. Copy the webhook URL and bearer secret — you can't retrieve the secret later.

Confirm the URL works with a quick curl:

```bash 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"}'
```

### Step 2: Point GitLab at the Cosmos webhook

Now tell GitLab to POST to that URL whenever a merge request changes.

1. In GitLab, open your repo → **Settings → Webhooks → Add new webhook**.
2. Fill in:
   * **Name** — anything recognizable.
   * **URL** — the Cosmos webhook URL.
   * **Secret Token** — leave blank. This field sets a separate `X-Gitlab-Token` header that Cosmos ignores; authentication runs through the `Authorization` header instead.
   * **Trigger** — **Merge request events**.
   * **Custom Headers → Add custom header** — name `Authorization`, value `Bearer <the secret provided by Cosmos>`.
   * **Enable SSL verification** — keep selected.
3. Save changes.

### Step 3: Verify the events are reaching Cosmos

1. In GitLab's webhook list, click **Test → Merge request events**.
2. In Cosmos, open **Configuration → Events log** and look for your event with source **Custom**.
3. Click the event to inspect the full payload.

If you don't see the event, double-check the bearer header and the URL on the GitLab webhook.

### Step 4: Let Cosmos write back to GitLab

To post a code review back onto the MR, Cosmos needs a GitLab service account and access token. Store the token in the Cosmos Secrets Manager so it's available in every Expert session.

**Create the GitLab service account and token:**

1. In GitLab, open your repo → **Settings → Service accounts → Add service account** and give it a name.
2. Next to the service account, click the **three-dot menu → Manage access tokens**.
3. Click **Add new token** and configure:
   * **Token name**.
   * **Expiration date** — you'll need to rotate this token periodically and update its value in Cosmos.
   * **Scope**: `api`.
4. Click **Generate token** and copy the value immediately.

**Store the token in Cosmos:**

1. Open [https://app.augmentcode.com/app/secrets](https://app.augmentcode.com/app/secrets), click **Add Secret**, and choose **Environment Variable**.
2. Configure:
   * **Name**: `GITLAB_SERVICE_ACCOUNT_ACCESS_TOKEN`.
   * **Value**: the token you copied from GitLab.
   * **Visibility — Shared**: leave off.
   * **Automatically install in VMs**: keep selected.
3. Click **Create Secret**.

The token is now auto-injected as `$GITLAB_SERVICE_ACCOUNT_ACCESS_TOKEN` into every Expert session that uses this environment. To verify, start a new session and prompt: *"Check whether GITLAB\_SERVICE\_ACCOUNT\_ACCESS\_TOKEN is set in this workspace."*

## Connect Jira to a Ticket-to-PR Expert

Use this flow when you want Cosmos to react to Jira tickets being created or updated, then read and update them through the Atlassian remote MCP server.

### Step 1: Create a Cosmos webhook URL for Jira

In Cosmos, go to **Configuration → Webhooks → Create a new webhook** and copy the URL and bearer secret.

### Step 2: Create a Jira automation rule that POSTs to Cosmos

Tell Jira to forward ticket events to your webhook.

1. In Jira, click the **⚙️ (Settings)** icon → **System**.
2. In the left nav, go to **Automation → Global automation**.
3. Top right, click **Create rule → Create from scratch**.
4. On the **Add a trigger** view, select **Work item created**.
5. Click **Add component** under the When block, then select **THEN: Add an action**.
6. Search for and select **Send web request**, then configure:
   * **Web request URL** — the Cosmos webhook URL.
   * **HTTP method** — `POST`.
   * **Web request body** — `Issue data (Automation format)`.
   * **Headers**:
     * `Authorization: Bearer <cosmos-webhook-secret>`
     * `Content-Type: application/json`
7. Click **Rule details**, give it a name, and keep scope as **Global** with actor **Automation for Jira**.
8. Click **Turn on rule**.

### Step 3: Verify the events are reaching Cosmos

Create a new Jira ticket, then open **Configuration → Events log** in Cosmos. You should see the event with source **Custom** containing the ticket details. If not, double-check the headers and URL on the automation rule.

### Step 4: Create an Atlassian service account

Cosmos writes back to Jira through the Atlassian remote MCP server. Most use cases run headless, so use a dedicated service account rather than a personal one.

1. As an Atlassian admin, open [https://admin.atlassian.com](https://admin.atlassian.com).

2. Go to **Directory → Service Accounts → Create a service account** and configure:
   * **Name**: `Augment Code`.
   * **App**: `Jira`. **Role**: `User`.
   * Save.

3. On the new service account, click **Create credentials** and choose authentication type **API token**.

4. Give it a name and expiration date (max 1 year).

5. Select the following scopes:

   **Read:** `read:jira-work`, `read:jira-user`, `read:comment:jira`, `read:comment.property:jira`

   **Write:** `write:jira-work`, `write:comment:jira`, `write:comment.property:jira`, `write:request.comment:jira-service-management`

   **Manage (optional):** `manage:servicedesk-customer`, `manage:jira-webhook`, `manage:jira-project`, `manage:jira-data-provider`, `manage:jira-configuration`

6. Click **Next → Create** and copy the API token somewhere safe.

### Step 5: Register the Atlassian MCP server in Cosmos

1. Go to **Configuration → MCP Registry** ([https://app.augmentcode.com/app/mcp](https://app.augmentcode.com/app/mcp)).
2. Click **Add server → Remote MCP**.
3. Configure:
   * **Name**: `Atlassian MCP server`.
   * **Connection type**: `HTTP`.
   * **Server URL**: `https://mcp.atlassian.com/v1/mcp`.
   * **Authentication type**: `Header` — header name `Authorization`, header value `Bearer <your-service-account-api-token>`.
   * Keep **CLI** and **Cloud Agents** enabled.
   * **Visibility**: switch to **Shared** so the MCP server and service account are reusable across your team.
4. Click **Add Server**.

### Step 6: Confirm end-to-end connectivity

1. Start a new session with the Atlassian MCP server attached.
2. Prompt the agent to look up a Jira ticket by URL.
3. Prompt it to add a comment to that ticket and confirm the comment appears in Jira.

If the round-trip works, you're done. Attach the Jira webhook and the Atlassian MCP server to an Expert and let it loose.