GitLab

Introduction

This guide is your comprehensive resource for integrating and utilizing the GitLab toolkit within ELITEA. It provides detailed, step-by-step instructions, from setting up your GitLab Personal Access Token to configuring the toolkit in ELITEA and effectively using it within your Agents, Pipelines, and Chat conversations. By following this guide, you will unlock the power of automated code management, streamlined development workflows, and enhanced team collaboration, all directly within the ELITEA platform. Brief Overview of GitLab GitLab is a powerful, web-based DevOps platform that provides a comprehensive suite of tools for the entire software development lifecycle, delivered as a single, integrated application. It is widely adopted by development teams for its robust features and collaborative environment, offering features for:

Centralized Git Repository Management: GitLab provides a robust and scalable platform for hosting and managing Git repositories, ensuring efficient version control, code organization, and secure access management for your entire codebase.
Enhanced Collaboration Features: GitLab fosters seamless team collaboration with features such as Merge Requests for code review, robust Issue Tracking for project management, Wikis for documentation, and in-line Code Review tools, facilitating a collaborative and transparent development process.
Integrated CI/CD Pipelines: GitLab CI/CD is a powerful built-in Continuous Integration and Continuous Delivery system that automates the entire software pipeline, from building and testing code to deploying applications, enabling rapid and reliable software releases.
Comprehensive Project Management Tools: GitLab includes a rich set of project planning and management features, such as Issue Boards for agile task management, Milestones for tracking progress against deadlines, and Time Tracking to monitor effort, streamlining software development workflows and improving project visibility.
DevSecOps Capabilities: GitLab integrates security scanning and testing throughout the DevOps lifecycle, enabling teams to build secure applications and proactively address vulnerabilities early in the development process.

Integrating GitLab with ELITEA brings these powerful DevOps capabilities directly into your AI-driven workflows. Your ELITEA Agents, Pipelines, and Chat conversations can intelligently interact with your GitLab repositories to automate code-related tasks, enhance development processes, and improve team collaboration.

Toolkit’s Account Setup and Configuration

Account Setup If you don’t have a GitLab account yet, here’s how to get started:

Visit GitLab Website: Open your web browser and navigate to GitLab’s official website.
Sign Up: Click on the “Register” or “Sign Up” button, typically located in the top right corner of the homepage.
Fill Out the Registration Form: Provide your details in the registration form. This typically includes your username, email address, full name, and a secure password. For professional use, it’s highly recommended to use your company email.
Submit the Form: Click on the “Register” or similar button to submit the form. GitLab will send a confirmation email to the email address you provided.
Verify Your Email: Open the confirmation email from GitLab and click on the verification link provided within the email. This step is crucial to activate your GitLab account.
Access Your Account: After email verification, you will be redirected to your GitLab account or prompted to log in. You are now ready to proceed with GitLab configuration.

Generate a Personal Access Token

For secure integration with ELITEA, it is essential to use a GitLab Personal Access Token. This method is significantly more secure than using your primary GitLab account password directly and allows you to precisely control the permissions granted to ELITEA. Follow these steps to generate a Personal Access Token in GitLab:

Log in to GitLab: Access your GitLab account using your credentials.
Access User Settings: Click on your profile avatar in the top right corner of the GitLab interface. From the dropdown menu, select “Edit profile”.
Navigate to Access Tokens: In the left-hand sidebar of your profile settings, click on “Access Tokens”.
Add New Token: Click the “Add new token” button to create a new Personal Access Token.
Configure Token Details:
- Token name: In the “Token name” field, enter a descriptive name for the token, such as “ELITEA Integration Token”. This will help you identify the purpose of this token later.
- Expiration date (Recommended): For enhanced security, it is strongly recommended to set an Expiration date for your token. Choose a reasonable validity period that aligns with your security policies and integration needs.
- Select Scopes - Grant Least Privilege (Crucial for Security): Carefully select the scopes or permissions you grant to this Personal Access Token. It is crucial to grant only the minimum necessary permissions required for your ELITEA Agent’s intended interactions with GitLab. !!! tip “Token Scopes” Minimal Scopes for Common Use Cases:
  - api: Provides full access to the GitLab API. If possible, for enhanced security, consider using more granular scopes
  - read_api: Read-only access to the API
  - read_repository: Read-only access to repositories
  - write_repository: Write access to repositories. Include only if your Agent needs to modify repositories
  Additional Scopes for Specific Functionality (Grant only when required):
  - read_user: Read access to user profiles
  - read_issue: Read access to issues
  - write_issue: Write access to issues. Include only if your Agent needs to manage issues
  - read_merge_requests: Read access to merge requests
  - write_merge_requests: Write access to merge requests. Include only if your Agent needs to manage merge requests
