diff --git a/doc/user/gitlab_duo/_index.md b/doc/user/gitlab_duo/_index.md index 52c24f6b39ce0915bfd6dc2f2f404cc3906cf859..7d49b19d508e213e09ab562d1abef520d73bce07 100644 --- a/doc/user/gitlab_duo/_index.md +++ b/doc/user/gitlab_duo/_index.md @@ -19,3 +19,7 @@ Some features are also available as part of [GitLab Duo Chat](../gitlab_duo_chat - [Use your own models with GitLab Duo Self-Hosted](../../administration/gitlab_duo_self_hosted/_index.md) {{< /walkthrough >}} + +## Customizing GitLab Duo + +- [Customize GitLab Duo behavior with custom instructions](customize_duo.md) diff --git a/doc/user/gitlab_duo/customize_duo.md b/doc/user/gitlab_duo/customize_duo.md new file mode 100644 index 0000000000000000000000000000000000000000..087401c33c888427bde40dbc077c78df4d720361 --- /dev/null +++ b/doc/user/gitlab_duo/customize_duo.md @@ -0,0 +1,107 @@ +--- +stage: AI-powered +group: Duo Chat +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +title: Customizing GitLab Duo +--- + +{{< history >}} + +- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/584017) in GitLab 18.8. + +{{< /history >}} + +GitLab Duo provides multiple ways to customize its behavior to match your workflow, coding standards, and project requirements. This page helps you understand which customization option to use for your needs. + +## Available customization options + +GitLab Duo supports three main customization mechanisms: + +- **Custom chat rules** (`chat-rules.md`): Personal preferences and team-wide standards for GitLab Duo Chat conversations +- **AGENTS.md instruction files**: Project-specific context and directory-specific conventions for GitLab Duo Chat in your IDE +- **Code Review instructions** (`mr-review-instructions.yaml`): Custom review criteria for GitLab Duo Code Review + +## Decision matrix + +Use this table to determine which customization option best fits your needs: + +| Feature | `chat-rules.md` | `AGENTS.md` | `mr-review-instructions.yaml` | +|---------|---------------|-----------|----------------------------| +| **Purpose** | Personal preferences and team-wide chat standards | Project-specific context and directory conventions | Code review standards and guidelines | +| **Scope** | All GitLab Duo Chat conversations | GitLab Duo Chat conversations in IDEs | GitLab Duo Code Review only | +| **File Location** | User: `~/.gitlab/duo/chat-rules.md`
Workspace: `.gitlab/duo/chat-rules.md` | User: `~/.gitlab/duo/AGENTS.md`
Workspace: `AGENTS.md` (root)
Subdirectories: `/AGENTS.md` | Workspace: `.gitlab/duo/mr-review-instructions.yaml` | +| **Supported Environments** | IDEs (VS Code, JetBrains, Visual Studio) | IDEs (VS Code, JetBrains, Visual Studio), Duo CLI | GitLab UI, IDEs | +| **Nested Directory Support** | No | Yes | Yes (via file patterns) | +| **Use Cases** | - Personal coding style preferences
- Team-wide standards
- Consistent response formatting | - Monorepo organization
- Project-specific context
- Directory-specific conventions
- Cross-tool compatibility | - Language-specific review rules
- Security standards
- Code quality requirements
- File-specific guidelines | + +## Precedence rules + +When multiple customization files exist, GitLab Duo applies them in this order: + +1. **User-level chat rules** (`~/.gitlab/duo/chat-rules.md`) - Applied first +1. **User-level AGENTS.md** (`~/.gitlab/duo/AGENTS.md`) - Applied second +1. **Workspace-level AGENTS.md** (root `AGENTS.md`) - Applied third +1. **Subdirectory AGENTS.md** (discovered based on files being worked with) - Applied fourth +1. **Workspace-level chat rules** (`.gitlab/duo/chat-rules.md`) - Applied last + +Instructions from all applicable files are combined. Later instructions can override or supplement earlier ones. + +Code Review instructions (`.gitlab/duo/mr-review-instructions.yaml`) are applied independently and only affect GitLab Duo Code Review, not Chat. + +## Quick start guide + +### For personal preferences + +If you want to customize how GitLab Duo Chat responds to you across all projects: + +1. Create a user-level chat rules file: `~/.gitlab/duo/chat-rules.md` +1. Add your preferences in Markdown format +1. Start a new GitLab Duo Chat conversation + +[Learn more about custom chat rules](../gitlab_duo_chat/agentic_chat.md#create-custom-rules) + +### For project-specific context + +If you want to provide project-specific context or conventions: + +1. Create an `AGENTS.md` file in your project root +1. Add project-specific instructions in Markdown format +1. Start a new GitLab Duo Chat conversation + +[Learn more about AGENTS.md files](../gitlab_duo_chat/agentic_chat.md#create-agentsmd-instruction-files) + +### For code review standards + +If you want to enforce specific code review standards: + +1. Create `.gitlab/duo/mr-review-instructions.yaml` in your project +1. Define file patterns and review instructions in YAML format +1. Create or update a merge request to see the custom review criteria applied + +[Learn more about Code Review customization](../project/merge_requests/duo_in_merge_requests.md#customize-instructions-for-gitlab-duo-code-review) + +### For monorepo organization + +If you have a monorepo with different conventions in different directories: + +1. Create `AGENTS.md` files in relevant subdirectories +1. Add directory-specific instructions in each file +1. GitLab Duo Chat will apply the appropriate instructions based on the files you're working with + +[Learn more about subdirectory AGENTS.md files](../gitlab_duo_chat/agentic_chat.md#create-subdirectory-level-agentsmd-files) + +## Best practices + +- **Start simple**: Begin with a few clear instructions and add more as needed +- **Be specific**: Provide actionable guidance rather than vague preferences +- **Use the right tool**: Choose the customization mechanism that matches your scope (personal, project, or review) +- **Combine approaches**: Use multiple customization files together for comprehensive control +- **Document your choices**: Add comments to explain why certain instructions exist +- **Use Code Owners**: Protect customization files with [Code Owners](../project/codeowners/_index.md) to manage changes + +## Related topics + +- [GitLab Duo Chat custom rules](../gitlab_duo_chat/agentic_chat.md#create-custom-rules) +- [AGENTS.md instruction files](../gitlab_duo_chat/agentic_chat.md#create-agentsmd-instruction-files) +- [Customize GitLab Duo Code Review](../project/merge_requests/duo_in_merge_requests.md#customize-instructions-for-gitlab-duo-code-review) +- [GitLab Duo feature summary](feature_summary.md) diff --git a/doc/user/gitlab_duo_chat/agentic_chat.md b/doc/user/gitlab_duo_chat/agentic_chat.md index 3902a279e31ba999fad7f107cee3b2ef3de5dd3f..da34264a7b48517939197750bccebd4b3c875d6a 100644 --- a/doc/user/gitlab_duo_chat/agentic_chat.md +++ b/doc/user/gitlab_duo_chat/agentic_chat.md @@ -283,9 +283,8 @@ User-level custom rules apply to all of your projects and workspaces. 1. Create a custom rules file in your user configuration directory: - If you have set the `GLAB_CONFIG_DIR` environment variable, create the file at: `$GLAB_CONFIG_DIR/chat-rules.md` - Otherwise, create the file in your platform's default configuration directory: - - macOS: `~/Library/Application Support/glab-cli/chat-rules.md` - - Linux: `~/.config/glab-cli/chat-rules.md` - - Windows: `%LOCALAPPDATA%\glab-cli\chat-rules.md` + - macOS and Linux: `~/.gitlab/duo/chat-rules.md` + - Windows: `%APPDATA%\GitLab\duo\chat-rules.md` 1. Add custom rules to the file. For example: ```markdown @@ -319,6 +318,8 @@ Workspace-level custom rules apply only to a specific project or workspace. For more information, see the [Custom rules in GitLab Duo Agentic Chat blog](https://about.gitlab.com/blog/custom-rules-duo-agentic-chat-deep-dive/). +For a complete overview of all customization options, see [Customizing GitLab Duo](../gitlab_duo/customize_duo.md). + ### Update custom rules To update your custom rules, edit and save the custom rules file. Then, start a new GitLab Duo @@ -328,6 +329,175 @@ You cannot use Chat to edit your custom rules file directly. To manage who must approve any changes to custom rules, use [Code Owners](../project/codeowners/_index.md). +## Create `AGENTS.md` instruction files + +{{< history >}} + +- AGENTS.md support [introduced](https://gitlab.com/gitlab-org/editor-extensions/gitlab-lsp/-/merge_requests/2597) in GitLab 18.7. + +{{< /history >}} + +Use `AGENTS.md` files to provide instructions for GitLab Duo Chat to follow during conversations in your IDE. + +`AGENTS.md` files are plain text files that contain instructions in Markdown format. GitLab Duo Chat reads these files and applies the instructions to conversations. + +You can create `AGENTS.md` files at three levels: + +- **User-level**: Apply to all of your projects and workspaces. +- **Workspace-level**: Apply to a specific project or workspace. +- **Subdirectory-level**: Apply when working with files in a specific directory within a project. + +GitLab Duo Chat combines available instructions from user-level and workspace-level `AGENTS.md` files for all conversations. If a task requires working with files in a directory that contains an additional `AGENTS.md` file, Chat applies those instructions as well. + +Prerequisites: + +- For VS Code, [install and configure the GitLab Workflow extension for VS Code](../../editor_extensions/visual_studio_code/setup.md) version 6.60 or later. +- For a JetBrains IDE, [install and configure the GitLab plugin for JetBrains](../../editor_extensions/jetbrains_ide/setup.md) version 3.26.0 or later. +- For Visual Studio, [install and configure the GitLab extension for Visual Studio](../../editor_extensions/visual_studio/setup.md) version 0.74.0 or later. + +{{< alert type="note" >}} + +Conversations that existed before you created any `AGENTS.md` files do not follow those instructions. + +{{< /alert >}} + +### Supported environments + +`AGENTS.md` files work with: + +- VS Code (GitLab Workflow extension version 6.60 or later) +- JetBrains IDEs (GitLab plugin version 3.26.0 or later) +- Visual Studio (GitLab extension version 0.74.0 or later) +- Duo CLI + +Support for remote flows (Fix Pipeline, Duo Developer) is in progress. + +### Create a user-level AGENTS.md file + +User-level `AGENTS.md` files apply to all of your projects and workspaces. + +1. Create an `AGENTS.md` file in your user configuration directory: + - If you have set the `GLAB_CONFIG_DIR` environment variable, create the file at: `$GLAB_CONFIG_DIR/AGENTS.md` + - Otherwise, create the file in your platform's default configuration directory: + - macOS and Linux: `~/.gitlab/duo/AGENTS.md` + - Windows: `%APPDATA%\GitLab\duo\AGENTS.md` +1. Add instructions to the file. For example: + + ```markdown + # My Personal Coding Preferences + + - Always explain code changes in simple terms for beginners + - Use descriptive variable names + - Add comments for complex logic + - Prefer functional programming patterns when appropriate + ``` + + Or for team coding standards: + + ```markdown + # Team Coding Standards + + - Follow our company's style guide for all code + - Use TypeScript strict mode + - Write unit tests for all new functions + - Document all public APIs with JSDoc + ``` + + Or for monorepo-specific context: + + ```markdown + # Monorepo Context + + - This is a monorepo with multiple services + - Frontend code is in /apps/web + - Backend services are in /services + - Shared libraries are in /packages + - Follow the architecture decision records in /docs/adr + ``` + + Or for security-focused review guidelines: + + ```markdown + # Security Review Guidelines + + - Always validate user input + - Use parameterized queries for database operations + - Implement proper authentication and authorization + - Follow OWASP security best practices + - Never log sensitive information + ``` + +1. Save the file. +1. To apply the new instructions, start a new GitLab Duo conversation. + + You must do this every time you change the `AGENTS.md` file. + +### Create a workspace-level AGENTS.md file + +Workspace-level `AGENTS.md` files apply to a specific project or workspace. + +1. In the root of your project workspace, create an `AGENTS.md` file. +1. Add instructions to the file. For example: + + ```markdown + # Project-Specific Guidelines + + - This project uses React with TypeScript + - Follow the component structure in /src/components + - Use our custom hooks from /src/hooks + - State management uses Redux Toolkit + ``` + +1. Save the file. +1. To apply the new instructions, start a new GitLab Duo conversation. + + You must do this every time you change the `AGENTS.md` file. + +### Create subdirectory-level AGENTS.md files + +Subdirectory-level `AGENTS.md` files apply when working with files in a specific directory within a project. This is useful for monorepos or projects with different conventions in different areas. + +1. In a subdirectory of your project, create an `AGENTS.md` file. +1. Add instructions specific to that directory. For example, for a backend service: + + ```markdown + # Backend Service Guidelines + + - This service uses Node.js with Express + - Follow RESTful API conventions + - Use async/await for asynchronous operations + - Validate all inputs with Joi schemas + ``` + +1. Save the file. +1. To apply the new instructions, start a new GitLab Duo conversation that involves files in that directory. + + You must do this every time you change the `AGENTS.md` file. + +### The difference between `AGENTS.md` and `chat-rules.md` + +Both `AGENTS.md` and `chat-rules.md` files provide instructions to GitLab Duo Chat, but they serve different purposes: + +| Feature | AGENTS.md | chat-rules.md | +|---------|-----------|---------------| +| **GitLab-only vs cross-tool compatibility** | Standard format that works across different AI tools and IDEs | GitLab-specific format | +| **File locations** | User-level (`~/.gitlab/duo/AGENTS.md`), workspace root, and subdirectories | User-level (`~/.gitlab/duo/chat-rules.md`) and workspace (`.gitlab/duo/chat-rules.md`) | +| **Precedence level** | Applied after user-level chat rules, before workspace-level chat rules | User-level rules applied first, workspace-level rules applied last | +| **Nested directory support** | Yes - can be placed in any subdirectory | No - only user-level and workspace-level | +| **Best used for** | Project-specific context, monorepo organization, directory-specific conventions | Personal preferences, team-wide standards | + +**Precedence order** (from first to last applied): + +1. User-level chat rules (`~/.gitlab/duo/chat-rules.md`) +1. User-level AGENTS.md (`~/.gitlab/duo/AGENTS.md`) +1. Workspace-level AGENTS.md (root `AGENTS.md`) +1. Subdirectory AGENTS.md (discovered based on files being worked with) +1. Workspace-level chat rules (`.gitlab/duo/chat-rules.md`) + +Use `chat-rules.md` for personal preferences and team-wide standards that should apply to all conversations. Use `AGENTS.md` for project-specific context and directory-specific conventions, especially in monorepos. + +For a complete overview of all customization options, see [Customizing GitLab Duo](../gitlab_duo/customize_duo.md). + ## Select a model {{< details >}} diff --git a/doc/user/project/merge_requests/duo_in_merge_requests.md b/doc/user/project/merge_requests/duo_in_merge_requests.md index 8708711ef82c46dabb9a356274961bae92ccb871..f5e3906bcdae086efded4ecf5bb765e535b918bf 100644 --- a/doc/user/project/merge_requests/duo_in_merge_requests.md +++ b/doc/user/project/merge_requests/duo_in_merge_requests.md @@ -310,6 +310,8 @@ I need more Duo Code Review custom rules - when you look at the source code, whi You can find practical examples for many programming languages in the [use case examples for customized MR review rules section](#use-case-examples-for-customized-mr-review-rules). +For other ways to customize GitLab Duo behavior, see [Customizing GitLab Duo](../../gitlab_duo/customize_duo.md). + ### Customized code review comments When GitLab Duo Code Review generates code review comments based on your custom instructions, they follow this format: