Skip to main content

​
Overview

Gitea is a full-stack web application built with Go on the backend and Vue.js on the frontend. It follows a modular, layered architecture that separates concerns and enables maintainability.

​
Technology Stack

Backend

  • Language: Go 1.26+
  • Web Framework: Chi router
  • ORM: XORM
  • Template Engine: Go templates

Frontend

  • Framework: Vue.js 3.5+
  • Build Tool: Webpack 5
  • Language: TypeScript
  • Styling: CSS with Tailwind

Database

  • PostgreSQL (recommended)
  • MySQL / MariaDB
  • SQLite3
  • MSSQL

Storage

  • Local filesystem
  • S3-compatible (MinIO, AWS S3)
  • Azure Blob Storage

​
Directory Structure

gitea/
├── cmd/                  # Command-line interface
│   ├── web.go           # Web server command
│   ├── admin.go         # Admin commands
│   └── ...
├── models/              # Database models and schemas
│   ├── user/            # User models
│   ├── repo/            # Repository models
│   ├── issues/          # Issue/PR models
│   └── ...
├── modules/             # Shared utility modules
│   ├── git/             # Git operations
│   ├── auth/            # Authentication
│   ├── setting/         # Configuration
│   └── ...
├── routers/             # HTTP request routing
│   ├── web/             # Web UI routes
│   ├── api/             # API routes
│   └── ...
├── services/            # Business logic layer
│   ├── repository/      # Repository services
│   ├── user/            # User services
│   ├── issue/           # Issue services
│   └── ...
├── templates/           # HTML templates
│   ├── repo/            # Repository pages
│   ├── user/            # User pages
│   └── ...
├── web_src/             # Frontend source code
│   ├── js/              # JavaScript/TypeScript
│   ├── css/             # Stylesheets
│   └── ...
├── public/              # Static assets (compiled)
├── options/             # Configuration templates
└── tests/               # Test suites

​
Layered Architecture

Gitea follows a clean architecture with clear separation of concerns:

​
Layer Responsibilities

1

Routers Layer

Location: routers/web/, routers/api/
  • Handle HTTP requests/responses
  • Parse request parameters
  • Validate input
  • Call service layer
  • Render responses (HTML or JSON)
// Example router handler
func CreateRepository(ctx *context.Context) {
    form := web.GetForm(ctx).(*forms.CreateRepoForm)
    repo, err := repo_service.CreateRepository(ctx, ctx.Doer, form.ToCreateRepoOption())
    if err != nil {
        ctx.Error(http.StatusInternalServerError)
        return
    }
    ctx.JSON(http.StatusCreated, convert.ToRepo(repo, permission.AccessModeOwner))
}
2

Services Layer

Location: services/
  • Implement business logic
  • Orchestrate multiple operations
  • Handle transactions
  • Emit notifications/webhooks
// Example service function
func CreateRepository(ctx context.Context, doer *user_model.User, opts CreateRepoOptions) (*repo_model.Repository, error) {
    // Validate
    // Create repository record
    // Initialize git repository
    // Set up default branch
    // Trigger webhooks
    return repo, nil
}
3

Models Layer

Location: models/
  • Define data structures
  • Database operations (CRUD)
  • Query builders
  • Migrations
// Example model
type Repository struct {
    ID          int64
    OwnerID     int64
    Name        string
    Description string
    IsPrivate   bool
    CreatedUnix timeutil.TimeStamp
}

func GetRepositoryByID(ctx context.Context, id int64) (*Repository, error) {
    repo := new(Repository)
    has, err := db.GetEngine(ctx).ID(id).Get(repo)
    if !has {
        return nil, ErrRepoNotExist{ID: id}
    }
    return repo, err
}
4

Modules Layer

Location: modules/
  • Utility functions
  • External integrations
  • Git operations
  • Authentication providers

​
Key Components

​
Git Integration

Gitea interacts with Git repositories through:
  • Native Git: Executes git commands via modules/git/
  • Git LFS: Large file storage support
  • Git Hooks: Server-side and client-side hooks

​
Authentication System

Multiple authentication backends: 
// modules/auth/
- LDAP (Bind DN and Simple Auth)
- OAuth2 (GitHub, GitLab, Google, etc.)
- SMTP
- PAM
- SSPI (Windows)

​
Database Abstraction

XORM provides database-agnostic queries: 
// Works across PostgreSQL, MySQL, SQLite, MSSQL
repos, err := db.Find(ctx, FindRepoOptions{
    OwnerID: userID,
    Private: false,
    Page:    1,
    PageSize: 20,
})

​
Queue System

Asynchronous task processing: 
// Background jobs
- Email notifications
- Webhook deliveries
- Repository mirroring
- Git garbage collection

​
Request Flow

​
Web Request Example

1. User visits /user/repo/issues/new
   ↓
2. Chi router matches route → routers/web/repo/issue.go
   ↓
3. Handler validates permissions (middleware)
   ↓
4. Handler calls services/issue/Create()
   ↓
5. Service creates issue in database (models/issues/)
   ↓
6. Service triggers notifications and webhooks
   ↓
7. Handler renders HTML template (templates/repo/issue/new.tmpl)
   ↓
8. Response sent to user

​
API Request Example

1. POST /api/v1/repos/:owner/:repo/issues
   ↓
2. API router → routers/api/v1/repo/issue.go
   ↓
3. Authenticate token (middleware)
   ↓
4. Parse JSON request body
   ↓
5. Call services/issue/Create()
   ↓
6. Return JSON response

​
Database Schema

Core database tables: 
-- Users and authentication
user, email_address, access_token, oauth2_application

-- Repositories
repository, release, branch, protected_branch

-- Collaboration
issue, pull_request, comment, review, milestone, label

-- Organizations
org_user, team, team_user, team_repo

-- Actions (CI/CD)
action_run, action_run_job, action_runner

-- Packages
package, package_version, package_file

​
Middleware

Request middleware pipeline: 
// Common middleware
- Context initialization
- Session management
- CSRF protection
- Authentication
- Permission checks
- Rate limiting
- Logging

​
See Also

Database Layer

Deep dive into database architecture

Frontend

Frontend architecture and build system

Contributing

Learn how to contribute

Building

Build Gitea from source