Create Personal Access Token: Click the “Create personal access token” button to generate your token.
Securely Copy and Store Your Token: Immediately copy the generated Personal Access Token. This is the only time it will be displayed in full. Store it securely in a password manager or, preferably, ELITEA’s built-in Secrets feature for enhanced security within ELITEA. You will need this token to configure the GitLab toolkit in ELITEA.

Principle of Least Privilege: Grant only the permissions absolutely essential for your ELITEA integration tasks.Never Share Tokens: Treat your Personal Access Token like a password. Do not share it publicly or commit it to version control systems.Regular Token Review and Rotation: Regularly review generated tokens and rotate them periodically as a security best practice.

System Integration with ELITEA

To integrate GitLab with ELITEA, you need to follow a three-step process: Create Credentials → Create Toolkit → Use in Agents. This workflow ensures secure authentication and proper configuration.

Step 1: Create GitLab Credentials

Before creating a toolkit, you must first create GitLab credentials in ELITEA:

Navigate to Credentials Menu: Open the sidebar and select Credentials.
Create New Credential: Click the + Create button.
Select GitLab: Choose GitLab as the credential type.

Configure Credential Details:

Field	Description	Example
Display Name	Descriptive name for easy identification	`GitLab - Development Team`
ID	Unique identifier for the credential	Auto-generated
URL	Your GitLab instance URL	`https://gitlab.com` or `https://gitlab.yourcompany.com`
Private Token	Your GitLab Personal Access Token	`your-personal-access-token`

Test Connection: Click Test Connection to verify your credentials are valid and ELITEA can connect to GitLab
Save Credential: Click Save to create the credential !!! tip “Security Recommendation” It’s highly recommended to use Secrets for Personal Access Tokens instead of entering them directly. Create a secret first, then reference it in your credential configuration.

Step 2: Create GitLab Toolkit

Once your credentials are configured, create the GitLab toolkit:

Navigate to Toolkits Menu: Open the sidebar and select Toolkits.
Create New Toolkit: Click the + Create button.
Select GitLab: Choose GitLab from the list of available toolkit types.

Configure Toolkit Settings:

Field	Description	Example
Toolkit Name	Descriptive name for your toolkit	`GitLab - MyProject Repo`
Description	Optional description for the toolkit	`GitLab toolkit for development team`
GitLab Configuration	Select your previously created GitLab credential	`GitLab - Development Team`
PgVector Configuration	(Optional) Select PgVector for indexing features	Your PgVector configuration
Embedding Model	(Optional) Select embedding model for semantic search	`amazon.titan-embed-text-v2:0`
Repository	Enter repository name in format `namespace/repository`	`mygroup/my-project`
Branch	Enter the main branch name	`main`

Enable Desired Tools: In the “Tools” section, select the checkboxes next to the specific GitLab tools you want to enable. Enable only the tools your agents will actually use
- Make Tools Available by MCP - (optional checkbox) Enable this option to make the selected tools accessible through external MCP clients
Save Toolkit: Click Save to create the toolkit

Available Tools:

The GitLab toolkit provides the following tools for interacting with GitLab repositories, organized by functional categories:

Tool Category	Tool Name	Description	Primary Use Case
Branch Management
	Create branch	Creates a new branch from the active branch. Automatically sets the new branch as active after creation. Returns success message or handles conflicts if branch already exists	Set up new feature branches or bug fix branches for development work
	Delete branch	Deletes a branch from the repository with proper validation and error handling	Remove obsolete or merged feature branches to maintain repository cleanliness
	List branches in repo	Lists branches in the repository with optional limit parameter (default: 20) and wildcard filtering support (e.g., ‘*dev’)	View all branches or find specific branches matching a pattern for branch management
	Set active branch	Switches the active branch for subsequent operations. Validates branch existence before switching and provides helpful error messages with available branches	Switch context to work on a specific branch for file operations and merge requests
