Gitea Self-Hosted Git Service Documentation¶

Table of Contents¶

Overview
Architecture
Access Information
Integration with Supabase PostgreSQL
Redis Integration
Git Hooks Configuration
Sync Workflow Details
Backup and Restore Procedures
Common Operations
Troubleshooting
Security Considerations

Overview¶

Gitea is a lightweight, self-hosted Git service that provides a complete development platform similar to GitHub or GitLab. In this infrastructure, Gitea serves as the primary source control system, offering:

Git repository hosting with SSH and HTTPS access
Web-based interface for repository management
Issue tracking and project management
Pull request workflow with code review
Webhook integrations for CI/CD
User and organization management
Repository mirroring capabilities
Git LFS (Large File Storage) support
Redis integration for enhanced caching and persistent sessions

The service is deployed as a Docker container and exposed via gitea.rbnk.uk with SSL termination handled by Traefik. Redis integration provides improved performance through caching (DB 3) and persistent user sessions (DB 1).

Architecture¶

Container Configuration¶

services:
  gitea:
    image: gitea/gitea:1.24.3
    container_name: gitea
    restart: unless-stopped
    networks:
      - traefik_proxy       # External access via Traefik
      - supabase_internal   # Database connectivity
      - cache_redis_network # Redis caching
      - session_redis_network # Redis sessions
    volumes:
      - ./data:/data        # Git repositories and Gitea data
      - ./config:/config    # Configuration files

Storage Structure¶

/srv/dockerdata/gitea/
├── data/
│   ├── gitea/           # Gitea application data
│   │   ├── conf/        # Runtime configuration
│   │   ├── log/         # Application logs
│   │   └── queues/      # Background job queues
│   ├── git/             # Git repositories
│   │   ├── repositories/# Bare git repositories
│   │   └── lfs/         # Large File Storage
│   └── ssh/             # SSH host keys
├── config/              # Additional configuration
├── sync-config/         # GitHub sync configuration
├── sync-logs/           # Synchronization logs
└── hooks/               # Git hook scripts

Network Architecture¶

Internal Network: Connected to supabase_internal for PostgreSQL access
External Network: Connected to traefik_proxy for HTTPS access
Redis Networks:
Connected to cache_redis_network for caching (DB 3)
Connected to session_redis_network for sessions (DB 1)
Ports:
Port 3000: HTTP web interface (internal)
Port 22: SSH Git access (mapped through host)

Access Information¶

Web Interface¶

URL: https://gitea.rbnk.uk
Admin User: Created during initial setup
Admin Credentials:
Check /srv/dockerdata/gitea/data/gitea/conf/app.ini for initial setup status
First registered user becomes admin if INSTALL_LOCK = false

SSH Access¶

# Clone via SSH
git clone [email protected]:username/repository.git

# SSH connection test
ssh -T [email protected]

HTTPS Access¶

# Clone via HTTPS
git clone https://gitea.rbnk.uk/username/repository.git

Git Remote Configuration¶

The standard remote naming convention is: - origin → Gitea (primary repository) - github → GitHub (mirror, auto-synced)

# After cloning, verify remotes
git remote -v

# Standard workflow - push to origin only
git push origin main

# GitHub sync happens automatically via:
# 1. Hourly systemd timer
# 2. Post-receive hook notifications

Development Workflow Setup¶

For development with dual remotes (Gitea + GitHub):

# 1. Clone from Gitea
git clone [email protected]:admin/infrastructure.git
cd infrastructure

# 2. Configure dual remotes
/srv/dockerdata/_scripts/setup-git-remotes.sh

# 3. Use Git aliases for efficient workflow
git push-all          # Push to both Gitea and GitHub
git sync-github       # Pull from GitHub, push to Gitea
git sync-gitea        # Pull from Gitea, push to GitHub

API Access¶

# API endpoint
https://gitea.rbnk.uk/api/v1/

# Example: List repositories
curl -H "Authorization: token YOUR_ACCESS_TOKEN" \
  https://gitea.rbnk.uk/api/v1/user/repos

Integration with Supabase PostgreSQL¶

Gitea is configured to use the Supabase PostgreSQL instance for its database needs:

