# 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;
3. Enter your GitLab credentials:
* **GitLab URL**: Your GitLab instance URL (e.g., `https://gitlab.com`);
* **API Token**: The token generated above.
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:
## 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-` |
| 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.
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 |
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.akamas.io/insights/applying-changes/applying-recommendations/gitlab.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.