Advanced Configuration

Welcome to Ship Guard's advanced configuration guide! This document covers advanced features for teams who want to customize their code review experience beyond the basics. You'll learn about team-specific rules, advanced RAG integration, custom policies, global settings, and integrations.

📋 What You'll Learn

By the end of this guide, you'll understand:

✅ Advanced rule configuration with custom error codes and tags
✅ Sophisticated RAG integration with security controls
✅ Global settings for team-wide customization
✅ Integration with external tools (Slack, Jira)
✅ Custom comment templates and reporting
✅ Security and performance optimization

🎯 Advanced Rule Configuration

Enhanced Rule Properties

Beyond the basic rule configuration, Ship Guard supports advanced properties for better organization and control:

rules:
  - name: 'Advanced security scan'
    condition: 'security-scan'
    severity: 'error'
    enabled: true # Enable/disable rules dynamically
    errorCode: 'SEC-001' # Custom error codes for categorization
    tags: ['security', 'critical'] # Tags for rule organization
    paths: ['src/**/*.ts']
    excludePaths: ['**/*.test.ts']
    parameters:
      scanPatterns: ['password', 'secret', 'token']
      excludeTestFiles: true

Advanced Rule Properties

Property	Type	Default	Description
`enabled`	`boolean`	`true`	Enable/disable rules dynamically
`errorCode`	`string`	—	Custom error code for categorization
`tags`	`array[string]`	—	Tags for rule organization and filtering

Rule Organization with Tags

Use tags to organize and filter rules:

rules:
  # === SECURITY RULES ===
  - name: 'No hardcoded secrets'
    condition: 'banned-terms'
    tags: ['security', 'secrets']
    parameters:
      terms: ['password', 'secret', 'token']

  - name: 'Security vulnerability scan'
    condition: 'security-scan'
    tags: ['security', 'vulnerabilities']
    severity: 'error'

  # === CODE QUALITY RULES ===
  - name: 'No TODO comments'
    condition: 'banned-terms'
    tags: ['quality', 'cleanup']
    parameters:
      terms: ['TODO', 'FIXME', 'HACK']

  - name: 'Require tests for new features'
    condition: 'require-tests'
    tags: ['quality', 'testing']
    severity: 'warning'

Advanced RAG Integration

Sophisticated RAG Configuration

Ship Guard's RAG system supports advanced configuration for optimal performance and security:

rag_sources:
  # High-priority architectural decisions
  - path: 'docs/adr/*.md'
    weight: 1.0

  # Security guidelines with high weight
  - path: 'docs/security/**/*.md'
    weight: 0.9

  # API documentation
  - path: 'docs/api/**/*.{md,yaml,json}'
    weight: 0.8

  # General coding standards
  - path: 'docs/coding-standards/**'
    weight: 0.7

  # Examples and tutorials (lower priority)
  - path: 'examples/**/*.{js,ts,py}'
    weight: 0.5

RAG Security Controls

Advanced AI rules can include RAG-specific security controls:

- name: 'Advanced security review with RAG'
  condition: 'ai-review'
  severity: 'error'
  paths: ['src/api/**', 'src/auth/**']
  parameters:
    prompt: |
      Review this code for security vulnerabilities using our team's 
      security guidelines and architectural decisions.
    ragContext:
      maxDocs: 5 # Maximum documents to retrieve
      similarityThreshold: 0.8 # Minimum relevance threshold
    security:
      allowSensitiveFiles: false # Block sensitive file access
      maxFilesPerReview: 15 # Limit files per review
      enableContentFiltering: true # Enable content filtering

RAG Context Parameters

Parameter	Type	Default	Description
`maxDocs`	`number`	`3`	Maximum documents to retrieve (1-10)
`similarityThreshold`	`number`	`0.7`	Minimum relevance threshold (0.5-1.0)

Security Settings

Parameter	Type	Default	Description
`allowSensitiveFiles`	`boolean`	`false`	Allow access to sensitive files
`maxFilesPerReview`	`number`	`20`	Maximum files per review (1-50)
`enableContentFiltering`	`boolean`	`true`	Enable content filtering

