> For the complete documentation index, see [llms.txt](https://docs.akamas.io/insights/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.akamas.io/insights/applying-changes/applying-recommendations/gitlab.md).

# GitLab Integration

Integrate Akamas Insights with GitLab to automatically create merge requests with recommended resource configurations. This enables **GitOps** workflows where infrastructure changes go through code review **before** reaching **production**.

## Prerequisites

* GitLab account with access to target repository;
* API token with required permissions (see [Generate API Token](#generate-api-token));
* Repository containing Kubernetes deployment manifests.

## Setup

### Generate API Token

Create a GitLab API token with the following requirements:

| Token Type            | Scope | Minimum Role |
| --------------------- | ----- | ------------ |
| Personal Access Token | `api` | Developer    |
| Project Access Token  | `api` | Developer    |

To create a token:

1. Navigate to **Settings > Access Tokens** (user or project level);
2. Select the `api` scope;
3. Set an expiration date;
4. Click **Create token** and save the value.

### Configure VCS Provider

1. In Akamas Insights, go to **Plan > VCS Configuration;**
2. Select **GitLab** as the provider;

<figure><img src="/files/gRxvq2DonfwyBJTUuBwR" alt=""><figcaption></figcaption></figure>

3. Enter your GitLab credentials:

* **GitLab URL**: Your GitLab instance URL (e.g., `https://gitlab.com`);
* **API Token**: The token generated above.

<figure><img src="/files/qCyS9PXxJlXgqE50njIU" alt=""><figcaption></figcaption></figure>

4. Click **Save** to store the configuration.

## Create a Merge Request

After completing the setup, create merge requests for workload recommendations:

1. Navigate to **Workloads** and select a workload;
2. Review the recommendation and click **Apply Now;**
3. Select **Open a merge request.**

The wizard guides you through the configuration:

![Merge Request Wizard - Step 1](/files/1ktgleC3Y7vmFsFpESI3)

## Step 1 - Configuration

### Connection

| Field      | Description                                         |
| ---------- | --------------------------------------------------- |
| GitLab URL | Your GitLab instance URL (pre-filled from settings) |
| API Token  | Your API token (pre-filled from settings)           |

Click **Test connection** to verify credentials. A success message confirms the connection is established.

### Repository and Branches

| Field         | Description                                     | Example                         |
| ------------- | ----------------------------------------------- | ------------------------------- |
| Project URI   | Repository containing your deployment manifests | `my-org/k8s-manifests`          |
| New Branch    | Branch name for the recommended changes         | `feat/optimize-<workload-name>` |
| Source Branch | Base branch for the merge request               | `main`                          |

### Files and Services Configuration

| Field               | Description                                | Example                          |
| ------------------- | ------------------------------------------ | -------------------------------- |
| File Path           | Path to the deployment manifest            | `deployments/my-app/values.yaml` |
| Resources YAML Path | Dot notation path to the `resources` block | `spec.containers.resources`      |

#### JVM Optimization

When a workload includes JVM optimization recommendations, an additional field appears:

| Field           | Description                          | Example               |
| --------------- | ------------------------------------ | --------------------- |
| JAVA\_OPTS Path | Dot notation path to the JVM options | `spec.containers.env` |

{% hint style="warning" %}
This field requires a single `JAVA_OPTS` environment variable. Multiple `JAVA_*` variables are not supported.
{% endhint %}

### Advanced Settings

Expand **Advanced Settings** to configure:

| Field          | Description                       |
| -------------- | --------------------------------- |
| Commit message | Custom message for the commit     |
| Approver       | GitLab user to assign as reviewer |

### Submit

Click **Next** to review and create the merge request. Akamas Insights will:

1. Create a new branch from your source branch;
2. Commit the recommended changes to the YAML file;
3. Open a merge request with the specified reviewer.

## Step 2 - Review and Create

This step displays a summary of the changes before creating the merge request:

* **Recommendation preview**: The resource configuration changes to be applied;
* **Target file**: The YAML file that will be modified;
* **Branch details**: Source and target branch names.

![Merge Request Wizard - Step 2](/files/DODvV7nESFZbZDXfH1R6)

Click **Create Merge Request** to submit. Once created, you can review and merge the changes in GitLab.

## Troubleshooting

| Issue                 | Solution                                                     |
| --------------------- | ------------------------------------------------------------ |
| Connection test fails | Verify token has `api` scope and Developer role              |
| Repository not found  | Check token has access to the project                        |
| Permission denied     | Ensure token owner has push access to the repository         |
| Branch already exists | Choose a different branch name or delete the existing branch |
| File not found        | Verify the file path exists in the source branch             |
| Merge conflict        | Manually resolve conflicts in GitLab before retrying         |