What is Gitea?#
Gitea is an open-source, lightweight software package for hosting Git repositories. It is designed to be a self-hosted alternative to platforms like GitHub or GitLab, providing a web interface for managing code, tracking issues, and collaborating with others.
One of its most defining characteristics is its efficiency; it is written in Go and can run on very low-powered hardware, including a Raspberry Pi or a basic NAS.
Core Features#
Repository Management: Gitea provides a familiar interface for managing your code. You can create public or private repositories, manage branches, and view commit histories. It supports Git LFS (Large File Storage) for handling big binary files.
Collaboration Tools:
- Pull Requests: Facilitate code reviews and discussions before merging changes.
- Issue Tracking: A built-in system to report bugs, suggest features, and organize tasks with labels and milestones.
- Wikis: Every repository can have its own dedicated wiki for documentation.
- Kanban Boards: Visual project management tools to track the progress of issues.
Gitea Actions (CI/CD): Recent versions of Gitea include Actions, a built-in continuous integration and delivery system. It is designed to be compatible with GitHub Actions syntax, allowing you to automate testing and deployment workflows directly within your instance.
User and Organization Management: You can manage multiple users, organize them into teams, and set granular permissions for different repositories. It also supports various authentication methods, including OAuth2, LDAP, and PAM.
Technical Advantages#
| Feature | Description |
|---|---|
| Low Resource Usage | Runs comfortably with minimal RAM and CPU overhead. |
| Cross-Platform | Can be installed on Linux, macOS, Windows, and ARM architectures. |
| Simple Deployment | Usually distributed as a single binary or a Docker image, making setup and updates straightforward. |
| Database Support | Compatible with PostgreSQL, MySQL, MSSQL, and SQLite. |
Why Choose Gitea?#
Gitea is often the preferred choice for developers who want full control over their source code without the resource heavy-lifting required by GitLab. It is ideal for:
- Home Labs: Perfect for personal projects and self-hosting enthusiasts.
- Small Teams: Provides all the professional tools needed for collaboration without expensive licensing.
- Internal Corporate Use: Keeps sensitive codebases behind a private firewall.
If you are looking for a “no-nonsense” Git hosting solution that feels like GitHub but lives on your own hardware, Gitea is generally the top recommendation.
Docker Compose Example#
################################################################################
# gitea -- https://docs.gitea.com/installation/install-with-docker
################################################################################
networks:
gitea_net:
driver: bridge
services:
# --- Gitea ---
server:
image: docker.gitea.com/gitea:1.25.4
container_name: gitea
environment:
- USER_UID=1000
- USER_GID=1000
- GITEA__database__DB_TYPE=postgres
- GITEA__database__HOST=db:5432
- GITEA__database__NAME=gitea
- GITEA__database__USER=gitea
- GITEA__database__PASSWD=gitea
restart: always
networks:
- gitea_net
volumes:
- "${GITEA_HOME}/data:/data"
- "/etc/timezone:/etc/timezone:ro"
- "/etc/localtime:/etc/localtime:ro"
ports:
- "3001:3000"
- "222:22"
depends_on:
- db
# --- Gitea postgres db ---
db:
image: docker.io/library/postgres:14
restart: always
environment:
- POSTGRES_USER=gitea
- POSTGRES_PASSWORD=gitea
- POSTGRES_DB=gitea
networks:
- gitea_net
volumes:
- "${GITEA_HOME}/postgres:/var/lib/postgresql/data"
# --- Gitea Actions Runner ---
runner:
image: gitea/act_runner:latest
container_name: gitea_runner
restart: always
environment:
- GITEA_INSTANCE_URL=https://git.wompmacho.com
- GITEA_RUNNER_REGISTRATION_TOKEN=${GITEA_RUNNER_TOKEN}
- GITEA_RUNNER_NAME=gitea-runner-01
- CONFIG_FILE=/data/config.yaml
volumes:
- "${GITEA_HOME}/runner:/data"
- "/srv/www:/deploy"
- "/srv/configs:/assets"
- "/var/run/docker.sock:/var/run/docker.sock"
networks:
- gitea_net
depends_on:
- server
# --- Nginx Web Server (Public) ---
docs-public:
image: nginx:alpine
container_name: docs-public
restart: always
ports:
- "9895:80"
volumes:
- "/srv/www/docs-public:/usr/share/nginx/html:ro"
networks:
- gitea_net
# --- Nginx Web Server (Private) ---
docs-private:
image: nginx:alpine
container_name: docs-private
restart: always
ports:
- "9897:80"
volumes:
- "/srv/www/docs-private:/usr/share/nginx/html:ro"
networks:
- gitea_netsetup#
todo
runners / gitea actions#
todo