⚙️ Global Settings

Team-Wide Configuration

Configure global settings that apply to all rules in your repository:

# .github/ship-gaurd.yml
version: 1
default_severity: 'error'

# Global settings for team-wide customization
settings:
  # Maximum findings to report (prevent spam)
  maxFindings: 50

  # Custom comment templates
  commentTemplates:
    success: '✅ All checks passed! Great work!'
    error: '❌ Issues found that need attention:'
    warning: '⚠️ Suggestions for improvement:'

  # Control comment behavior
  maxFindingsInComment: 25
  disableComments: false
  disableStatusChecks: false

  # Enable/disable AI reviews globally
  enableAIReviews: true

Global Settings Reference

Setting	Type	Default	Description
`maxFindings`	`number`	`50`	Maximum findings to report (1-200)
`maxFindingsInComment`	`number`	`25`	Max findings per comment
`disableComments`	`boolean`	`false`	Disable PR comments
`disableStatusChecks`	`boolean`	`false`	Disable status checks
`enableAIReviews`	`boolean`	`false`	Enable AI reviews globally

Custom Comment Templates

Create personalized comment templates for your team:

settings:
  commentTemplates:
    success: |
      🎉 **Ship Guard - All Checks Passed!**

      Great work! This PR meets all our team's standards.

      **Checks completed:**
      - Code quality standards ✅
      - Security requirements ✅
      - Documentation requirements ✅

    error: |
      🚨 **Ship Guard - Issues Found**

      The following issues need to be addressed before merging:

      {findings}

      Please review and fix these issues.

    warning: |
      ⚠️ **Ship Guard - Suggestions**

      Consider the following improvements:

      {findings}

      These are suggestions and won't block merging.

Team-Specific Customizations

Frontend Team Configuration

# Frontend team - React/TypeScript focus
version: 1
default_severity: 'warning'

rag_sources:
  - path: 'docs/frontend-standards.md'
    weight: 1.0
  - path: 'docs/component-guidelines.md'
    weight: 0.9

rules:
  # Accessibility compliance
  - name: 'Accessibility requirements'
    condition: 'ai-review'
    tags: ['accessibility', 'frontend']
    paths: ['src/components/**/*.{tsx,jsx}']
    parameters:
      prompt: |
        Check React components for accessibility compliance:
        - ARIA attributes usage
        - Keyboard navigation support
        - Color contrast requirements
        - Screen reader compatibility

  # Component structure
  - name: 'Component structure standards'
    condition: 'ai-review'
    tags: ['structure', 'frontend']
    paths: ['src/components/**/*.{tsx,jsx}']
    parameters:
      prompt: |
        Verify component structure follows our standards:
        - Proper prop typing with TypeScript
        - Consistent naming conventions
        - Separation of concerns
        - Reusable component patterns

Backend Team Configuration

# Backend team - API and security focus
version: 1
default_severity: 'error'

rag_sources:
  - path: 'docs/api-standards.md'
    weight: 1.0
  - path: 'docs/security-guidelines.md'
    weight: 1.0

rules:
  # API contract validation
  - name: 'API contract compliance'
    condition: 'ai-review'
    tags: ['api', 'contracts']
    paths: ['src/api/**/*.ts', 'src/routes/**/*.ts']
    parameters:
      prompt: |
        Review API endpoints for contract compliance:
        - Consistent response formats
        - Proper error handling
        - Input validation
        - Authentication requirements

  # Security best practices
  - name: 'Security review'
    condition: 'ai-review'
    tags: ['security', 'backend']
    paths: ['src/**/*.ts']
    parameters:
      prompt: |
        Security review focusing on:
        - SQL injection prevention
        - Input sanitization
        - Authentication/authorization
        - Sensitive data handling

DevOps Team Configuration

# DevOps team - Infrastructure and deployment focus
version: 1
default_severity: 'error'

rag_sources:
  - path: 'docs/infrastructure-standards.md'
    weight: 1.0
  - path: 'docs/deployment-guidelines.md'
    weight: 0.9

