GitLab Duo

opencode integrates with the GitLab Duo Agent Platform (DAP), connecting to GitLab's AI-powered development features. This integration is currently experimental and requires a GitLab Premium or Ultimate subscription.

Prerequisites

• GitLab Premium or Ultimate subscription.
• GitLab account with access to Duo features.
• For self-hosted instances: GitLab 16.11+ with Duo features enabled.

Connecting to GitLab Duo

Open the command palette and run:

/connect

Select GitLab from the provider list. You have two authentication options.

OAuth Authentication

OAuth is the recommended method for GitLab.com users:

1. A browser window opens prompting you to authorize opencode.
2. Grant the requested permissions.
3. The terminal confirms the connection.

For self-hosted GitLab instances, OAuth requires additional configuration (see below).

Personal Access Token

Create a GitLab personal access token with the ai_features scope:

1. Navigate to Settings > Access Tokens in GitLab.
2. Create a new token with the ai_features scope.
3. Run /connect, select GitLab, and choose token authentication.
4. Paste the token when prompted.

Available Models

The following chat models are available through the GitLab Duo Agent Platform:

Model Identifier	Description
duo-chat-haiku-4-5	Fast, lightweight model for quick responses
duo-chat-sonnet-4-5	Balanced model for general coding tasks
duo-chat-opus-4-5	Premium model for complex reasoning

Select a model after connecting:

/models

Workflow Models

GitLab DAP also provides workflow-oriented models for automated task execution. These are prefixed with duo-workflow-*:

• duo-workflow-default — general-purpose routed tool execution.
• duo-workflow-codegen — specialized for code generation tasks.

Workflow models enable opencode to execute multi-step plans using GitLab's routed tool execution infrastructure.

Self-Hosted GitLab Configuration

For self-hosted GitLab instances, configure the following environment variables:

export GITLAB_INSTANCE_URL=https://gitlab.example.com
export GITLAB_AI_GATEWAY_URL=https://ai-gateway.example.com
export GITLAB_TOKEN=your_personal_access_token

Variable	Purpose
GITLAB_INSTANCE_URL	Base URL of your GitLab instance
GITLAB_AI_GATEWAY_URL	URL of the GitLab AI Gateway (usually https://gitlab.example.com/-/ai_gateway)
GITLAB_TOKEN	Personal access token with ai_features scope

OAuth for Self-Hosted Instances

To use OAuth with a self-hosted GitLab instance, register an OAuth application in GitLab:

1. Navigate to Admin > Applications.
2. Create a new application with:
   • Name: opencode
   • Redirect URI: http://localhost:42456/callback
   • Scopes: ai_features, openid, profile
3. Save the application and note the Application ID and Secret.
4. Set these environment variables:

export GITLAB_INSTANCE_URL=https://gitlab.example.com
export GITLAB_OAUTH_APP_ID=your_application_id
export GITLAB_OAUTH_APP_SECRET=your_application_secret
export GITLAB_OAUTH_CALLBACK_URL=http://localhost:42456/callback

The callback URL must match exactly what is registered in the GitLab application. The default redirect port is 42456.

Small Model Configuration

For self-hosted instances where latency or cost is a concern, you can configure a smaller default model:

export GITLAB_SMALL_MODEL=duo-chat-haiku-4-5

This sets the fallback model for quick operations such as completions and simple edits.

Compliance Configuration

For self-hosted enterprise deployments, you can provide compliance instructions that are prepended to every request:

{
  "gitlab": {
    "instructions": "All code suggestions must comply with our internal security policies. Do not generate code that uses deprecated APIs. Ensure all generated code includes appropriate error handling."
  }
}

These instructions are injected into the system prompt for every model interaction, ensuring organizational policies are consistently applied.

GitLab Plugin

The opencode-gitlab-plugin extends opencode with direct GitLab operations:

opencode plugin install opencode-gitlab-plugin

Features

Feature	Command	Description
Merge Requests	/mr list	List open merge requests
MR Details	/mr show 42	View MR details and diff
Issues	/issue list	List project issues
Issue Details	/issue show 7	View issue details
Pipelines	/pipeline list	List recent pipeline runs
Pipeline Status	/pipeline show 123	View pipeline job status

Plugin Configuration

{
  "plugins": {
    "opencode-gitlab-plugin": {
      "projectId": 12345,
      "defaultView": "mr"
    }
  }
}

Troubleshooting

Connection Issues

If the connection fails:

• Verify your GitLab subscription tier (Premium or Ultimate required).
• Check that Duo features are enabled in your GitLab admin settings.
• For self-hosted, confirm the AI Gateway URL is reachable from your network.

Model Not Found

If a specific Duo model does not appear in the model list:

• Ensure your GitLab instance supports the model (some models require newer GitLab versions).
• Check that your subscription tier includes the model.
• Run /models --refresh to force a model list refresh.

OAuth Redirect Issues

If OAuth authentication hangs or fails:

• Confirm the redirect URI matches exactly between GitLab and opencode.
• Verify port 42456 is not blocked by a firewall.
• Check GitLab application logs for OAuth errors.

Security Considerations

• Personal access tokens should be stored securely and rotated regularly.
• For production self-hosted deployments, use OAuth with short-lived tokens rather than PATs.
• Compliance instructions are sent with every request — ensure they contain no secrets.
• The GitLab plugin respects the same permission model as the GitLab API.