GitLab Toolkit

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.

aviso

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

1. Open GitLab

   Sign in to GitLab.com or your organization's self-hosted GitLab instance.

2. Create a Personal Access Token

   Go to User Settings → Access Tokens, create a token with the api scope, and copy it securely.

3. Identify a GitLab project

   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.

4. Add GitLab in EKB

   Open the required EKB agent or workflow, add the GitLab toolkit, and select a GitLab action.

5. Create a GitLab connection

   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.

6. Configure an action

   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.

7. Run and verify

   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.