Master Gitea: Your Comprehensive Guide to Self-Hosted Git Management

Introduction

Gitea is an open-source self-hosted Git service that provides a lightweight and user-friendly alternative to larger platforms like GitHub and GitLab. For sysadmins and developers, understanding Gitea is essential as it offers full control over your repositories, reduces reliance on third-party services, enhances privacy, and can be customized to meet specific project needs. With its intuitive interface and robust features, Gitea is suitable for both small teams and large organizations aiming to manage their source code efficiently.

What Is Gitea?

Gitea is a self-hosted Git service that enables users to create, manage, and collaborate on Git repositories. It is designed to be lightweight and easy to install, making it accessible for developers of all skill levels. Gitea allows you to maintain your own instance of a Git repository hosting service, giving you control over your data and the ability to tailor the platform to your workflow.

How It Works

Gitea functions as a web application that simplifies the management of Git repositories. Here are some core concepts:

Repositories: The fundamental unit in Gitea, a repository stores all the files, commit history, and branches for a project.
Organizations and Teams: Users can organize repositories into groups, allowing for collaborative work among multiple users or departments while managing permissions through teams.
Pull Requests: Gitea supports pull requests, which enable developers to propose code changes and facilitate review and discussion before integration.
Webhooks: Gitea can trigger automated actions in response to events like code pushes or pull requests, seamlessly integrating with CI/CD processes.

Prerequisites

Before installing Gitea, ensure that you have the following:

A 64-bit operating system
git installed
A database system such as SQLite, MySQL, or PostgreSQL
Sufficient permissions to install software and manage services

Installation & Setup

Follow these steps to install Gitea on your server:

Step 1: System Requirements

Ensure your system meets the following requirements:

64-bit operating system
git installed
SQLite or MySQL/PostgreSQL for the database

Step 2: Install Dependencies

Update your package list and install Git:

sudo apt update
sudo apt install -y git

Step 3: Download Gitea Binary

Download the latest Gitea binary from the official releases page. For Ubuntu, use the following command:

wget https://dl.gitea.io/gitea/<version>/gitea-<version>-linux-amd64 -O gitea
chmod +x gitea

Replace <version> with the latest version number available.

Step 4: Create a User and Directories

Create a dedicated user for Gitea and set up necessary directories:

sudo adduser --system --shell /bin/bash --gecos 'Gitea' --group --disabled-password git
sudo mkdir -p /var/lib/gitea/{custom,data,indexers,repos}
sudo chown -R git:git /var/lib/gitea/
sudo chmod -R 750 /var/lib/gitea/

Step 5: Configure Gitea

Create a service file for Gitea:

sudo nano /etc/systemd/system/gitea.service

Add the following configuration:

[Unit]
Description=Gitea
After=syslog.target

[Service]
User=git
Group=git
WorkingDirectory=/var/lib/gitea
ExecStart=/var/lib/gitea/gitea web
Restart=always
Environment=USER=git HOME=/var/lib/gitea

[Install]
WantedBy=multi-user.target

Step 6: Start Gitea

Start the Gitea service and enable it to run on boot:

sudo systemctl start gitea
sudo systemctl enable gitea

You can now access Gitea via http://your-server-ip:3000.

Step-by-Step Guide

Install Dependencies: Ensure git is installed.
```
sudo apt update
sudo apt install -y git
```

Download Gitea: Fetch the Gitea binary.

wget https://dl.gitea.io/gitea/<version>/gitea-<version>-linux-amd64 -O gitea
chmod +x gitea

Create User and Directories: Set up a user and necessary directories.

sudo adduser --system --shell /bin/bash --gecos 'Gitea' --group --disabled-password git
sudo mkdir -p /var/lib/gitea/{custom,data,indexers,repos}
sudo chown -R git:git /var/lib/gitea/
sudo chmod -R 750 /var/lib/gitea/

Configure Gitea: Create a service file.
```
sudo nano /etc/systemd/system/gitea.service
```
(Add the service configuration as described above.)

Start Gitea: Launch and enable the service.

sudo systemctl start gitea
sudo systemctl enable gitea

Real-World Examples

Creating a Repository

Log in to your Gitea instance.
Navigate to the dashboard and click on "New Repository."
Fill in the repository details and click "Create Repository."

Setting Up Webhooks

To integrate Gitea with a CI/CD tool:

Go to your repository settings.
Select "Webhooks" and click "Add Webhook."
Enter the payload URL and choose the events to trigger the webhook.

Managing Teams

Navigate to your organization settings.
Click on "Teams" and then "New Team."
Assign repositories and manage permissions for team members.

Best Practices

Regularly back up your Gitea data and configuration.
Use HTTPS for secure communication with your Gitea server.
Monitor resource usage to ensure optimal performance.
Keep Gitea updated to benefit from the latest features and security patches.
Implement role-based access control for sensitive repositories.
Use webhooks to automate CI/CD workflows effectively.
Document your repository structure and team roles for better collaboration.

Common Issues & Fixes

Issue	Cause	Fix
Gitea won't start	Incorrect service configuration	Check `/etc/systemd/system/gitea.service` for errors
Database connection error	Misconfigured database settings	Verify database connection details in Gitea config
Permission denied	Incorrect directory permissions	Ensure `/var/lib/gitea/` is owned by the `git` user
404 error on access	Gitea not running or wrong URL	Confirm Gitea service is active and check the URL

Key Takeaways

Gitea is a lightweight, self-hosted Git service ideal for managing repositories.
It supports key features like organizations, teams, pull requests, and webhooks.
Installation requires a 64-bit OS, Git, and a database setup.
Follow structured steps for installation, configuration, and starting the service.
Best practices include regular backups, secure communication, and keeping the software updated.