Skip to content

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 &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

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, with the ability for projects to extend (but not override) group-level rules.

Proposal

We will implement a group-level custom instructions system for GitLab Duo Code Review that provides centralized management while maintaining project-level flexibility.

User Journey

  1. A group administrator notices inconsistent code review standards across projects in their organization
  2. They navigate to Group Settings > GitLab Duo > Custom Instructions
  3. They create organization-wide rules by:
    • Providing descriptive titles for each rule
    • Defining path patterns to target specific file types across all projects
    • Writing clear instructions that reflect organizational standards
  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

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

Group-Level Rule Configuration

Rules will be configurable via the GitLab group settings UI:

  • Settings located under Group Settings > GitLab Duo > Custom Instructions
  • Consistent interface with project-level custom instructions
  • Ability to enable/disable individual rules without deletion
  • Preview functionality to see how rules will apply across projects

Rule Structure (Enhanced)

Each group-level rule will consist of:

  • Title: Descriptive name for organizational reference
  • Path patterns: Glob patterns specifying which files the rule applies to across all projects
  • Instruction: Plain text guidance for the AI reviewer
  • Scope: Indicator showing the rule applies at group level
  • Inheritance settings: Controls for how the rule propagates to subgroups

Permissions and Access Control

  • Group Owners: Full access to create, edit, and delete group-level custom instructions
  • Group Maintainers: Can view and edit existing group-level custom instructions (configurable)
  • Project Maintainers: Can view group-level rules but cannot modify them; can create project-level rules that extend group rules
  • Developers: Can view which group-level rules are applied in code reviews but cannot modify them

User Experience

Group-Level Rule Management

  • Centralized dashboard showing all group-level rules
  • Clear indication of rule scope and inheritance
  • Bulk operations for managing multiple rules
  • Rule templates for common organizational standards

Rule Application Visibility

  • Clear indication in Duo Code Review comments when group-level rules are applied
  • Separate sections showing group vs. project rule applications
  • Ability to view the specific group-level instructions that influenced review comments
  • Inheritance chain visualization for complex group structures

Project-Level Integration

  • Project settings show inherited group rules (read-only)
  • Clear distinction between inherited and project-specific rules
  • Guidance on how to extend group rules with project-specific instructions

Use Cases

1. Organization-Wide Security Standards

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

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

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

Implementation Considerations

Database Schema

  • New group_duo_custom_instructions table
  • Relationship to existing project_duo_custom_instructions
  • Inheritance tracking and caching mechanisms

Performance

  • Efficient rule lookup and caching for large group hierarchies
  • Minimal impact on existing Duo Code Review performance
  • Optimized rule matching for complex inheritance scenarios

API Integration

  • REST API endpoints for programmatic management of group-level rules
  • GraphQL support for complex queries across group hierarchies
  • Bulk import/export capabilities for organizational migration

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

Acceptance Criteria

  1. Group owners, maintainers, and gitlab administrators can create and delete group-level custom instructions .yml through the GitLab UI
  2. Group-level custom instructions are correctly inherited by all projects within the group
  3. Both group-level and project-level rules are applied together in Duo Code Review
  4. Proper permissions are enforced for group-level rule management
  5. API endpoints support programmatic management of group-level rules

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

This feature builds upon the successful implementation of project-level custom instructions and addresses the clear group need for centralized management of AI code review standards. It provides a foundation for future expansion into advanced governance capabilities.

Edited by Conley Rogers