Database Configuration¶

Located in /data/gitea/conf/app.ini:

[database]
DB_TYPE = postgres
HOST = supa-db:5432
NAME = gitea
USER = postgres
PASSWD = ${POSTGRES_PASSWORD}
SSL_MODE = disable

Database Schema¶

Gitea automatically creates its schema on first run: - Tables: ~40 tables for users, repositories, issues, etc. - Indexes: Optimized for Git operations and web UI queries - Foreign Keys: Maintain referential integrity

Database Operations¶

# Access Gitea database
docker exec -it supa-db psql -U postgres -d gitea

# Common queries
-- Repository statistics
SELECT COUNT(*) as repo_count FROM repository;

-- User activity
SELECT name, created_unix, last_login_unix 
FROM "user" 
ORDER BY last_login_unix DESC 
LIMIT 10;

-- Storage usage
SELECT 
  schemaname,
  tablename,
  pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) AS size
FROM pg_tables 
WHERE schemaname = 'public'
ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC;

Redis Integration¶

Gitea is configured to use Redis for caching and session storage to improve performance and provide persistent sessions across container restarts.

Redis Configuration¶

Redis integration is configured in /data/gitea/conf/app.ini:

[cache]
ENABLED = true
ADAPTER = redis
HOST = cache-redis:6379
DB = 3

[session]
PROVIDER = redis
PROVIDER_CONFIG = cache-redis:6379/1
COOKIE_SECURE = true
COOKIE_NAME = i_like_gitea

Performance Benefits¶

Faster Page Loads: Redis caching reduces database queries for frequently accessed data
Repository metadata
User authentication state
Configuration settings
File tree information
Persistent Sessions: Sessions survive container restarts and deployments
Users stay logged in during maintenance
No session loss during rolling updates
Better user experience
Scalability: Redis allows for horizontal scaling scenarios
Multiple Gitea instances can share the same cache
Session sharing between instances
Reduced database load

Redis Database Assignment¶

DB 1: Session storage (session_redis_network)
User login sessions
Authentication tokens
CSRF tokens
DB 3: Application caching (cache_redis_network)
Repository metadata cache
User profile cache
Configuration cache
Git object cache

Monitoring Redis Integration¶

# Check Redis connectivity from Gitea
docker exec -it gitea redis-cli -h cache-redis ping

# Monitor cache hit rates
docker exec -it cache-redis redis-cli info stats | grep keyspace_hits

# View session data
docker exec -it cache-redis redis-cli -n 1 keys "session:*" | wc -l

# Monitor cache usage
docker exec -it cache-redis redis-cli -n 3 info memory

# View cached keys
docker exec -it cache-redis redis-cli -n 3 keys "*" | head -10

Cache Performance Metrics¶

Access Redis metrics for monitoring:

# Cache hit ratio (should be > 80% for good performance)
docker exec -it cache-redis redis-cli info stats | grep -E 'keyspace_hits|keyspace_misses'

# Memory usage by database
docker exec -it cache-redis redis-cli info keyspace

# Connection statistics
docker exec -it cache-redis redis-cli info clients

# Operations per second
docker exec -it cache-redis redis-cli info stats | grep instantaneous_ops_per_sec

Redis Troubleshooting¶

Common Redis-related issues and solutions:

1. Cache Connection Failed¶

Symptoms: Gitea logs show Redis connection errors Solution:

# Test Redis connectivity
docker exec -it gitea ping cache-redis

# Check Redis container status
docker ps | grep cache-redis

# Verify network connectivity
docker network inspect cache_redis_network | grep gitea

2. Session Loss Issues¶

Symptoms: Users frequently logged out Solution:

# Check session Redis database
docker exec -it cache-redis redis-cli -n 1 dbsize

# Verify session configuration
docker exec -it gitea grep -A 5 '\[session\]' /data/gitea/conf/app.ini

# Monitor session creation/deletion
docker exec -it cache-redis redis-cli -n 1 monitor

3. High Memory Usage¶

Symptoms: Redis using excessive memory Solution:

# Check memory usage breakdown
docker exec -it cache-redis redis-cli info memory

