GitLab OpenCode Plugin

A comprehensive GitLab integration plugin for OpenCode that provides AI assistants with tools to interact with GitLab projects, issues, merge requests, and more.

Features

• Project Management: List and retrieve project information
• Issue Management: Create, update, and track issues with comments
• Merge Request Management: Create, review, and manage merge requests
• Branch Operations: List and search branches
• User Information: Get authenticated user details

Installation

1. Install dependencies:

   npm install

2. Create a .env file with your GitLab credentials:

   cp .env.example .env

3. Edit .env and add your GitLab Personal Access Token:

   GITLAB_TOKEN=your-personal-access-token
   GITLAB_URL=https://gitlab.com

Getting a GitLab Personal Access Token

1. Go to (GitLab Settings → Access Tokens)[https://gitlab.com/-/user_settings/personal_access_tokens]
2. Create a new token with the following scopes:
   • api - Full API access
   • read_repository - Read repository data
   • write_repository - Write repository data (if creating MRs/branches)
3. Copy the token and add it to your .env file

Available Tools

Project Tools

• gitlab-list-projects - List all accessible projects
• gitlab-get-project - Get detailed project information

Issue Tools

• gitlab-list-issues - List issues with filtering
• gitlab-get-issue - Get specific issue details
• gitlab-get-issue-comments - Get all comments on an issue
• gitlab-create-issue-comment - Add a comment to an issue
• gitlab-create-issue - Create a new issue
• gitlab-update-issue - Update an existing issue

Merge Request Tools

• gitlab-list-merge-requests - List merge requests with filtering
• gitlab-get-merge-request - Get specific merge request details
• gitlab-get-merge-request-comments - Get all comments on a merge request
• gitlab-create-merge-request-comment - Add a comment to a merge request
• gitlab-create-merge-request - Create a new merge request

Repository Tools

• gitlab-list-branches - List all branches in a project

User Tools

• gitlab-get-user - Get information about the authenticated user

Testing

Run the direct test to verify your configuration:

node direct-test.js

This will:

1. Load the plugin
2. Authenticate with GitLab
3. Fetch your user information
4. List your projects
5. Test issue and comment retrieval

Usage Examples

Using with OpenCode

opencode run "list my gitlab projects"
opencode run "get comments on issue #42 in project myorg/myproject"
opencode run "create an issue in project myorg/myproject titled 'Bug fix needed'"

Project ID Format

Most tools accept a projectId parameter which can be:

• Numeric ID: 12345
• URL-encoded path: myorg%2Fmyproject
• The plugin automatically URL-encodes paths for you

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | GITLAB_TOKEN | Yes | - | Personal Access Token for GitLab API | | GITLAB_URL | No | https://gitlab.com | GitLab instance URL (change for self-hosted) |

Troubleshooting

Authentication Errors

If you see authentication errors:

1. Verify your GITLAB_TOKEN is correct
2. Check that your token has the required scopes
3. Ensure your token hasn't expired

Self-Hosted GitLab

For self-hosted GitLab instances:

1. Set GITLAB_URL to your instance URL (e.g., https://gitlab.mycompany.com)
2. Ensure the URL doesn't have a trailing slash
3. Verify your token has been created on the correct instance

404 Errors

If you get 404 errors:

1. Verify the project ID or path is correct
2. Ensure you have access to the project
3. For URL-encoded paths, use the format namespace%2Fproject

API Documentation

This plugin uses the GitLab API v4. For more information, see:

• GitLab API Documentation
• Personal Access Tokens

License

MIT