From 1aae1c795db6b57b1404c40ee8a9d894bc9fd745 Mon Sep 17 00:00:00 2001
From: Viktor Nagy <126671+nagyv@users.noreply.github.com>
Date: Wed, 10 Dec 2025 15:29:28 +0100
Subject: Add gitlab-opencode to GitLab docs

The current GitLab page describes OpenCode integration through GitLab Duo.

GitLab Duo is a paying functionality and is limited to workflows supported by GitLab.

GitLab-OpenCode is a community project that offers more flexiblity, better customization and easier setup to use OpenCode in GitLab. On the downside, it does not have the level of integration into GitLab as Duo does.
---
 packages/web/src/content/docs/gitlab.mdx | 46 +++++++++++++++++++++++++++++---
 1 file changed, 43 insertions(+), 3 deletions(-)

(limited to 'packages/web/src/content/docs/gitlab.mdx')

diff --git a/packages/web/src/content/docs/gitlab.mdx b/packages/web/src/content/docs/gitlab.mdx
index 66c006c80..3810ba318 100644
--- a/packages/web/src/content/docs/gitlab.mdx
+++ b/packages/web/src/content/docs/gitlab.mdx
@@ -3,12 +3,52 @@ title: GitLab
 description: Use OpenCode in GitLab issues and merge requests.
 ---
 
+## Integration options
+
+There are at least two approaches to run OpenCode in GitLab:
+
+- Run it in GitLab pipelines as a regular pipeline
+- Run it through GitLab Duo
+
+In both cases, OpenCode will run on your GitLab runners.
+
+## GitLab CI integration
+
+OpenCode works in a regular GitLab pipeline. You build it into a pipeline as a [CI component](https://docs.gitlab.com/ee/ci/components/)
+
+---
+
+### Features
+
+- **Use custom configuration per job**: Configure OpenCode with a [custom configuration directory](./config/#custom-directory) to enable/disable functionality per OpenCode invocation.
+- **Minimal setup**: The CI component sets up OpenCode in the background, you only need to create the OpenCode configuration and the initial prompt.
+- **Flexible**: The CI component supports several inputs for customizing its behavior
+
+### Setup
+
+1. Store your OpenCode authentication JSON as a File type CI environment variables under **Settings -> CI/CD -> Variables**. Tip: Mark it "Masked and hidden".
+2. Add code blocks like the following to your `.gitlab-ci.yml` file:
+
+```
+include:
+  - component: $CI_SERVER_FQDN/nagyv/gitlab-opencode/opencode@1.0.0
+    inputs:
+      config_dir: ${CI_PROJECT_DIR}/opencode-config
+      auth_json: $OPENCODE_AUTH_JSON  # The variable name for your OpenCode authentication JSON
+      command: optional-custom-command
+      message: "Your prompt here"
+```
+
+See more inputs and use cases in [its documentation](https://gitlab.com/explore/catalog/nagyv/gitlab-opencode).
+
+## GitLab Duo integration
+
 OpenCode integrates with your GitLab workflow.
 Mention `@opencode` in a comment, and OpenCode will execute tasks within your GitLab CI pipeline.
 
 ---
 
-## Features
+### Features
 
 - **Triage issues**: Ask OpenCode to look into an issue and explain it to you.
 - **Fix and implement**: Ask OpenCode to fix an issue or implement a feature.
@@ -17,7 +57,7 @@ Mention `@opencode` in a comment, and OpenCode will execute tasks within your Gi
 
 ---
 
-## Setup
+### Setup
 
 OpenCode runs in your GitLab CI/CD pipeline, here's what you'll need to set it up:
 
@@ -113,7 +153,7 @@ You can refer to the [GitLab CLI agents docs](https://docs.gitlab.com/user/duo_a
 
 ---
 
-## Examples
+### Examples
 
 Here are some examples of how you can use OpenCode in GitLab.
 
-- 
cgit v1.2.3

