npm package: @openpets/gitlab
Description: GitLab integration plugin for OpenCode - manage projects, issues, merge requests, and more
Latest version: 1.0.8

# 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:
   ```bash
   npm install
   ```

2. Create a `.env` file with your GitLab credentials:
   ```bash
   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:

```bash
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

```bash
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](https://docs.gitlab.com/ee/api/)
- [Personal Access Tokens](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html)

## License

MIT