claude-hub/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Claude Gitea Webhook

This repository contains a webhook service that integrates Claude with Gitea, allowing Claude to respond to mentions in Gitea comments, help with repository tasks, and automatically respond to CI failures. When someone mentions the configured bot username (configured via environment variables) in a Gitea issue or PR comment, the system processes the command with Claude Code and returns a helpful response.

Documentation Structure

• /docs/complete-workflow.md - Comprehensive workflow documentation
• /docs/gitea-workflow.md - Gitea-specific integration details
• /docs/container-setup.md - Docker container configuration
• /docs/container-limitations.md - Container execution constraints
• /docs/aws-authentication-best-practices.md - AWS credential management
• /docs/aws-profile-quickstart.md - Quick setup for AWS profiles
• /docs/aws-profile-setup.md - Detailed AWS profile configuration

Build & Run Commands

TypeScript Build Commands

• Build TypeScript: npm run build (compiles to dist/ directory)
• Build TypeScript (watch mode): npm run build:watch
• Type checking only: npm run typecheck (no compilation)
• Clean build artifacts: npm run clean

Setup and Installation

• Initial setup: ./scripts/setup.sh
• Setup secure credentials: ./scripts/setup/setup-secure-credentials.sh
• Start with Docker (recommended): docker compose up -d
• Start production build: npm start (runs compiled JavaScript from dist/)
• Start development build: npm run start:dev (runs JavaScript directly from src/)
• Development mode with TypeScript: npm run dev (uses ts-node)
• Development mode with auto-restart: npm run dev:watch (uses nodemon + ts-node)
• Start on specific port: ./scripts/runtime/start-api.sh (uses port 3003)
• Run tests: npm test
• Run specific test types:
  • Unit tests: npm run test:unit (supports both .js and .ts files)
  • End-to-end tests: npm run test:e2e (supports both .js and .ts files)
  • Test with coverage: npm run test:coverage
  • Watch mode: npm run test:watch

Docker Commands

• Start services: docker compose up -d (uses secure credentials)
• Stop services: docker compose down
• View logs: docker compose logs -f webhook
• Restart: docker compose restart webhook
• Build Claude container: ./build-claude-container.sh
• Build Claude Code container: ./scripts/build/build.sh claudecode
• Update production image: ./update-production-image.sh

AWS Credential Management

• Create AWS profile: ./scripts/create-aws-profile.sh
• Migrate from static credentials: ./scripts/migrate-aws-credentials.sh
• Setup AWS profiles: ./scripts/setup-aws-profiles.sh
• Setup Claude authentication: ./scripts/setup/setup-claude-auth.sh

Testing Utilities

• Test Claude webhook API (async): node test/test-claude-api.js owner/repo async "Your command here"
• Check session status: node test/test-claude-api.js status <sessionId>
• Test outgoing webhook: node test/test-outgoing-webhook.js
• Test pre-commit hooks: pre-commit run --all-files
• Test AWS credential provider: node test/test-aws-credential-provider.js
• Test Claude container: ./test/test-claudecode-docker.sh
• Test full workflow: ./test/test-full-flow.sh

CI/CD Commands

• Run linting: npm run lint (auto-fix) or npm run lint:check (check only)
• Run formatting: npm run format (auto-fix) or npm run format:check (check only)
• Run security audit: npm run security:audit
• Fix security vulnerabilities: npm run security:fix
• All CI tests: npm run test:ci (includes coverage)

Pre-commit Hooks

The project uses Husky for Git pre-commit hooks to ensure code quality:

• ESLint: Checks code for linting errors
• Prettier: Validates code formatting
• TypeScript: Runs type checking
• Setup: Hooks are automatically installed via npm run prepare
• Manual run: Execute .husky/pre-commit to test locally

End-to-End Testing

Use a test repository for testing auto-tagging and webhook functionality:

• Test auto-tagging: ./cli/webhook-cli.js --repo "owner/test-repo" --command "Auto-tag this issue" --issue 1 --url "http://localhost:8082"
• Test with specific issue content: Create a new issue in a test repository to trigger auto-tagging webhook
• Verify labels are applied based on issue content analysis

Label Management

• Setup repository labels: GITEA_TOKEN=your_token node scripts/utils/setup-repository-labels.js owner/repo

CLI Commands

• Basic usage: ./cli/claude-webhook myrepo "Your command for Claude"
• With explicit owner: ./cli/claude-webhook owner/repo "Your command for Claude"
• Pull request review: ./cli/claude-webhook myrepo "Review this PR" -p -b feature-branch
• Specific issue: ./cli/claude-webhook myrepo "Fix issue" -i 42
• Advanced usage: node cli/webhook-cli.js --repo myrepo --command "Your command" --verbose
• Secure mode: node cli/webhook-cli-secure.js (uses AWS profile authentication)

Claude Authentication Options

This service supports three authentication methods:

• Setup Container: Personal subscription authentication - Setup Container Guide
• ANTHROPIC_API_KEY: Direct API key authentication - Authentication Guide
• AWS Bedrock: Enterprise AWS integration - Authentication Guide

Quick Start: Setup Container

For personal subscription users:

# 1. Run interactive authentication setup
./scripts/setup/setup-claude-interactive.sh

# 2. In container: authenticate with your subscription
claude --dangerously-skip-permissions  # Follow authentication flow
exit                                    # Save authentication

# 3. Test captured authentication
./scripts/setup/test-claude-auth.sh

# 4. Use in production
cp -r ${CLAUDE_HUB_DIR:-~/.claude-hub}/* ~/.claude/

📖 See Complete Authentication Guide for all methods

Features

Auto-Tagging

The system automatically analyzes new issues and applies appropriate labels using a secure, minimal-permission approach:

Security Features:

• Minimal Tool Access: Uses only Read and Gitea API tools (no file editing or bash execution)
• Dedicated Container: Runs in specialized container with restricted entrypoint script
• API-Based: Uses Gitea REST API directly for reliable label management

Label Categories:

• Priority: critical, high, medium, low
• Type: bug, feature, enhancement, documentation, question, security
• Complexity: trivial, simple, moderate, complex
• Component: api, frontend, backend, database, auth, webhook, docker

Process Flow:

1. New issue triggers issues.opened webhook from Gitea
2. Dedicated Claude container starts with claudecode-tagging-entrypoint.sh
3. Claude analyzes issue content using minimal tools
4. Labels applied via Gitea REST API
5. No comments posted (silent operation)
6. Fallback to keyword-based labeling if API approach fails

Automated PR Review

The system automatically triggers comprehensive PR reviews when all checks pass:

• Trigger: pull_request webhook events
• Scope: Reviews all PRs as requested
• Process: Claude performs security, logic, performance, and code quality analysis
• Output: Detailed review comments, line-specific feedback, and approval/change requests
• Integration: Uses Gitea REST API for seamless review workflow

CI Failure Response

The system can automatically respond to CI/CD workflow failures:

• Trigger: workflow_run or workflow_job webhook events with conclusion: 'failure'
• Process: Claude analyzes the failure logs and attempts to diagnose the issue
• Output: Creates a fix PR with proposed changes or comments with analysis
• Integration: Uses Gitea Actions API to fetch workflow logs

Architecture Overview

Core Components

1. Express Server (src/index.ts): Main application entry point that sets up middleware, routes, and error handling
2. Routes:
   • Webhook Router: /api/webhooks/:provider - Processes webhook events from configured providers
   • Claude API: /api/claude - Direct API access to Claude
   • Health Check: /health - Service status monitoring
3. Providers:
   • providers/gitea/ - Gitea webhook handling and API client
   • providers/claude/ - Claude orchestration and session management
4. Services:
   • claudeService.ts - Interfaces with Claude Code CLI
   • providers/gitea/GiteaApiClient.ts - Handles Gitea REST API interactions
5. Utilities:
   • logger.ts - Logging functionality with redaction capability
   • awsCredentialProvider.ts - Secure AWS credential management
   • sanitize.ts - Input sanitization and security

Execution Modes & Security Architecture

The system uses different execution modes based on operation type:

Operation Types:

• Auto-tagging: Minimal permissions (Read tool only, uses Gitea API)
• PR Review: Standard permissions (full tool set)
• CI Failure Fix: Standard permissions (full tool set for code fixes)
• Default: Standard permissions (full tool set)

Security Features:

• Tool Allowlists: Each operation type uses specific tool restrictions
• Dedicated Entrypoints: Separate container entrypoint scripts for different operations
• No Dangerous Permissions: System avoids --dangerously-skip-permissions flag
• Container Isolation: Docker containers with minimal required capabilities

Container Entrypoints:

• claudecode-tagging-entrypoint.sh: Minimal tools for auto-tagging (--allowedTools Read)
• claudecode-entrypoint.sh: Full tools for general operations (--allowedTools Bash,Create,Edit,Read,Write)

DevContainer Configuration: The repository includes a .devcontainer configuration for development:

• Privileged mode for system-level access
• Network capabilities (NET_ADMIN, NET_RAW) for firewall management
• System capabilities (SYS_TIME, DAC_OVERRIDE, AUDIT_WRITE, SYS_ADMIN)
• Docker socket mounting for container management
• Automatic firewall initialization via post-create command

Workflow

1. Gitea comment with bot mention (configured via BOT_USERNAME) triggers a webhook event
2. Express server receives the webhook at /api/webhooks/gitea
3. GiteaWebhookProvider verifies the signature and parses the event
4. Appropriate handler processes the event (issue, PR, workflow failure, etc.)
5. Service extracts the command and processes it with Claude in a Docker container
6. Claude analyzes the repository and responds to the command
7. Response is posted back to Gitea via the REST API

AWS Authentication

The service supports multiple AWS authentication methods, with a focus on security:

• Profile-based authentication: Uses AWS profiles from ~/.aws/credentials
• Instance Profiles (EC2): Automatically uses instance metadata
• Task Roles (ECS): Automatically uses container credentials
• Direct credentials: Not recommended, but supported for backward compatibility

The awsCredentialProvider.ts utility handles credential retrieval and rotation.

Security Features

• Webhook signature verification using HMAC-SHA256 (x-gitea-signature header)
• Credential scanning in pre-commit hooks
• Container isolation for Claude execution
• AWS profile-based authentication
• Input sanitization and validation
• Docker capability restrictions
• Firewall initialization for container networking

Configuration

• Environment variables are loaded from .env file
• AWS Bedrock credentials for Claude access
• Gitea tokens and webhook secrets
• Container execution settings
• Webhook URL and port configuration

Required Environment Variables

• BOT_USERNAME: Username that the bot responds to (e.g., @ClaudeBot)
• DEFAULT_AUTHORIZED_USER: Default username authorized to use the bot (if AUTHORIZED_USERS is not set)
• AUTHORIZED_USERS: Comma-separated list of usernames authorized to use the bot
• BOT_EMAIL: Email address used for git commits made by the bot
• GITEA_API_URL: Gitea API base URL (e.g., https://git.example.com/api/v1)
• GITEA_WEBHOOK_SECRET: Secret for validating Gitea webhook payloads
• GITEA_TOKEN: Gitea personal access token for API access
• ANTHROPIC_API_KEY: Anthropic API key for Claude access

Optional Environment Variables

• PR_REVIEW_WAIT_FOR_ALL_CHECKS: Set to "true" to wait for all workflow runs to complete successfully before triggering PR review (default: "true").
• PR_REVIEW_TRIGGER_WORKFLOW: Name of a specific Gitea Actions workflow that should trigger PR reviews (e.g., "Pull Request CI"). Only used if PR_REVIEW_WAIT_FOR_ALL_CHECKS is "false".
• PR_REVIEW_DEBOUNCE_MS: Delay in milliseconds before checking workflow status (default: "5000").
• PR_REVIEW_MAX_WAIT_MS: Maximum time to wait for in-progress workflows before considering them failed (default: "1800000" = 30 minutes).
• PR_REVIEW_CONDITIONAL_TIMEOUT_MS: Time to wait for conditional jobs that never start before skipping them (default: "300000" = 5 minutes).

Gitea Webhook Setup

To configure Gitea to send webhooks to this service:

1. Go to your repository's Settings → Webhooks → Add Webhook → Gitea
2. Configure the webhook:
   • Target URL: https://your-claude-hub-domain/api/webhooks/gitea
   • HTTP Method: POST
   • Content Type: application/json
   • Secret: Match the GITEA_WEBHOOK_SECRET environment variable
3. Select events to trigger the webhook:
   • Issues: For issue auto-tagging
   • Issue Comment: For bot mentions in issue comments
   • Pull Request: For PR events
   • Pull Request Comment: For bot mentions in PR comments
   • Workflow Run: For CI failure detection (Gitea Actions)
   • Workflow Job: For job-level CI failure detection
4. Save the webhook and test with the "Test Delivery" button

Gitea Personal Access Token

Create a personal access token with these scopes:

• read:repository - Read repository content
• write:issue - Create/edit issues and comments
• write:repository - Push commits, create branches/PRs

Generate at: https://your-gitea-instance/user/settings/applications

TypeScript Infrastructure

The project is configured with TypeScript for enhanced type safety and developer experience:

Configuration Files

• tsconfig.json: TypeScript compiler configuration with strict mode enabled
• eslint.config.js: ESLint configuration with TypeScript support and strict rules
• jest.config.js: Jest configuration with ts-jest for TypeScript test support
• babel.config.js: Babel configuration for JavaScript file transformation

Build Process

• TypeScript source files in src/ compile to JavaScript in dist/
• Support for both .js and .ts files during the transition period
• Source maps enabled for debugging compiled code
• Watch mode available for development with automatic recompilation

Migration Strategy

• Phase 1 (Current): Infrastructure setup with TypeScript tooling
• Phase 2 (Future): Gradual conversion of JavaScript files to TypeScript
• Backward Compatibility: Existing JavaScript files continue to work during transition

Code Style Guidelines

• TypeScript/JavaScript with Node.js (ES2022 target)
• Use async/await for asynchronous operations
• Comprehensive error handling and logging
• camelCase variable and function naming
• Input validation and sanitization for security
• TypeScript specific:
  • Strict mode enabled for all TypeScript files
  • Interface definitions preferred over type aliases
  • Type imports when importing only for types
  • No explicit any types (use unknown or proper typing)