Configuring the AI Coding Rules Backend Plugin#

This guide covers the configuration options available for the AI Coding Rules backend plugin.

Basic Configuration#

Rule Types Configuration#

Configure which rule types the backend should search for in your app-config.yaml:

aiRules:
  allowedRuleTypes:
    - cursor
    - copilot
    - cline
    - claude-code
  defaultRuleTypes:
    - cursor
    - claude-code

Configuration Schema#

Option	Type	Default	Description
`allowedRuleTypes`	`string[]`	`["cursor", "copilot", "cline", "claude-code"]`	Array of rule types to search for and parse
`defaultRuleTypes`	`string[]`	`[]`	Array of rule types pre-selected when component loads

Default Configuration#

If no configuration is provided, the plugin defaults to:

aiRules:
  allowedRuleTypes:
    - cursor
    - copilot
    - cline
    - claude-code
  defaultRuleTypes: []

SCM Integration Requirements#

GitHub Configuration#

For GitHub repositories:

integrations:
  github:
    - host: github.com
      token: ${GITHUB_TOKEN}
    # For GitHub Enterprise
    - host: github.enterprise.com
      token: ${GITHUB_ENTERPRISE_TOKEN}
      apiBaseUrl: https://github.enterprise.com/api/v3

GitLab Configuration#

For GitLab repositories:

integrations:
  gitlab:
    - host: gitlab.com
      token: ${GITLAB_TOKEN}
    # For self-hosted GitLab
    - host: gitlab.company.com
      token: ${GITLAB_COMPANY_TOKEN}
      apiBaseUrl: https://gitlab.company.com/api/v4

Azure DevOps Configuration#

For Azure DevOps repositories:

integrations:
  azure:
    - host: dev.azure.com
      token: ${AZURE_TOKEN}
    # For Azure DevOps Server
    - host: tfs.company.com
      token: ${TFS_TOKEN}

Bitbucket Configuration#

For Bitbucket repositories:

integrations:
  bitbucket:
    - host: bitbucket.org
      username: ${BITBUCKET_USERNAME}
      appPassword: ${BITBUCKET_APP_PASSWORD}
    # For Bitbucket Server
    - host: bitbucket.company.com
      token: ${BITBUCKET_SERVER_TOKEN}

Rule Type Specifications#

Cursor Rules#