rules:
  # Infrastructure as Code
  - name: 'Infrastructure standards'
    condition: 'ai-review'
    tags: ['infrastructure', 'devops']
    paths: ['terraform/**/*.tf', 'kubernetes/**/*.yaml']
    parameters:
      prompt: |
        Review infrastructure code for:
        - Security best practices
        - Resource naming conventions
        - Cost optimization
        - Compliance requirements

  # Deployment safety
  - name: 'Deployment safety checks'
    condition: 'ai-review'
    tags: ['deployment', 'safety']
    paths: ['deploy/**/*.yaml', 'helm/**/*.yaml']
    parameters:
      prompt: |
        Verify deployment configurations:
        - Resource limits and requests
        - Health check configurations
        - Rollback strategies
        - Environment-specific settings

🔒 Security and Performance

Performance Optimization

Optimize Ship Guard for large repositories:

settings:
  # Performance settings
  maxFindings: 30 # Reduce findings for faster processing
  maxFindingsInComment: 15 # Limit comment size

  # File processing limits
  maxFilesPerReview: 25 # Limit files per review
  maxFileSizeKB: 200 # Skip large files

Security Hardening

Enhance security for sensitive repositories:

settings:
  # Security settings
  enableContentFiltering: true # Enable content filtering
  disableComments: false # Keep comments for transparency

  # AI review security
  enableAIReviews: true # Enable AI reviews
  maxTokens: 500 # Limit AI response size

Advanced Security Rules

rules:
  # Sensitive data detection
  - name: 'Sensitive data protection'
    condition: 'ai-review'
    tags: ['security', 'sensitive-data']
    severity: 'error'
    parameters:
      prompt: |
        Scan for sensitive data exposure:
        - API keys and secrets
        - Database credentials
        - Personal information
        - Internal URLs or endpoints
      security:
        allowSensitiveFiles: false
        enableContentFiltering: true
        maxFilesPerReview: 10

📊 Advanced Reporting

Custom Error Codes

Use custom error codes for better categorization and reporting:

rules:
  - name: 'Security vulnerability scan'
    condition: 'security-scan'
    errorCode: 'SEC-VULN-001'
    tags: ['security', 'vulnerabilities']

  - name: 'Code quality standards'
    condition: 'ai-review'
    errorCode: 'QUALITY-001'
    tags: ['quality', 'standards']

  - name: 'Documentation requirements'
    condition: 'require-documentation'
    errorCode: 'DOC-001'
    tags: ['documentation', 'compliance']

Tag-Based Filtering

Filter and report based on rule tags:

# Example: Focus on security rules only
rules:
  - name: 'Security review'
    condition: 'ai-review'
    tags: ['security']
    paths: ['src/**/*.ts']

  - name: 'Authentication check'
    condition: 'ai-review'
    tags: ['security', 'auth']
    paths: ['src/auth/**/*.ts']

  - name: 'Input validation'
    condition: 'ai-review'
    tags: ['security', 'validation']
    paths: ['src/api/**/*.ts']

Complete Advanced Example

Here's a comprehensive example showing advanced configuration features:

# .github/ship-guard.yml
version: 1
default_severity: 'error'

# Advanced RAG configuration
rag_sources:
  - path: 'docs/architecture/*.md'
    weight: 1.0
  - path: 'docs/security-guidelines.md'
    weight: 1.0
  - path: 'docs/coding-standards/**'
    weight: 0.8
  - path: 'docs/api/**'
    weight: 0.7

# Global settings
settings:
  maxFindings: 50
  maxFindingsInComment: 25
  disableComments: false
  disableStatusChecks: false
  enableAIReviews: true

  # Custom comment templates
  commentTemplates:
    success: '🎉 All checks passed! Great work!'
    error: '🚨 Issues found that need attention:'
    warning: '⚠️ Suggestions for improvement:'

