Building from Source

Build Gitea from source code for development and customization

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 later
• pnpm: Version 10.0.0 or later
• Git: For cloning the repository
• Make: Build automation

Optional

• Docker: For building Docker images
• SQLite3: If building with SQLite support

Installation

Go

Install Go from go.dev/dl

# Verify installation
go version
# Should output: go version go1.26.1 or later

Node.js & pnpm

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:

Backend

Build only the Go backend:

make backend

Requirements: Go 1.26.1+

Frontend

Build only the frontend assets:

make frontend

Requirements: Node.js 22.6.0+ and pnpm 10.0.0+

Build Tags

Common build tags:

Tag	Description
bindata	Embed static assets into binary
sqlite	Enable SQLite database support
sqlite_unlock_notify	Enable SQLite unlock notifications
pam	Enable PAM authentication
gogit	Use 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:

Linux ARM64

GOOS=linux GOARCH=arm64 TAGS="bindata" make build

GOOS=darwin GOARCH=amd64 TAGS="bindata" make build

GOOS=windows GOARCH=amd64 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

Frontend build fails

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

SQLite build fails

Install SQLite3 development headers:

Ubuntu/Debian

sudo apt-get install libsqlite3-dev

brew install sqlite3

sudo dnf install sqlite-devel

Build is very slow

• 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