# Set max memory limit
docker exec -it cache-redis redis-cli config set maxmemory 256mb
docker exec -it cache-redis redis-cli config set maxmemory-policy allkeys-lru

# Clear cache if needed (will impact performance temporarily)
docker exec -it cache-redis redis-cli -n 3 flushdb

4. Performance Issues¶

Symptoms: Slow page loads despite Redis Solution:

# Check cache hit ratio
docker exec -it cache-redis redis-cli info stats | grep hit_rate

# Monitor slow operations
docker exec -it cache-redis redis-cli slowlog get 10

# Check for blocked operations
docker exec -it cache-redis redis-cli info clients | grep blocked_clients

Cache Invalidation¶

Understanding when Gitea invalidates cache:

Repository Operations: Push, merge, delete
User Operations: Login, logout, profile changes
Administrative Changes: Settings, permissions
Time-based Expiry: Configurable TTL values

# Manual cache clear (if needed)
docker exec -it cache-redis redis-cli -n 3 flushdb

# Clear specific cache patterns
docker exec -it cache-redis redis-cli -n 3 eval "return redis.call('del', unpack(redis.call('keys', ARGV[1])))" 0 "repo:*"

Git Hooks Configuration¶

Gitea supports both server-side and repository-specific Git hooks:

Server-Side Hooks¶

Located in /srv/dockerdata/gitea/hooks/:

1. Post-Receive Hook (`gitea-post-receive.sh`)¶

Triggers after commits are received:

#!/bin/bash
# Sync to GitHub mirror
/srv/dockerdata/_scripts/gitea-github-sync.sh -r "$GITEA_REPO_NAME"

# Send webhook notifications
curl -X POST https://your-ci-system.com/webhook \
  -H "Content-Type: application/json" \
  -d "{\"repository\": \"$GITEA_REPO_NAME\", \"ref\": \"$GITEA_REF\"}"

2. Pre-Push Verification (`pre-push-verify.sh`)¶

Prevents sensitive data from being pushed:

#!/bin/bash
# Check for secrets and credentials
/srv/dockerdata/_scripts/verify-no-secrets.sh "$GIT_DIR"

Repository-Specific Hooks¶

Each repository can have custom hooks in:

/data/git/repositories/{owner}/{repo}.git/hooks/

Installing Hooks¶

Use the provided installation script:

/srv/dockerdata/gitea/hooks/install-hooks.sh

Hook Environment Variables¶

Gitea provides these variables to hooks: - GITEA_REPO_NAME: Full repository name (owner/repo) - GITEA_REPO_USER_NAME: Repository owner - GITEA_PUSHER_NAME: User who pushed - GITEA_REF: Git reference being updated

Sync Workflow Details¶

The Gitea to GitHub sync workflow provides secure, automated mirroring of repositories while filtering out sensitive files from the entire Git history.

How the Sync Works¶

The sync process uses advanced Git history rewriting tools to ensure no sensitive data ever reaches GitHub:

History Filtering: The sync script uses one of three tools (in order of preference):
git-filter-repo (preferred): Modern, fast, and efficient history rewriting
BFG Repo-Cleaner: Java-based tool for removing large files and passwords
git filter-branch (fallback): Native Git tool (deprecated but functional)
Security Verification: After filtering, the verify-no-secrets.sh script scans the repository to ensure no secrets remain
Selective Push: Only configured branches are pushed to GitHub

Configuration¶

Sync configuration in /srv/dockerdata/gitea/sync-config/git-sync-config.yml:

# GitHub organization for syncing
organization: your-github-org

# Repositories to sync
repositories:
  - source: https://gitea.rbnk.uk/admin/myproject.git
    target: myproject
    sync_branches: [main, develop]

# Files to exclude from sync (removed from entire history)
global_exclude_patterns:
  # Environment and configuration files
  - ".env"
  - "*.env"
  - "**/.env*"
  - ".envrc"

  # Private keys and certificates
  - "*.pem"
  - "*.key"
  - "*.pfx"
  - "id_rsa*"
  - "id_dsa*"

  # Cloud credentials
  - ".aws/*"
  - "aws-credentials"
  - "gcp-credentials.json"

  # Database dumps and backups
  - "*.sql"
  - "*.dump"
  - "*.bak"
  - "_backup/*"

  # Secrets and credentials
  - "**/secrets/*"
  - "**/credentials/*"
  - "*password*"
  - "*token*"
  - "*secret*"

