Group-Level Custom Instructions for Duo Code Review
## Problem to solve
As an organization administrator or group owner, I want to define custom code review instructions at the group level that apply to all projects within my group, so I can enforce organization-wide coding standards and best practices consistently across multiple projects without having to configure each project individually.
Currently, custom instructions for Duo Code Review are only available at the project level (implemented in https://gitlab.com/groups/gitlab-org/-/work_items/17685). This creates several challenges for organizations:
1. **Inconsistent standards**: Each project must configure its own custom instructions, leading to inconsistent application of organizational coding standards
2. **Management overhead**: Administrators must manually configure and maintain custom instructions across dozens or hundreds of projects
3. **Lack of centralized control**: No single point of control for organization-wide AI code review policies
4. **Onboarding complexity**: New projects don't automatically inherit organizational standards
## Proposal
Extend the existing custom instructions feature for Duo Code Review to support group-level configuration. Group owners and administrators should be able to define custom code review instructions at the group level that automatically apply to all projects within the group.
## User experience goal
Group owners and administrators should be able to define, manage, and apply custom code review instructions at the group level that automatically inherit to all projects within the group.
## Acceptance Criteria
1. Group owners can designate an existing project within the group as the Duo template repository via the GitLab UI (Group Settings › GitLab Duo) and via the REST/GraphQL APIs
2. The instructions file (`.gitlab/duo/mr-review-instructions.yaml`) from the designated template project is automatically applied to all projects within the group during Duo Code Review
3. Instructions are merged from all ancestor groups (most-specific group first) plus the project itself — both group-level and project-level instructions are applied together
---
## Implementation Details
> The implementation reuses the existing `.gitlab/duo/mr-review-instructions.yaml` file format. Groups designate an existing project as their "Duo template repository" via a new `duo_template_project_id` setting. Instructions are merged from all ancestor groups (most-specific first) plus the project itself — the same traversal strategy used by description templates via `CustomFileTemplates`.
### Phased implementation
#### Phase 1 - Backend + REST API
- **DB**: New `duo_template_project_id bigint` column on `namespace_template_settings` with a FK to `projects`
- **API**: Change admin API to allow updating `duo_template_project_id` in the `GitLab Duo features` section
- Create class to resolve all rules for a given project/merge request
#### Phase 2 - Backend + Rest API
- **API**: Add API to GitLab to fetch rules for a given project/merge request (feature behind a feature flag)
- Change AI Gateway to [fetch rules hierarchy from GitLab](https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/-/blob/d19f79bdb262869aacbed1f0dca2c7e6fe563085/duo_workflow_service/tools/code_review.py#L353-362), instead of only for the project
- Ability to filter rules by applicability (see [_matches_pattern](https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/-/blob/d19f79bdb262869aacbed1f0dca2c7e6fe563085/duo_workflow_service/tools/code_review.py#L414-426))
### Phase 3 - Frontend
- **UI**: Allow group admins to change the template project (feature behind a feature flag)
### User Journey
1. A group administrator notices inconsistent code review standards across projects in their organization
2. They navigate to Group Settings > General > GitLab Duo features
3. They select a project under `GitLab Duo template repository`
4. When team members submit merge requests in any project within the group, Duo Code Review automatically applies both group-level and project-level rules
5. Projects receive consistent AI review comments that reflect organizational conventions while still allowing project-specific customizations
{width=702 height=367}
### Rule Inheritance and Precedence
#### Inheritance Model
- **Group rules**: Apply to all projects within the group and its subgroups
- **Project rules**: Apply only to the specific project
- **Combined application**: Both group and project rules are applied together during code review
#### Rule Precedence
1. **Group rules**: Always applied first as baseline organizational standards
2. **Project rules**: Applied in addition to group rules for project-specific requirements
3. **Conflict resolution**: Project rules cannot override group rules but can provide additional guidance
4. **Path pattern specificity**: More specific patterns take precedence over broader patterns within the same level
### User Experience
#### Group-Level Rule Management
- Centralized repository containing all group-level rules
- Clear indication of rule scope and inheritance
- Rule templates for common organizational standards
#### Rule Application Visibility
- Clear indication in Duo Code Review comments when group-level rules are applied
### Use Cases
#### 1. Organization-Wide Security Standards
```yaml
instructions:
- name: Security Best Practices
fileFilters:
- "**/*.js"
- "**/*.ts"
- "**/*.py"
- "**/*.rb"
instructions: |
All code must follow our organization's security guidelines:
1. Never log sensitive information (passwords, tokens, PII)
2. Always validate and sanitize user inputs
3. Use parameterized queries to prevent SQL injection
4. Implement proper error handling that doesn't expose system details
5. Follow principle of least privilege for access controls
```
#### 2. Documentation Requirements
```yaml
instructions:
- name: Documentation Standards
fileFilters:
- "**/*.go"
- "**/*.java"
- "**/*.cs"
instructions: |
Ensure all public functions and classes have proper documentation:
1. Public functions must have docstrings explaining purpose, parameters, and return values
2. Complex algorithms should include inline comments
3. API endpoints must document expected inputs and outputs
4. Include examples for non-trivial functions
```
#### 3. Code Quality Standards
```yaml
instructions:
- name: Code Quality Guidelines
fileFilters:
- "**/*"
instructions: |
Review code for adherence to our quality standards:
1. Functions should be focused and do one thing well
2. Variable and function names should be descriptive
3. Avoid deep nesting (max 3 levels)
4. Include error handling for external dependencies
5. Follow DRY principles - flag duplicate code patterns
```
### Feature Usage Metrics
We will track:
1. **Group-level adoption**:
- Number of groups with at least one custom instruction rule
- Average number of group-level rules per group
2. **Inheritance effectiveness**:
- Ratio of group vs. project rules applied in reviews
- Rule override/extension patterns
3. **Organizational impact**:
- Consistency improvement in code review comments across projects
- Reduction in project-level rule duplication
### Success Metrics
1. **Adoption**: 15% of groups using Duo Code Review implement at least one group-level custom instruction within 6 months of launch
### Future Enhancements
1. **Rule templates**: Pre-built rule templates for common organizational standards
2. **Advanced inheritance**: More sophisticated inheritance models with selective overrides
3. **Analytics dashboard**: Comprehensive analytics on rule effectiveness and organizational compliance
4. **Integration with security policies or compliance frameworks**: Direct integration with compliance and governance tools
epic