Cursor rules are found in .cursor/rules/*.mdc files with optional frontmatter:

# Configuration
aiRules:
  allowedRuleTypes:
    - cursor

# Rule file structure
# .cursor/rules/typescript.mdc
---
description: "TypeScript coding standards"
globs: ["*.ts", "*.tsx"]
alwaysApply: true
---

# TypeScript Rules
Use strict typing and avoid any types.

GitHub Copilot Rules#

Copilot rules are found in .github/copilot-instructions.md:

# Configuration
aiRules:
  allowedRuleTypes:
    - copilot

# Rule file structure  
# .github/copilot-instructions.md
# Development Guidelines

Use TypeScript for all new code.
Follow existing code patterns.

Prefer functional components in React.
Use hooks instead of class components.

Cline Rules#

Cline rules are found in .clinerules/*.md files:

# Configuration
aiRules:
  allowedRuleTypes:
    - cline

# Rule file structure
# .clinerules/development.md
# Development Guidelines

## Code Style
- Use ESLint and Prettier
- Follow team conventions

## Testing
- Write unit tests for all functions

Claude Code Rules#

Claude Code rules are found in CLAUDE.md file in repository root:

# Configuration
aiRules:
  allowedRuleTypes:
    - claude-code

# Rule file structure
# CLAUDE.md (in repository root)
# Claude Code Guidelines

## Development Principles
- Write clean, readable code
- Follow SOLID principles
- Use meaningful variable names

## Code Review Standards
- All code must be reviewed
- Tests must pass before merge

Environment-Specific Configuration#

Development Environment#

# app-config.development.yaml
aiRules:
  allowedRuleTypes:
    - cursor
    - copilot
    - cline

backend:
  logger:
    level: debug # Enable debug logging

Production Environment#

# app-config.production.yaml
aiRules:
  allowedRuleTypes:
    - copilot # Only official guidelines in production

backend:
  logger:
    level: info # Standard logging level

Testing Environment#

# app-config.test.yaml
aiRules:
  allowedRuleTypes:
    - cursor
    - copilot
    - cline

# Mock SCM integrations for testing
integrations:
  github:
    - host: github.com
      token: mock-token

Security Configuration#

Token Security#

Store authentication tokens securely:

# Environment variables
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
export GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
export AZURE_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxx

Repository Access Control#

Ensure tokens have minimal required permissions:

GitHub: repo scope for private repos, or public_repo for public repos
GitLab: read_repository permission
Azure DevOps: Code (read) permission
Bitbucket: Repositories: Read permission

Performance and Rate Limiting#

Retry Logic Configuration#

The backend includes built-in retry logic with exponential backoff to handle rate limiting and network issues:

# Default retry configuration (not user-configurable)
# - Max retries: 3 attempts
# - Initial delay: 1 second  
# - Max delay: 10 seconds
# - Exponential backoff with jitter

Retry Behavior#

The plugin automatically retries on these error conditions:

Rate Limiting: HTTP 429 "Too Many Requests"
Server Errors: HTTP 502, 503, 504
Network Issues: Timeouts, connection resets, DNS failures

Large Repository Optimization#

For large repositories with many rule files:

Automatic Retry: Failed requests are retried with increasing delays
Jitter: Random delays prevent thundering herd problems
Circuit Breaking: Stops retrying permanently failed requests
Logging: Detailed logs for debugging rate limit issues

Rate Limit Best Practices#

GitLab Rate Limits#

GitLab.com has stricter rate limits than GitHub:

# Consider using GitLab tokens with higher rate limits
integrations:
  gitlab:
    - host: gitlab.com
      token: ${GITLAB_TOKEN} # Use personal access token with appropriate scopes

GitHub Rate Limits#

GitHub has generous rate limits, but monitor usage:

integrations:
  github:
    - host: github.com
      token: ${GITHUB_TOKEN} # Authenticated requests have higher limits

Repository Access Patterns#

Optimize access patterns: - Avoid scanning extremely large repositories frequently - Consider caching strategies for frequently accessed rules - Monitor API usage in provider dashboards

Monitoring and Observability#

Health Checks#

The plugin provides health check endpoints:

# Check plugin health
curl http://localhost:7007/api/ai-rules/health

Metrics#

Monitor these key metrics:

API request rate and latency
Repository access success/failure rates
Rule parsing success/failure rates
Cache hit rates (when implemented)

Error Tracking#

Common error scenarios to monitor:

Repository Access Errors
Authentication failures
Network timeouts
Repository not found
Content Parsing Errors
Invalid frontmatter syntax
File encoding issues
Content too large
Entity Resolution Errors
Invalid entity references
Missing source locations
Catalog synchronization issues

Troubleshooting Configuration#

Validation#

Validate your configuration:

// Check configuration loading
import { Config } from '@backstage/config';

const config = /* your config instance */;
const allowedRuleTypes = config.getOptionalStringArray('aiRules.allowedRuleTypes') 
  ?? ['cursor', 'copilot'];

console.log('Configured rule types:', allowedRuleTypes);

Common Configuration Issues#

Invalid Rule Types#

# Incorrect - unsupported rule type
aiRules:
  allowedRuleTypes:
    - cursor
    - copilot
    - invalid-type # This will be ignored

# Correct
aiRules:
  allowedRuleTypes:
    - cursor
    - copilot
    - cline

Missing SCM Integration#

# Incomplete - missing required token
integrations:
  github:
    - host: github.com
      # Missing token

# Complete
integrations:
  github:
    - host: github.com
      token: ${GITHUB_TOKEN}

Environment Variable Issues#

# Check if environment variables are set
echo $GITHUB_TOKEN
echo $GITLAB_TOKEN

# Set if missing
export GITHUB_TOKEN=your_token_here

Configuration Testing#

Test your configuration:

# Start backend in debug mode
LOG_LEVEL=debug yarn dev

# Test API with configuration
curl "http://localhost:7007/api/ai-rules/rules?entityRef=component:default/test-service&ruleTypes=cursor,copilot"

Best Practices#

Configuration Management#

Use environment variables for sensitive data
Use separate config files for different environments
Validate configuration in CI/CD pipelines
Document all configuration options

Security#

Rotate tokens regularly
Use minimal required permissions
Monitor token usage
Secure configuration files

Performance#

Monitor API response times
Track repository access patterns
Plan for caching implementation
Set appropriate timeouts

Maintenance#

Keep SCM integrations updated
Monitor for deprecated configuration options
Review and update rule types as needed
Test configuration changes in staging