Security Features¶

Complete History Filtering: Sensitive files are removed from ALL commits, not just the latest
Pattern Matching: Supports glob patterns and specific file paths
Pre-sync Verification: Automated security scanning before pushing to GitHub
Audit Logging: All sync operations are logged with timestamps

Manual Sync Operations¶

# Sync specific repository (with full history filtering)
/srv/dockerdata/_scripts/gitea-github-sync.sh -r https://gitea.rbnk.uk/user/repo.git

# Dry run (preview what will be synced)
/srv/dockerdata/_scripts/gitea-github-sync.sh -d -r https://gitea.rbnk.uk/user/repo.git

# Verify only (run security checks without syncing)
/srv/dockerdata/_scripts/gitea-github-sync.sh -v -r https://gitea.rbnk.uk/user/repo.git

Automated Sync¶

Sync Schedule: - Hourly sync: Systemd timer runs every hour at :00 - Push notifications: Immediate notification on push to main/master/production branches - Manual trigger: Available for immediate sync when needed

# Check sync timer status and next run time
systemctl status gitea-sync.timer
systemctl list-timers gitea-sync.timer

# View sync logs
journalctl -u gitea-sync.service -f

# Manual trigger (immediate sync)
systemctl start gitea-sync.service

# View detailed sync logs
tail -f /srv/dockerdata/gitea/sync-logs/sync-*.log

Post-receive Hook: When you push to main/master/production branches, you'll see:

==================== GitHub Sync Triggered ====================
Branch: main
Commit: abc12345
Time: 2025-07-27 18:21:55

The hourly sync will pick up this change automatically.
For immediate sync, run: systemctl start gitea-sync.service
===============================================================

Sync Process Flow¶

1. Clone from Gitea (full history)
     ↓
2. Create exclude patterns file from config
     ↓
3. Filter repository history:
   - Remove all instances of sensitive files
   - Clean up Git history completely
   - Update all references
     ↓
4. Run security verification
   - Scan for environment files
   - Check for private keys
   - Look for credential patterns
     ↓
5. Push filtered repository to GitHub
   - Only configured branches
   - Force push if necessary
   - Update tags

Troubleshooting Sync Issues¶

Filter Tool Installation¶

# Install git-filter-repo (recommended)
pip3 install git-filter-repo

# Or download BFG
wget https://repo1.maven.org/maven2/com/madgag/bfg/1.14.0/bfg-1.14.0.jar
sudo mv bfg-1.14.0.jar /usr/local/bin/bfg.jar

Common Issues¶

Large Repository Sync Timeout:

# Increase Git buffer size
git config http.postBuffer 524288000

BFG Memory Issues:

# Run with more memory
java -Xmx4g -jar bfg.jar ...

Verification Failures:
Check sync logs for specific files
Update exclude patterns in config
Run manual verification

Sync Features¶

Selective Sync: Only specified repositories are synced
Complete Security Filtering: Sensitive files removed from entire history
Branch Selection: Choose which branches to mirror
Pre-sync Verification: Automated security checks
Detailed Logging: Comprehensive logs in /srv/dockerdata/gitea/sync-logs/
Flexible Filter Tools: Automatic selection of best available tool
Dry Run Mode: Preview changes before syncing

Backup and Restore Procedures¶

Automated Backups¶

Daily backups via systemd timer (2 AM):

# Check backup status
systemctl status gitea-backup.timer

# Manual backup
/srv/dockerdata/_scripts/gitea-backup.sh

What's Backed Up¶

Database: Full PostgreSQL dump of Gitea database
Repositories: All Git repositories with LFS objects
Configuration: app.ini and custom configurations
User Data: Avatars, attachments, and uploads
SSH Keys: Host keys for consistent access

Backup Locations¶

/srv/backups/gitea/
├── db/
│   └── gitea-dump-20240719.sql.gz
├── data/
│   └── gitea-data-20240719.tar.gz
└── config/
    └── gitea-config-20240719.tar.gz

