Add GitLab Integration with DevOps Automation Capabilities

[Samir-atra]

Overview

This PR implements comprehensive GitLab API integration for the hive/aden tools package, enabling agents to automate DevOps workflows across projects, issues, merge requests, and CI/CD pipelines.

Branch: feat/gitlab-integration

Closes #2963
Related to #2805

Motivation

GitLab is a cornerstone of the DevOps lifecycle for many enterprises, especially those requiring self-hosted solutions. This integration enables Hive agents to automate workflows across the entire DevSecOps pipeline, complementing the existing GitHub support.

Key Use Cases:

• Automated Triage: Scan new issues, apply labels, and assign to milestones
• Pipeline Recovery: Analyze failed CI/CD pipelines and post diagnostic comments on MRs
• Merge Request Summaries: Review MRs and summarize changes for human reviewers

Changes

New Files

File	Description
tools/src/aden_tools/credentials/gitlab.py	Credential specs for GITLAB_ACCESS_TOKEN (required) and GITLAB_URL (optional)
tools/src/aden_tools/tools/gitlab_tool/__init__.py	Module initialization
tools/src/aden_tools/tools/gitlab_tool/gitlab.py	Main implementation with GitLabClient class and 5 MCP tools
tools/tests/tools/test_gitlab_tool.py	Comprehensive unit tests (18 tests)
docs/tools/gitlab-tool.md	Full documentation with usage examples

Modified Files

File	Changes
tools/src/aden_tools/credentials/__init__.py	Added GITLAB_CREDENTIALS import and export
tools/src/aden_tools/tools/__init__.py	Added register_gitlab and 5 tool names

Features

5 MCP Tools (MVP Scope)

Tool	Description
gitlab_list_projects	Search and list accessible projects with ownership filtering
gitlab_list_issues	List issues with state (opened/closed) and label filtering
gitlab_get_merge_request	Get full MR details including status, author, and reviewers
gitlab_create_issue	Create issues with markdown description and label support
gitlab_trigger_pipeline	Trigger CI/CD pipeline runs for branches or tags

Key Implementation Details

• GitLabClient class: Handles all API interactions using httpx
• Self-Hosted Support: Works with gitlab.com or self-hosted instances via GITLAB_URL
• URL Encoding: Automatically encodes project paths (e.g., mygroup/myproject)
• Error Handling: Detailed JSON error responses with status codes
• Type Annotations: Modern Python 3.10+ syntax (X | None)

Authentication

Variable	Required	Description
GITLAB_ACCESS_TOKEN	Yes	Personal Access Token (scope: api)
GITLAB_URL	No	Base URL for self-hosted instances (default: https://gitlab.com)

Testing

Test Results

===== 18 passed in 0.04s =====

Test Category	Result
GitLabClient methods	✅ 7/7 passed
Credential integration	✅ 4/4 passed
Self-hosted GitLab support	✅ 2/2 passed
Error handling	✅ 5/5 passed

Test Coverage

• GitLabClient methods (list_projects, list_issues, get_merge_request, create_issue, trigger_pipeline)
• Self-hosted GitLab URL configuration
• Credential integration and validation
• Error handling for missing credentials
• URL encoding for project paths with namespaces

Documentation

Comprehensive documentation added at docs/tools/gitlab-tool.md:

• Usage examples for all 5 tools
• Authentication setup for PAT and self-hosted instances
• Project ID format explanation (numeric vs path)
• Error handling reference
• Rate limiting notes

Usage Examples

# Search for projects
gitlab_list_projects(
    search="my-project",
    owned=True,
    limit=10
)

# List open bugs
gitlab_list_issues(
    project_id="mygroup/myproject",
    state="opened",
    labels="bug,critical"
)

# Get merge request details
gitlab_get_merge_request(
    project_id="123",
    mr_iid=42
)

# Create an issue
gitlab_create_issue(
    project_id="mygroup/myproject",
    title="Bug: Login fails on mobile",
    description="## Steps\n1. Open app\n2. Try login",
    labels="bug,mobile"
)

# Trigger a pipeline
gitlab_trigger_pipeline(
    project_id="mygroup/myproject",
    ref="main"
)

Configuration

Add to .env:

# Required
GITLAB_ACCESS_TOKEN=glpat-XXXXXXXXXXXXXXXX

# Optional (for self-hosted GitLab)
GITLAB_URL=https://gitlab.mycompany.com

Checklist

• Code follows project style guidelines (Google style)
• Unit tests added (18 new tests, all passing)
• Documentation updated
• Credential specifications follow project patterns
• Self-hosted GitLab instances supported
• Branch contains only GitLab integration (isolated from other changes)

Related Issues

• Closes [Integration]: Add GitLab integration #2963 - GitLab Integration Request
• Related to [Integration]: Expand agent capabilities by adding more integrations/tools #2805 - GitHub Integration (complementary feature)

[github-actions]

PR Closed - Requirements Not Met

This PR has been automatically closed because it doesn't meet the requirements.

PR Author: @Samir-atra
Found issues: #2963 (assignees: none), #2805 (assignees: none)
Problem: The PR author must be assigned to the linked issue.

To fix:

1. Assign yourself (@Samir-atra) to one of the linked issues
2. Re-open this PR

Exception: To bypass this requirement, you can:

• Add the micro-fix label or include micro-fix in your PR title for trivial fixes
• Add the documentation label or include doc/docs in your PR title for documentation changes

Micro-fix requirements (must meet ALL):

Qualifies	Disqualifies
< 20 lines changed	Any functional bug fix
Typos & Documentation & Linting	Refactoring for "clean code"
No logic/API/DB changes	New features (even tiny ones)

Why is this required? See #472 for details.

[Samir-atra]

hello @austin931114 @Hundao @bryanadenhq @RichardTang-Aden

Please check this out, I need to get assigned to move forward.

I look forward to hearing from you.

Kind regards
Samer