# CLAUDE.md

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

## Project Overview

This is `go-git-server`, an experimental Git HTTP server in Go that provides authentication and authorization for Git repositories. It wraps the built-in `git-http-backend` CGI process to maintain compatibility while adding security features.

## Key Architecture

- **Main Entry Point**: `cmd/main.go` - HTTP server with middleware stack
- **Core Components**:
  - `internal/git/handler.go` - Git HTTP backend CGI wrapper
  - `internal/authz/` - Authentication/authorization middleware using Casbin
  - `internal/admin/` - Administrative services and configuration management
- **Configuration**: Uses Casbin for RBAC with auth model (`auth_model.ini`) and policy files
- **Authentication**: Token-based system with bcrypt hashing stored in CSV format
- **Authorization**: Role-based access control with roles like admin, maintainers, bots

## Common Commands

### Development
```bash
# Run tests and linting
just test

# Build the application
just build <version>

# Run server locally with debug mode
just debug-run

# Run specific test with debugger
just debug-test <package> <function>

# Run server with sample data
just run [repo_path]
```

### Testing
```bash
# Run all tests with coverage
just test

# Coverage is automatically generated in temp directories
```

### Building and Deployment
```bash
# Create new version and build
just release <part>  # where part is: patch, minor, major, or latest

# Build Docker image
just docker-build

# Local Kubernetes deployment
just local-deploy

# Clean build artifacts
just clean
```

### Token Management
```bash
# Generate new authentication token
TMPDIR=/tmp/go-build go run cmd/tokentool/main.go -generate -name <username>

# List existing tokens
TMPDIR=/tmp/go-build go run cmd/tokentool/main.go -list

# Generate token directly from main binary
./main -g
```

## Development Notes

- **Go Version**: Requires Go 1.24+
- **Dependencies**: Uses Casbin for authorization, go-git for Git operations
- **Testing**: Uses standard Go testing with coverage reporting
- **Linting**: Uses golangci-lint
- **Build System**: Uses `just` (justfile) for task automation
- **Container**: Designed for Kubernetes deployment with minimal dependencies
- **TMPDIR**: Use `TMPDIR=/tmp/go-build` for `go run` commands if /tmp filesystem doesn't allow executables

## Large File Support

For pushing large binary files (>1MB), clients need to increase git's HTTP POST buffer:

```bash
# Global configuration (recommended)
git config --global http.postBuffer 524288000

# Per-repository configuration
git config http.postBuffer 524288000
```

This setting allows git to handle large file pushes over HTTP without timing out.

## Configuration Files

- `gitserver.yaml` - Server configuration and repository definitions
- `auth_model.ini` - Casbin authentication model
- `policy.csv` - Casbin authorization policies
- `tokens.csv` - Authentication tokens (format: access_id,friendly_name,hash)

## Code Conventions

From `CONVENTIONS.md`:
- Prefer idiomatic Go code
- Minimize dependencies
- Expert-level Git and Go programming expected
- Building a proxy server for `git-http-backend`

# Workflow

1. Write Tests
2. Lint Code
3. Commit
4. Write Code
5. Lint
6. Run tests
7. Fix Code
8. Lint
6. Iterate