# Advanced rules with custom properties
rules:
  # === SECURITY RULES ===
  - name: 'Advanced security review'
    condition: 'ai-review'
    severity: 'error'
    enabled: true
    errorCode: 'SEC-001'
    tags: ['security', 'critical']
    paths: ['src/api/**', 'src/auth/**']
    parameters:
      prompt: |
        Comprehensive security review using our security guidelines:
        1. Input validation and sanitization
        2. Authentication and authorization
        3. Sensitive data handling
        4. SQL injection prevention
        5. XSS protection
      maxTokens: 800
      ragContext:
        maxDocs: 5
        similarityThreshold: 0.8
      security:
        allowSensitiveFiles: false
        maxFilesPerReview: 15
        enableContentFiltering: true

  # === CODE QUALITY RULES ===
  - name: 'Architecture compliance'
    condition: 'policy-question'
    severity: 'warning'
    enabled: true
    errorCode: 'ARCH-001'
    tags: ['architecture', 'compliance']
    parameters:
      prompt: |
        Does this PR follow our established architectural patterns 
        and decision records? If it introduces new patterns or 
        deviates from established ones, does it need architectural review?

  - name: 'Code quality standards'
    condition: 'ai-review'
    severity: 'warning'
    enabled: true
    errorCode: 'QUALITY-001'
    tags: ['quality', 'standards']
    paths: ['src/**/*.ts']
    excludePaths: ['**/*.test.ts', '**/*.spec.ts']
    parameters:
      prompt: |
        Review code quality using our coding standards:
        - Consistent naming conventions
        - Proper error handling patterns
        - Code organization and structure
        - Comment and documentation quality
      maxTokens: 600

  # === TESTING RULES ===
  - name: 'Test coverage requirements'
    condition: 'require-tests'
    severity: 'warning'
    enabled: true
    errorCode: 'TEST-001'
    tags: ['testing', 'coverage']
    paths: ['src/**/*.ts']
    excludePaths: ['src/types/**', 'src/utils/**']
    parameters:
      testPaths: ['tests/**', 'src/**/*.test.ts', 'src/**/*.spec.ts']
      requireForPaths: ['src/**/*.ts']
      matchStrategy: 'co-located'
      minChangedTests: 1

Best Practices for Advanced Configuration

🎯 Start with Essentials

Begin with basic rules and gradually add advanced features
Test new configurations on small repositories first
Monitor performance impact of complex rules

🔒 Security First

Always enable content filtering for AI reviews
Use appropriate file size and count limits
Regularly review and update security rules

📊 Monitor and Optimize

Track rule effectiveness and adjust as needed
Monitor AI review costs and optimize token usage
Use tags and error codes for better reporting

🎨 Team Collaboration

Document your configuration decisions
Share best practices across teams
Regular reviews of rule effectiveness

📚 Additional Resources

Topic	Description	Link
Glossary & Concepts	Key terms and platform concepts	glossary.md
Security & Permissions	GitHub scopes, data flow, retention, IP protection	security-and-permissions.md
Troubleshooting	Common issues, diagnostics, and quick fixes	troubleshooting.md
Incident Memory	Setting up incident and tracking them	incident-memory.md

📋 What You'll Learn​

🎯 Advanced Rule Configuration​

Enhanced Rule Properties​

Advanced Rule Properties​

Rule Organization with Tags​

Advanced RAG Integration​

Sophisticated RAG Configuration​

RAG Security Controls​

RAG Context Parameters​

Security Settings​

⚙️ Global Settings​

Team-Wide Configuration​

Global Settings Reference​

Custom Comment Templates​

Team-Specific Customizations​

Frontend Team Configuration​

Backend Team Configuration​

DevOps Team Configuration​

🔒 Security and Performance​

Performance Optimization​

Security Hardening​

Advanced Security Rules​

📊 Advanced Reporting​

Custom Error Codes​

Tag-Based Filtering​

Complete Advanced Example​

Best Practices for Advanced Configuration​

🎯 Start with Essentials​

🔒 Security First​

📊 Monitor and Optimize​

🎨 Team Collaboration​

📚 Additional Resources​