> ## Documentation Index
> Fetch the complete documentation index at: https://ai-kb.automationanywhere.com/llms.txt
> Use this file to discover all available pages before exploring further.
# GitLab Toolkit
> Connects GitLab projects to EKB agents and workflows for managing projects, merge requests, issues, repositories, and CI/CD pipelines.
The GitLab toolkit lets EKB agents and workflows work with GitLab projects through a Personal Access Token (PAT). You can inspect projects, manage merge requests and issues, view branches and repository files, review commit history, and monitor CI/CD pipelines and jobs.
## Prerequisites
* An active GitLab account on GitLab.com or a self-hosted GitLab instance.
* Permission to create a GitLab Personal Access Token.
* A Personal Access Token with the `api` scope.
* Access to at least one GitLab project.
* An EKB project where you can configure an agent or workflow.
* GitLab permissions appropriate for the actions you intend to run.
Never place the Personal Access Token in workflow inputs, prompts, screenshots, tickets, logs, or documentation. The toolkit does not grant additional GitLab permissions; all actions run with the access level of the account that owns the configured token.
## Setup
Sign in to GitLab.com or your organization's self-hosted GitLab instance.
Go to **User Settings → Access Tokens**, create a token with the `api` scope, and copy it securely.
Open the project you want to use. You can use its numeric project ID or URL-encoded project path. You can also use **List Projects** or **Search Projects** to find accessible projects.
Open the required EKB agent or workflow, add the **GitLab** toolkit, and select a GitLab action.
Enter the GitLab Instance URL for self-hosted GitLab, then securely provide the Personal Access Token. Leave the Instance URL empty when using GitLab.com.
Start with **List Projects** to confirm access. Use the returned project ID in later actions such as **Get Project**, **List Merge Requests**, or **List Issues**.
Run the agent or workflow step and confirm that GitLab project data is returned successfully.
## Available tools
### Project Management
| Tool | Description |
| ------------------- | ---------------------------------------------------------- |
| **List Projects** | Lists projects accessible to the connected GitLab account. |
| **Get Project** | Returns details for a GitLab project. |
| **Search Projects** | Searches accessible GitLab projects by name or keyword. |
### Merge Request Management
| Tool | Description |
| ----------------------------- | --------------------------------------------------------- |
| **List Merge Requests** | Lists merge requests in a project. |
| **Get Merge Request** | Returns details for a merge request. |
| **Create Merge Request** | Creates a merge request between two existing branches. |
| **Get Merge Request Diffs** | Returns changed files and patch text for a merge request. |
| **Get Merge Request Commits** | Returns the commits included in a merge request. |
| **Add Merge Request Note** | Adds a general note to a merge request. |
### Issue Management
| Tool | Description |
| ------------------ | ------------------------------------------------ |
| **List Issues** | Lists issues in a project. |
| **Get Issue** | Returns details for an issue. |
| **Create Issue** | Creates an issue in a project. |
| **Update Issue** | Updates one or more fields on an existing issue. |
| **Add Issue Note** | Adds a general note to an issue. |
### Branch and File Management
| Tool | Description |
| ---------------------- | ------------------------------------------------------------------------ |
| **List Branches** | Lists repository branches in a project. |
| **Get File Content** | Returns decoded text content for a repository file. |
| **Get Commit History** | Lists project commits, optionally filtered by branch, tag, or file path. |
### CI/CD Pipelines
| Tool | Description |
| ---------------------- | ------------------------------------------------- |
| **List Pipelines** | Lists CI/CD pipelines in a project, newest first. |
| **Get Pipeline** | Returns details for a pipeline. |
| **List Pipeline Jobs** | Lists jobs in a pipeline. |
## Use cases
* Find an accessible GitLab project and use its project ID in subsequent actions.
* Review an open merge request by retrieving its details, diffs, and commits, then posting review feedback.
* Create and update issues automatically from monitoring or deployment workflows.
* Inspect repository branches, files, and commit history to understand recent changes.
* Investigate failed CI/CD pipelines by identifying the pipeline, its status, and affected jobs.
## Troubleshooting
| Symptom | Likely cause | Fix |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `401 Unauthorized` | The Personal Access Token is invalid, expired, revoked, or incorrectly entered. | Create a new GitLab Personal Access Token with the `api` scope, update the GitLab connection in EKB, and run **List Projects** to verify access. |
| `403 Forbidden` | The token owner does not have permission for the requested action. | Confirm that the GitLab account has access to the project and the required permissions for the action. |
| `404 Project Not Found` | The project ID or project path is incorrect, or the token owner cannot access a private project. | Run **List Projects** or **Search Projects** and use an accessible numeric project ID or full project path. |
| Merge request cannot be created | The source or target branch does not exist, the branches are invalid, or the account lacks permission. | Run **List Branches** to confirm the branch names and verify merge request permissions. |
| Merge request has conflicts | The source branch conflicts with the target branch. | Run **Get Merge Request** and check `has_conflicts`. Resolve the conflict in GitLab and rerun the action if needed. |
| Issue cannot be created or updated | The account lacks issue permissions, the project is incorrect, or no update values were supplied. | Confirm project access. For **Update Issue**, provide at least one of `title`, `description`, `state_event`, or `labels`. |
| No projects returned | The account has no accessible projects, or the project filter is too restrictive. | Check the GitLab account and remove `search`, `owned`, or `membership` filters before running **List Projects** again. |
| No merge requests, issues, branches, or pipelines returned | The project has no matching resources, the filter is too restrictive, or the project ID is incorrect. | Confirm the project ID with **Get Project** and remove optional filters such as `state`, `status`, `labels`, `assignee`, or `search`. |
| File cannot be found | The file path or reference is incorrect. | Use the repository-relative file path and confirm the branch, tag, or commit SHA in `ref`. |
| Pipeline or pipeline job cannot be found | The pipeline ID is incorrect or belongs to another project. | Run **List Pipelines** for the same project and use the returned pipeline ID with **List Pipeline Jobs**. |
| Self-hosted GitLab connection fails | The GitLab Instance URL is incorrect, EKB cannot reach the instance, or its certificate is not trusted. | Use the full HTTPS URL and confirm that EKB can reach the instance and its TLS certificate is valid. |
| Workflow step appears successful but GitLab action failed | The toolkit returns failures through the `error` value in the response. | Check `{{ step.output.error }}` in the workflow and route the error to notification, retry, or manual review. |
| Rate limit or temporary GitLab API error | GitLab has throttled requests or the service is temporarily unavailable. | Reduce request frequency, use pagination, wait before retrying, and avoid automatically repeating write actions that could create duplicates. |