File Operations
	Append file	Appends new content to the end of an existing file without overwriting existing content	Add log entries, update changelog files, or append data to existing files
	Create file	Creates a new file in the GitLab repository at the specified path with provided contents and commits it to the specified branch	Add new configuration files, documentation, or source code to the repository
	Delete file	Deletes a file from the repository with proper commit message and branch specification	Remove obsolete files, clean up temporary files, or maintain repository hygiene
	Edit file	Edits an existing file with enhanced validation and error handling capabilities	Modify file contents with improved change tracking and validation
	Grep file	Searches for patterns within files using grep-like functionality across the repository	Find specific code patterns, text occurrences, or search within file contents
	List files	Lists files in the repository with optional path filter and branch specification. Supports filtering by directory path	Browse repository structure, explore directories, or locate specific file paths
	List folders	Lists folders in the repository with optional path filter, recursive/non-recursive search control, and branch specification	Explore directory structure and organize file operations
	Read file	Reads and returns the complete contents of a file from the repository at the specified branch	Retrieve file contents for review, analysis, or processing by the AI agent
	Read multiple files	Reads and returns contents of multiple files in a single operation for improved efficiency	Retrieve multiple file contents simultaneously for batch processing or analysis
	Update file	Updates an existing file using OLD/NEW marker format for content replacement. Validates changes and provides detailed error messages if markers are malformed	Modify existing file contents with explicit old-to-new content transformations
Issue Management
	Comment on issue	Adds a comment to an existing GitLab issue with support for markdown formatting	Provide updates, feedback, or status changes on issues
	Get issue	Retrieves complete details of a specific issue by number including the first 10 comments	Access detailed information about a particular issue for review or analysis
	Get issues	Retrieves all open issues from the repository with their titles, descriptions, labels, and metadata	Track project tasks, bugs, and feature requests across the project
Merge Request Management
	Comment on pr	Adds a general comment to a merge request for discussion or feedback	Provide overall feedback or discussion points on a merge request
	Create pr change comment	Adds a comment to specific changes within a merge request at a particular file path and line number	Provide targeted feedback on code modifications during code review
	Create pull request	Creates a merge request from the specified branch to the main branch using JSON data specification. Returns MR details including URL upon success	Initiate code review process for changes made by the agent or automation
	Get pr changes	Retrieves the diff/changes from a merge request showing file modifications, additions, and deletions	Examine specific file changes and modifications included in a merge request
Version Control
	Get commits	Retrieves a list of commits from the repository with optional filtering by SHA, path, date range, and author	Track project history, analyze code changes over time, and understand development activity
Indexing & Search
	Index data	Loads GitLab repository data into PgVector for semantic search. Requires PgVector configuration and embedding model to create searchable code index	Enable AI-powered semantic search across repository code for intelligent code discovery
	List collections	Lists all available indexed collections in the PgVector database to identify searchable datasets	View and manage indexed data collections to understand what code bases are searchable
	Remove index	Removes previously created search indexes from PgVector to free resources or refresh data	Clean up outdated indexes or prepare for re-indexing with updated repository content
	Search index	Performs semantic searches across indexed repository content using natural language queries	Find specific code patterns, implementations, or documentation using AI-powered search
	Stepback search index	Performs advanced contextual searches with broader scope, using step-back prompting to generate better search queries	Execute sophisticated searches requiring broader context understanding and query refinement
	Stepback summary index	Creates comprehensive summaries of indexed content using step-back prompting for more thorough analysis	Generate intelligent, context-aware summaries of repository code and documentation

The tools Index data, List collections, Remove index, Search index, Stepback search index, and Stepback summary index require PgVector configuration and an embedding model. These enable advanced semantic search capabilities across your GitLab repository.

Testing Toolkit Tools

After configuring your GitLab toolkit, you can test individual tools directly from the Toolkit detailed page using the Test Settings panel. This allows you to verify that your credentials are working correctly and validate tool functionality before adding the toolkit to your workflows. General Testing Steps:

