1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
|
# 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
- `internal/modules/` - Go module proxy endpoints and go-import metadata
- **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=$PWD/testdata go run cmd/tokentool/main.go -generate -name <username>
# List existing tokens
TMPDIR=$PWD/testdata 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**: **CRITICAL** - /tmp filesystem doesn't allow executables. Always use `TMPDIR=$PWD/testdata` for `go run` commands
- **Go Module Support**: Implements basic Go module proxy protocol for `go get` compatibility
## 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.
## Go Module Support
The server implements basic Go module proxy functionality to enable `go get` operations:
### Usage
```bash
# Enable go module proxy (make repositories discoverable)
go get yourdomain.com/repo
# The server automatically serves:
# - go-import meta tags for module discovery
# - Module proxy endpoints (@v/list, @latest, .info, .mod, .zip)
# - Version metadata from git tags
```
### Features
- **Module Discovery**: Serves go-import HTML meta tags
- **Version Listing**: Lists available versions from git tags
- **Pseudo-versions**: Generates pseudo-versions for untagged commits
- **Module Archives**: Creates zip files from git repository content
- **go.mod Serving**: Extracts go.mod files from specific versions
### Limitations
- Basic implementation focused on compatibility, not full Athens-style features
- No caching, authentication bypass, or advanced proxy features
- Requires properly tagged semantic versions (v1.0.0, v1.2.3, etc.)
## 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
|
