Prerequisites Before building Gitea, ensure you have the following installed:
Required
Go : Version 1.26.1 or later (as specified in go.mod)Node.js : Version 22.6.0 or laterpnpm : Version 10.0.0 or laterGit : For cloning the repositoryMake : Build automation
Optional
Docker : For building Docker imagesSQLite3 : If building with SQLite support
Installation Install Go from go.dev/dl # Verify installation go version # Should output: go version go1.26.1 or later
Install Node.js from nodejs.org # Verify Node.js installation node --version # Should output: v22.6.0 or later # Install pnpm globally npm install -g pnpm # Verify pnpm installation pnpm --version # Should output: 10.0.0 or later
Clone the Repository # Clone Gitea repository git clone https://github.com/go-gitea/gitea.git cd gitea
Building Gitea Basic Build Build Gitea with embedded assets:
TAGS = "bindata" make build
This creates a gitea binary in the root directory.
Build with SQLite Support To include SQLite database support:
TAGS = "bindata sqlite sqlite_unlock_notify" make build
SQLite support requires CGO to be enabled and SQLite3 development headers installed.
Build Targets The build process is split into two main targets:
Build only the Go backend: Requirements : Go 1.26.1+Build only the frontend assets: Requirements : Node.js 22.6.0+ and pnpm 10.0.0+Common build tags:
Tag Description bindataEmbed static assets into binary sqliteEnable SQLite database support sqlite_unlock_notifyEnable SQLite unlock notifications pamEnable PAM authentication gogitUse pure Go git implementation
Example with multiple tags: TAGS = "bindata sqlite sqlite_unlock_notify pam" make build
Development Build For development with live reloading:
# Install dependencies make deps-frontend make deps-backend # Run in development mode make watch-frontend & # Watch and rebuild frontend make watch-backend # Watch and rebuild backend
Or use Air for automatic reloading:
# Install air go install github.com/cosmtrek/air@latest # Run with air air -c .air.toml
Building for Production Optimized Build # Clean previous builds make clean # Build optimized binary TAGS = "bindata" make build # Strip debug symbols for smaller binary strip gitea
Cross-Compilation Build for different platforms:
GOOS = linux GOARCH = arm64 TAGS = "bindata" make build
Building Docker Images Standard Docker Image # Build Docker image make docker # Or use docker-compose docker build -t gitea:latest .
Rootless Docker Image docker build -f Dockerfile.rootless -t gitea:rootless .
Makefile Targets Common make targets:
# Show all available targets make help # Build targets make build # Build complete Gitea binary make backend # Build backend only make frontend # Build frontend only # Development make watch-frontend # Watch and rebuild frontend make watch-backend # Watch and rebuild backend # Testing make test # Run all tests make test-sqlite # Run tests with SQLite # Code quality make fmt # Format Go code make lint-go # Lint Go code make lint-js # Lint JavaScript/TypeScript make tidy # Tidy go.mod # Cleanup make clean # Remove build artifacts
Configuration Development Configuration Create a custom configuration for development:
# Create custom config directory mkdir -p custom/conf # Create app.ini cat > custom/conf/app.ini << EOF APP_NAME = Gitea: Git with a cup of tea (Dev) RUN_MODE = dev [server] HTTP_PORT = 3000 ROOT_URL = http://localhost:3000/ [database] DB_TYPE = sqlite3 PATH = data/gitea.db [log] ROOT_PATH = log MODE = console LEVEL = Debug EOF
Running the Development Build # Run Gitea ./gitea web # Or with custom config ./gitea web -c custom/conf/app.ini
Troubleshooting
Build fails with 'cannot find package'
Run make deps-backend to download Go dependencies: make deps-backend go mod download
Ensure you’re using the correct Node.js and pnpm versions: node --version # Should be >= 22.6.0 pnpm --version # Should be >= 10.0.0 # Clean and reinstall rm -rf node_modules pnpm install
Install SQLite3 development headers: sudo apt-get install libsqlite3-dev
Use make backend instead of full build during development
Enable build cache: GOCACHE=$(go env GOCACHE)
Use faster linker: go build -ldflags='-s -w'
See Also Contributing Learn how to contribute to Gitea
Testing Run tests and write new tests
Architecture Understand Gitea’s codebase structure
Installation Install pre-built Gitea binaries