Select LLM Model: Choose a Large Language Model from the model dropdown in the Test Settings panel
Configure Model Settings: Adjust model parameters like Creativity, Max Completion Tokens, and other settings as needed
Select a Tool: Choose the specific GitLab tool you want to test from the available tools
Provide Input: Enter any required parameters or test queries for the selected tool
Run the Test: Execute the tool and wait for the response
Review the Response: Analyze the output to verify the tool is working correctly and returning expected results

Verify that GitLab credentials and connection are configured correctly
Validate that tools function as expected with your GitLab repository
Test different parameter combinations and edge cases before production use
Familiarize yourself with tool capabilities and expected outputs

For detailed instructions on how to use the Test Settings panel, see How to Test Toolkit Tools.

Step 3: Use GitLab Toolkit in Agents

Once your GitLab toolkit is created, you can use it in various ELITEA features:

In Agents:

Navigate to Agents: Open the sidebar and select Agents.
Create or Edit Agent: Click + Create for a new agent or select an existing agent to edit.
Add GitLab Toolkit:
- In the “TOOLKITS” section of the agent configuration, click the “+Toolkit” icon
- Select your GitLab toolkit from the dropdown menu
- The toolkit will be added to your agent with the previously configured tools enabled

Your agent can now interact with GitLab using the configured toolkit and enabled tools.

In Pipelines:

Navigate to Pipelines: Open the sidebar and select Pipelines.
Create or Edit Pipeline: Either create a new pipeline or select an existing pipeline to edit.
Add GitLab Toolkit:
- In the “TOOLKITS” section of the pipeline configuration, click the “+Toolkit” icon
- Select your GitLab toolkit from the dropdown menu
- The toolkit will be added to your pipeline with the previously configured tools enabled

In Chat:

Navigate to Chat: Open the sidebar and select Chat.
Start New Conversation: Click +Create or open an existing conversation.
Add Toolkit to Conversation:
- In the chat Participants section, look for the Toolkits element
- Click to add a toolkit and select your GitLab toolkit from the available options
- The toolkit will be added to your conversation with all previously configured tools enabled
Use Toolkit in Chat: You can now directly interact with your GitLab repositories by asking questions or requesting actions that will trigger the GitLab toolkit tools.

Instructions and Prompts for Using the GitLab Toolkit

To effectively instruct your ELITEA Agent to use the GitLab toolkit, you need to provide clear and precise instructions within the Agent’s “Instructions” field. These instructions are crucial for guiding the Agent on when and how to utilize the available GitLab tools to achieve your desired automation goals.

Instruction Creation for Agents

When crafting instructions for the GitLab toolkit, especially for OpenAI-based Agents, clarity and precision are paramount. Break down complex tasks into a sequence of simple, actionable steps. Explicitly define all parameters required for each tool and guide the Agent on how to obtain or determine the values for these parameters. Agents respond best to instructions that are:

Direct and Action-Oriented: Employ strong action verbs and clear commands to initiate actions. For example, “Use the ‘read_file’ tool…”, “Create a branch named…”, “List all open issues…”.
Parameter-Centric: Clearly enumerate each parameter required by the tool. For each parameter, specify:
- Its name (exactly as expected by the tool)
- Its expected data type (string, integer, JSON object, etc.)
- How the Agent should obtain the value – whether from user input, derived from previous steps in the conversation, retrieved from an external source, or a predefined static value
Contextually Rich: Provide sufficient context so the Agent understands the overarching objective and the specific scenario in which each GitLab tool should be applied within the broader workflow. Explain the desired outcome or goal for each tool invocation.
Step-by-Step Structure: Organize instructions into a numbered or bulleted list of steps for complex workflows. This helps the Agent follow a logical sequence of actions.
Add Conversation Starters: Include example conversation starters that users can use to trigger this functionality. For example, “Conversation Starters: ‘Create a new branch’, ‘Show me the README’, ‘List all open issues’”

When instructing your Agent to use a GitLab toolkit tool, adhere to this structured pattern:

State the Goal: Begin by clearly stating the objective you want to achieve with this step. For example, “Goal: To retrieve the content of the ‘README.md’ file.”
Specify the Tool: Clearly indicate the specific GitLab tool to be used for this step. For example, “Tool: Use the ‘read_file’ tool.”
Define Parameters: Provide a detailed list of all parameters required by the selected tool. For each parameter:
- Parameter Name: <Parameter Name as defined in tool documentation>
- Value or Source: <Specify the value or how to obtain the value. Examples: "user input", "from previous step", "hardcoded value 'main'", "value of variable X">
Describe Expected Outcome (Optional but Recommended): Briefly describe the expected result or outcome after the tool is successfully executed. For example, “Outcome: The Agent will display the file content to the user.”
Add Conversation Starters: Include example conversation starters that users can use to trigger this functionality.

Agent Instructions for Creating a Branch:

Goal: Create a new feature branch based on the main branch.
Tool: Use the "create_branch" tool.
Parameters:
    - branch_name: "Ask the user for the feature branch name, or use a default naming convention like 'feature-<feature-name>'."
    - repository: "Use the repository configured in the GitLab toolkit, or ask user to specify."
Outcome: A new branch will be created and automatically set as the active branch for subsequent operations.
Conversation Starters: "Create a new feature branch", "Start a new branch for user authentication"

Agent Instructions for Reading a File:

1. Goal: Read the content of a specific file to provide information to the user.
2. Tool: Use the "read_file" tool.
3. Parameters:
    - file_path: "Ask the user which file they want to read, or specify a default file like 'README.md'."
    - branch: "Use the currently active branch, or ask the user to specify a branch name."
    - repository: "Use the repository configured in the GitLab toolkit."
4. Outcome: The file contents will be retrieved and displayed to the user.
5. Conversation Starters: "Show me the README file", "Read the config.json file"

Chat Usage Examples by Tool Category

The following examples demonstrate how to interact with the GitLab toolkit in ELITEA Chat, organized by functional categories. Each example shows the user request and the expected agent behavior.

Branch Management - Create Branch

Chat Example:

User: "Create a new feature branch called 'feature-user-authentication'"

Agent Response: [Agent uses create_branch tool]

✔️ **Branch Created Successfully!**

Branch `feature-user-authentication` created successfully and set as active.

You can now start making changes to this branch. All subsequent file operations will be performed on this branch.

Branch Management - List Branches

Chat Example:

User: "Show me all branches in the repository"

Agent Response: [Agent uses list_branches_in_repo tool]

**Repository Branches:**

Found branches: main, develop, feature-user-auth, feature-dashboard, bugfix-login, hotfix-security

Total: 6 branches found in the repository.

File Operations - Create File

Chat Example:

User: "Create a new file called 'deployment.yaml' with basic deployment configuration"

Agent Response: [Agent uses create_file tool]

✔️ **File Created Successfully!**

- **File Path**: deployment.yaml
- **Branch**: feature-user-authentication (active branch)
- **Status**: File has been created

The file has been added to the repository on the current active branch.

File Operations - Read File

Chat Example:

User: "Show me the contents of the README.md file"

Agent Response: [Agent uses read_file tool]

**File Contents: README.md**
**Branch**: main