Restore Process¶

1. Stop Gitea Service¶

docker compose -f /srv/dockerdata/gitea/docker-compose.yml down

2. Restore Database¶

# Drop existing database
docker exec -it supa-db psql -U postgres -c "DROP DATABASE IF EXISTS gitea;"
docker exec -it supa-db psql -U postgres -c "CREATE DATABASE gitea;"

# Restore from backup
gunzip -c /srv/backups/gitea/db/gitea-dump-20240719.sql.gz | \
  docker exec -i supa-db psql -U postgres -d gitea

3. Restore Data¶

# Backup current data
mv /srv/dockerdata/gitea/data /srv/dockerdata/gitea/data.old

# Extract backup
tar -xzf /srv/backups/gitea/data/gitea-data-20240719.tar.gz \
  -C /srv/dockerdata/gitea/

4. Restore Configuration¶

tar -xzf /srv/backups/gitea/config/gitea-config-20240719.tar.gz \
  -C /srv/dockerdata/gitea/

5. Start Gitea¶

docker compose -f /srv/dockerdata/gitea/docker-compose.yml up -d

Disaster Recovery¶

For complete disaster recovery:

Restore VM/Server: Ensure Docker environment is ready
Restore Traefik: Needed for HTTPS access
Restore Supabase: PostgreSQL must be running
Restore Gitea: Follow restore process above
Verify Access: Test web UI and Git operations

Common Operations¶

User Management¶

# Create user via CLI
docker exec -it gitea gitea admin user create \
  --username john \
  --password temp123 \
  --email [email protected]

# Change user password
docker exec -it gitea gitea admin user change-password \
  --username john \
  --password newpass123

# Grant admin privileges
docker exec -it gitea gitea admin user change-admin \
  --username john \
  --admin

Repository Management¶

# List all repositories
docker exec -it gitea gitea admin repo list

# Create repository
docker exec -it gitea gitea admin repo create \
  --owner john \
  --name myproject \
  --private

# Migrate repository from GitHub
curl -X POST https://gitea.rbnk.uk/api/v1/repos/migrate \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "clone_addr": "https://github.com/user/repo.git",
    "repo_name": "migrated-repo",
    "private": true
  }'

Maintenance Tasks¶

# Garbage collection
docker exec -it gitea gitea admin repo gc

# Reindex repositories
docker exec -it gitea gitea admin repo reindex

# Clean up old archives
docker exec -it gitea gitea admin repo clean-archives

# Check repository health
docker exec -it gitea gitea doctor

Monitoring¶

Service Health Monitoring¶

# View access logs
docker logs gitea -f

# Check queue status
docker exec -it gitea gitea admin queue status

# Database connection test
docker exec -it gitea gitea doctor --check db

# API health check
curl -s https://gitea.rbnk.uk/api/v1/version | jq

# Resource usage
docker stats gitea --no-stream

Automated Monitoring¶

Systemd Timer: gitea-monitor.timer runs every 30 minutes

# Check monitoring status
systemctl status gitea-monitor.timer

# View monitoring logs
journalctl -u gitea-monitor.service -f

# Manual health check
/srv/dockerdata/_scripts/gitea-maintenance.sh --health-check

Sync Monitoring¶

Sync Status Tracking:

# Check last sync time
grep "Sync completed" /var/log/gitea-sync.log | tail -1

# Monitor sync errors
tail -f /srv/dockerdata/gitea/sync-logs/sync-$(date +%Y%m%d).log

# Sync statistics
/srv/dockerdata/_scripts/monitor-gitea-sync.sh

Prometheus Metrics¶

Gitea exposes metrics at /metrics endpoint:

# Enable metrics in app.ini
[metrics]
ENABLED = true
TOKEN = your-metrics-token

# Access metrics
curl -H "Authorization: Bearer your-metrics-token" \
  https://gitea.rbnk.uk/metrics

Available Metrics: - gitea_repositories_total: Total number of repositories - gitea_users_total: Total number of users
- gitea_issues_total: Total number of issues - gitea_pulls_total: Total number of pull requests - gitea_http_request_duration_seconds: HTTP request latencies - gitea_process_resident_memory_bytes: Memory usage

