gitea

Run the Gitea web server using the default configuration

$ gitea web

$ gitea migrate

$ gitea admin [user list]

$ gitea [admin] --help

$ gitea help

$ gitea --version

gitea [global options] command [command options] [arguments...]
Example: gitea web --config /etc/gitea/app.ini

web
    Starts the Gitea web server. This is the primary command to run Gitea as a service.

migrate
    Performs database schema or data migrations. Essential after upgrading Gitea to a new version.

admin
    Provides various administrative functionalities, such as creating new users, changing passwords, or managing repositories.

doctor
    Performs a health check on the Gitea instance, verifying database, configuration, and other critical components.

keys
    Manages SSH and GPG keys associated with users and repositories within Gitea.

cert
    Manages SSL certificates for the Gitea instance, primarily for self-signed certificates.

dump
    Creates a backup dump of the Gitea data, including the database, repositories, and attachments.

restore
    Restores a Gitea instance from a previously created dump file.

help [command]
    Displays help information for the gitea command or a specific subcommand.

-v, --version
    Prints the current Gitea version and exits.

--config <path>
    (Global option) Specifies the path to the Gitea configuration file (usually app.ini).

--custom-path <path>
    (Global option) Specifies the path to custom files such as templates, options, or static assets.

Gitea is a community-managed, lightweight, and fast-growing open-source code hosting solution written in Go. The gitea command-line interface provides tools to manage and interact with a Gitea instance. This includes starting the web server, performing database migrations, managing administrative tasks like creating users or repositories, checking system health, and various other utilities. It's designed to be a self-contained binary, making deployment simple and efficient. It supports various databases like SQLite, MySQL, PostgreSQL, and MSSQL, and runs on multiple platforms, offering a robust and easy-to-maintain alternative to larger Git platforms for personal or small to medium-sized team use. Its ease of installation and low resource footprint make it a popular choice for self-hosting.

Requires proper configuration in its app.ini file for full functionality and security, especially regarding database connections and server settings.
Running gitea web directly in the foreground is generally not recommended for production environments; it should typically be managed by a service manager like systemd.
Correct file system and database permissions are crucial for Gitea's operation, as misconfigurations can lead to data loss or security vulnerabilities.

Gitea's behavior is primarily controlled by its app.ini configuration file. This file specifies crucial settings such as database connections, repository root paths, server listen addresses, authentication options, and various feature toggles. Understanding and properly configuring this file is essential for a secure, performant, and functional Gitea instance. The command-line options often allow overriding or specifying the location of this file.

While gitea web starts the server, for production environments, it is highly recommended to deploy Gitea as a system service (e.g., using systemd for automatic startup and management) and to place it behind a reverse proxy like Nginx or Apache. A reverse proxy handles SSL termination, allows for hosting multiple web services on the same port, and can provide additional security features.

Gitea is highly extensible, supporting webhooks for integration with CI/CD pipelines and other external services. It also offers comprehensive support for OAuth2 authentication and provides a rich RESTful API, allowing programmatic interaction with its features for automation and custom integrations.

Gitea was forked from Gogs (Go Git Service) in late 2016 due to disagreements within the Gogs community regarding its development model and responsiveness. The Gitea project aimed for a more community-driven and transparent development process. Since its inception, Gitea has rapidly gained popularity as a lightweight, self-hostable alternative to larger Git platforms like GitLab and GitHub, focusing on ease of use, low resource consumption, and a robust feature set, making it suitable for personal projects, small teams, and even larger organizations looking for a self-managed Git solution.

git(1), systemctl(1), nginx(8), apache2(8), mariadb(1), postgresql(1)