\`\`\`markdown
# My Project

This is a sample project demonstrating...
[... file contents ...]
\`\`\`

The README file provides an overview of the project structure and setup instructions.

Issue Management - Get Issues

Chat Example:

User: "Show me all open issues in the repository"

Agent Response: [Agent uses get_issues tool]

**Open Issues (15 total):**

1. **Issue #42**: "Implement user authentication"
   - **Labels**: enhancement, high-priority
   - **Created**: 3 days ago

2. **Issue #41**: "Fix login bug on mobile devices"
   - **Labels**: bug, mobile
   - **Created**: 5 days ago

3. **Issue #40**: "Add documentation for API endpoints"
   - **Labels**: documentation
   - **Created**: 1 week ago

[... additional issues ...]

These issues are currently open and awaiting action.

Merge Request Management - Create Merge Request

Chat Example:

User: "Create a merge request to merge feature-user-authentication into develop"

Agent Response: [Agent uses create_pull_request tool]

✔️ **Merge Request Created Successfully!**

- **Source Branch**: feature-user-authentication
- **Target Branch**: develop
- **Title**: Merge feature-user-authentication
- **Status**: Open
- **URL**: https://gitlab.com/workspace/repo/-/merge_requests/123

The merge request is ready for review. Team members can now review and approve the changes.

Version Control - Get Commits

Chat Example:

User: "Show me the recent commits from the last week"

Agent Response: [Agent uses get_commits tool]

📈 **Recent Commits (Last 7 Days)**:

1. **Latest**: `a7b3f2c` - "Fix user login validation" 
   - **Author**: @johndev
   - **Date**: 2 hours ago
   - **Changes**: Updated authentication logic to handle edge cases

2. `9d4e1a8` - "Add responsive design for mobile devices"
   - **Author**: @ui-designer
   - **Date**: Yesterday
   - **Changes**: Implemented mobile-first CSS and responsive breakpoints

3. `f2a1b9e` - "Update API documentation"
   - **Author**: @backend-dev
   - **Date**: 3 days ago
   - **Changes**: Added new endpoint documentation and examples

**Summary**: The team has been focusing on stability improvements and mobile user experience enhancements this week.

Use Cases

The GitLab toolkit unlocks numerous automation possibilities for software development workflows within ELITEA. Here are some key use cases:

Automated Branch Creation

Scenario: Development team needs to create feature branches consistently for new tasksTools Used: create_branch, set_active_branchBenefit: Ensure consistent branch naming and automatic branch activationExample Workflow:

User requests new feature branch through Chat
Agent creates branch with standardized naming (e.g., feature-<description>)
Branch automatically becomes active for subsequent operations
User can immediately start working on the new branch

Code Review Automation

Scenario: Automate creation and management of merge requests for code reviewsTools Used: create_pull_request, get_pr_changes, create_pr_change_commentBenefit: Streamline code review process and provide automated feedbackExample Workflow:

Agent creates merge request from feature branch to develop
Retrieves changes using get_pr_changes
Analyzes code modifications
Adds targeted comments on specific lines
Notifies reviewers of merge request creation

Issue Tracking and Management

Scenario: Monitor and manage project issues through AI-powered analysisTools Used: get_issues, get_issue, comment_on_issueBenefit: Efficient issue triage and automated status updatesExample Workflow:

Agent retrieves all open issues
Analyzes issue content and labels
Provides summary and prioritization recommendations
Automatically adds comments with analysis or status updates
Links related issues for better context

Documentation Generation

Scenario: Automatically generate or update project documentationTools Used: read_file, create_file, update_file, list_filesBenefit: Keep documentation synchronized with code changesExample Workflow:

Agent scans repository structure using list_files
Reads source files to extract documentation comments
Generates or updates README, API documentation, or changelog
Creates new documentation files or updates existing ones
Commits changes with descriptive messages

Repository Analysis

Scenario: Analyze repository structure and codebase for insightsTools Used: list_files, list_folders, read_file, get_commitsBenefit: Understand codebase structure and development patternsExample Workflow:

Agent explores directory structure with list_folders
Identifies key files and their purposes
Analyzes commit history for development activity
Provides insights on code organization and hotspots
Recommends refactoring or architectural improvements

Semantic Code Search

Scenario: Enable intelligent code discovery through semantic searchTools Used: index_data, search_index, stepback_search_indexBenefit: Find code patterns and implementations using natural languageExample Workflow:

Index repository content using index_data
User asks natural language questions about codebase
Agent performs semantic search across indexed content
Returns relevant code snippets and files
Provides context and explanations for found code

Continuous Integration Support

Scenario: Monitor commits and trigger automated workflowsTools Used: get_commits, read_file, comment_on_issueBenefit: Automate CI/CD processes and provide intelligent feedbackExample Workflow:

Agent monitors recent commits using get_commits
Analyzes commit messages and changed files
Triggers appropriate CI/CD pipelines
Reviews test results and code quality metrics
Updates related issues with commit references and status

File Management Automation

Scenario: Bulk file operations and repository maintenanceTools Used: create_file, update_file, delete_file, append_fileBenefit: Efficiently manage multiple files and maintain repository hygieneExample Workflow:

Agent identifies obsolete or temporary files
Creates new configuration or documentation files as needed
Updates multiple files with consistent changes
Appends log entries or changelog updates
Removes deprecated files to keep repository clean