Alerting¶

Configure alerts for: - Service downtime (> 1 minute) - Sync failures (> 1 hour without successful sync) - High disk usage (> 90% of allocated space) - Database connection pool exhaustion - Backup failures

Troubleshooting¶

Common Issues¶

1. Cannot Clone via SSH¶

Symptoms: SSH clone fails with permission denied Solution:

# Check SSH service
docker exec -it gitea gitea admin ssh-key list

# Verify SSH port forwarding
ss -tlnp | grep :22

# Test SSH connection
ssh -vT [email protected]

2. Web UI Not Accessible¶

Symptoms: Cannot reach https://gitea.rbnk.uk Solution:

# Check container status
docker ps | grep gitea

# Verify Traefik routing
docker logs traefik | grep gitea

# Test internal connectivity
docker exec -it gitea curl http://localhost:3000

3. Database Connection Failed¶

Symptoms: Gitea shows database error Solution:

# Test database connection
docker exec -it gitea pg_isready -h supa-db -p 5432

# Check database exists
docker exec -it supa-db psql -U postgres -l | grep gitea

# Verify network connectivity
docker exec -it gitea ping supa-db

4. Redis Connection Issues¶

Symptoms: Cache-related errors or session problems Solution:

# Test Redis connectivity
docker exec -it gitea redis-cli -h cache-redis ping

# Check if Redis is accepting connections
docker exec -it cache-redis redis-cli ping

# Verify cache configuration
docker exec -it gitea grep -A 5 '\[cache\]' /data/gitea/conf/app.ini

# Test cache database access
docker exec -it cache-redis redis-cli -n 3 ping

# Test session database access
docker exec -it cache-redis redis-cli -n 1 ping

# Check Redis logs for connection errors
docker logs cache-redis | grep -i error

5. Git Push Rejected¶

Symptoms: Push fails with hook error Solution:

# Check hook logs
tail -f /srv/dockerdata/gitea/data/gitea/log/gitea.log

# Disable problematic hook temporarily
mv /path/to/hook /path/to/hook.disabled

# Debug hook execution
docker exec -it gitea bash -x /path/to/hook

Debug Commands¶

# Container inspection
docker inspect gitea

# Network debugging
docker network inspect traefik_proxy
docker network inspect supabase_internal

# File permissions
docker exec -it gitea ls -la /data/git/repositories/

# Configuration validation
docker exec -it gitea gitea doctor --all

Security Considerations¶

Access Control¶

Authentication Methods:
Local accounts with strong passwords
OAuth2 integration (GitHub, Google, etc.)
LDAP/Active Directory support
Two-factor authentication (TOTP)
Repository Permissions:
Public/Private repository settings
Team-based access control
Branch protection rules
Signed commits enforcement

Security Best Practices¶

Regular Updates:

# Update Gitea image
docker compose pull
docker compose up -d

Secure Configuration:

[security]
INSTALL_LOCK = true
SECRET_KEY = <generate-strong-key>
INTERNAL_TOKEN = <generate-strong-token>

[service]
DISABLE_REGISTRATION = true
REQUIRE_SIGNIN_VIEW = true

Network Security:
Use HTTPS only (enforced by Traefik)
Restrict SSH access with fail2ban
Implement IP whitelisting if needed
Audit Logging:
Enable comprehensive logging
Monitor for suspicious activities
Regular security audits

Sensitive Data Protection¶

Git Hooks: Pre-receive hooks scan for secrets
Sync Filtering: Excludes sensitive files from GitHub mirror
Access Logs: Monitor and alert on unusual access patterns
Backup Encryption: Consider encrypting backups at rest

Performance Optimization¶

Database Tuning¶

-- Add indexes for common queries
CREATE INDEX idx_repository_owner ON repository(owner_id);
CREATE INDEX idx_issue_repo ON issue(repo_id);

-- Analyze tables regularly
ANALYZE;

Caching Configuration¶

With Redis integration, caching is significantly improved:

[cache]
ENABLED = true
ADAPTER = redis
HOST = cache-redis:6379
DB = 3
INTERVAL = 60
TTL = 3600

[session]
PROVIDER = redis
PROVIDER_CONFIG = cache-redis:6379/1
COOKIE_SECURE = true

Performance Benefits: - Persistent Cache: Survives container restarts - Shared Cache: Multiple Gitea instances can share cache - Better Memory Management: Redis handles memory more efficiently - Configurable TTL: Fine-tune cache expiration

Resource Limits¶

# In docker-compose.yml
services:
  gitea:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          cpus: '0.5'
          memory: 512M

Integration Examples¶

CI/CD Webhook¶

{
  "url": "https://ci.example.com/gitea-webhook",
  "content_type": "json",
  "secret": "webhook-secret",
  "events": ["push", "pull_request"]
}

API Usage Examples¶

# Python example using requests
import requests

headers = {
    "Authorization": "token YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}

# Create repository
repo_data = {
    "name": "new-project",
    "private": True,
    "description": "My new project"
}

response = requests.post(
    "https://gitea.rbnk.uk/api/v1/user/repos",
    headers=headers,
    json=repo_data
)

Conclusion¶

Gitea provides a robust, self-hosted Git service that integrates seamlessly with the existing infrastructure. Key benefits include:

Full Control: Complete ownership of source code and data
PostgreSQL Integration: Leverages existing Supabase database
Redis Integration: Enhanced performance with caching and persistent sessions
Security: Advanced hooks and filtering for sensitive data
Flexibility: Supports both private development and public mirroring
Performance: Lightweight and efficient for small to medium teams with Redis acceleration

The dual-remote workflow with GitHub sync enables the best of both worlds: private development with optional public collaboration. Redis integration ensures fast, responsive user experience with persistent sessions and intelligent caching.

Gitea Self-Hosted Git Service Documentation¶

Table of Contents¶

Overview¶

Architecture¶

Container Configuration¶

Storage Structure¶

Network Architecture¶

Access Information¶

Web Interface¶

SSH Access¶

HTTPS Access¶

Git Remote Configuration¶

Development Workflow Setup¶

API Access¶

Integration with Supabase PostgreSQL¶

Database Configuration¶

Database Schema¶

Database Operations¶

Redis Integration¶

Redis Configuration¶

Performance Benefits¶

Redis Database Assignment¶

Monitoring Redis Integration¶

Cache Performance Metrics¶

Redis Troubleshooting¶

1. Cache Connection Failed¶

2. Session Loss Issues¶

3. High Memory Usage¶

4. Performance Issues¶

Cache Invalidation¶

Git Hooks Configuration¶

Server-Side Hooks¶

1. Post-Receive Hook (gitea-post-receive.sh)¶

2. Pre-Push Verification (pre-push-verify.sh)¶

Repository-Specific Hooks¶

Installing Hooks¶

Hook Environment Variables¶

Sync Workflow Details¶

How the Sync Works¶

Configuration¶

Security Features¶

Manual Sync Operations¶

Automated Sync¶

Sync Process Flow¶

Troubleshooting Sync Issues¶

Filter Tool Installation¶

Common Issues¶

Sync Features¶

Backup and Restore Procedures¶

Automated Backups¶

What's Backed Up¶

Backup Locations¶

Restore Process¶

1. Stop Gitea Service¶

2. Restore Database¶

3. Restore Data¶

4. Restore Configuration¶

5. Start Gitea¶

Disaster Recovery¶

Common Operations¶

User Management¶

Repository Management¶

Maintenance Tasks¶

Monitoring¶

Service Health Monitoring¶

Automated Monitoring¶

Sync Monitoring¶

Prometheus Metrics¶

Alerting¶

Troubleshooting¶

Common Issues¶

1. Cannot Clone via SSH¶

2. Web UI Not Accessible¶

3. Database Connection Failed¶

4. Redis Connection Issues¶

5. Git Push Rejected¶

Debug Commands¶

Security Considerations¶

Access Control¶

Security Best Practices¶

1. Post-Receive Hook (`gitea-post-receive.sh`)¶

2. Pre-Push Verification (`pre-push-verify.sh`)¶