Skip to content
Get packs

Guide · Open source

How to use Gitea: install, run and get started

Updated · written with AI from the project's own documentation and checked against our catalogue data

Gitea is a self-hosted, all-in-one software development service that bundles Git hosting, code review, issue tracking, a wiki, a package registry and CI/CD. This guide is for teams and individuals who want to run their own Git server instead of using a public cloud service. After reading it, you will know what Gitea covers, how to get it running from the source, where its configuration lives, and what to check before you rely on it.

Giteago-gitea/gitea · ★ 58.8k · MIT

Quick start

  1. 1Read the docs first. Open docs.gitea.com and the build guides in the repository to confirm what you need before installing.
  2. 2Clone the repository. Run the git clone command for the go-gitea/gitea repository to get the source code.
  3. 3Build Gitea. Follow docs/build-source.md to build the binary, or choose the official container image.
  4. 4Start the server. Run ./gitea web from the build directory to start the web server.
  5. 5Open the admin panel. Use the admin panel's configuration section to change dynamic settings.
  6. 6Edit app.ini for static settings. Change static options in app.ini using app.example.ini as a reference, then restart the instance.
  7. 7Plan updates. Subscribe to release notes and security advisories so you can apply patches yourself.

What does Gitea include?

Gitea is meant to be a single tool for work that is often split across several products. According to the project's README, it covers Git hosting, code management, code review, issue tracking, project kanban, wiki, team collaboration, package registry and CI/CD that can reuse GitHub Actions.

Because Gitea is written in Go, the README says it works on all platforms and architectures that Go supports, including Linux, macOS, FreeBSD/OpenBSD and Windows.

  • Git hosting and code management
  • Code review and pull requests
  • Issue tracking, milestones and project kanban
  • Wiki and team collaboration
  • Package registry
  • CI/CD that can reuse GitHub Actions

Install Gitea from the source repository

The source gives one install-related command: cloning the repository from GitHub. The README points to separate documents for build prerequisites and building from source, so check those before you compile.

Gitea's own quick start on the project README is limited, so for installation details the README directs you to the official documentation website at docs.gitea.com.

  • Read docs/build-setup.md for build prerequisites.
  • Read docs/build-source.md if you want to build from source or make a distribution package.
  • Use the official documentation at docs.gitea.com for installation guides.
git clone https://github.com/go-gitea/gitea

Run the Gitea server

After building, the README says you can start the server with the web command. To see every available command, run the help command.

If you prefer containers, the README mentions an official Docker image hosted on Docker Hub, which can be run with Docker, Podman or similar tools on your own server.

  • Start the server with the web subcommand.
  • List all available commands with the help subcommand.
  • Container option: the official image at hub.docker.com/r/gitea/gitea.
./gitea web

Configure your instance

Gitea has two kinds of configuration. Dynamic options can be changed in the admin panel's configuration section. Static options live in an app.ini file, and you need to restart the instance after editing it.

The project provides app.example.ini and a configuration cheat sheet in the documentation to help you set the static options.

  • Dynamic options: change them in the admin panel's configuration section.
  • Static options: edit the app.ini file, then restart the instance.
  • Reference: app.example.ini in the repository and the config cheat sheet at docs.gitea.com.

Keep your instance secure and up to date

Because you host Gitea yourself, security patches are your responsibility. The README says to check the release notes and security advisories on GitHub for patches.

The README also asks anyone who finds a vulnerability to write privately to security@gitea.io rather than opening a public issue.

  • Watch the release notes on the GitHub releases page.
  • Check the GitHub security advisories for the project.
  • Report vulnerabilities privately to security@gitea.io.

Get help and find extensions

For questions the documentation does not answer, the README lists a Discord server and a discourse forum. The project also publishes an official Go SDK, a CLI tool called tea, and an action runner for Gitea Actions.

A curated list of third-party Gitea projects, including SDKs, plugins and themes, is kept in the gitea/awesome-gitea repository.

  • Community chat: Discord server linked in the README.
  • Forum: the discourse forum linked in the README.
  • Official tools: go-sdk, the tea CLI and the Gitea Actions runner.
  • Third-party projects: gitea/awesome-gitea.

What people use it for

  • A small team hosting private repositories on its own server instead of a public cloud service.
  • A developer running a private Git server on a personal machine.
  • Running code review, issue tracking and a wiki in one tool for a small organization.
  • Running CI/CD pipelines that reuse GitHub Actions workflows on self-hosted infrastructure.
  • Hosting a private package registry alongside the repositories that produce the packages.

Frequently asked questions

Is Gitea free?

Gitea is released under the MIT License, as stated in the README, and the full text is in the LICENSE file in the repository. The README also mentions a free hosted service at gitea.com with a limited number of repositories, and a Gitea Cloud free trial.

How do I install Gitea?

The README gives the command git clone https://github.com/go-gitea/gitea to get the source. It then points to docs/build-source.md for building and to docs.gitea.com for installation guides. You can also use the official Docker image.

What are the requirements for Gitea?

The source does not list specific prerequisites for running Gitea. It says the software works on platforms and architectures that Go supports, and that build prerequisites are described in docs/build-setup.md.

How do I configure Gitea?

Dynamic settings can be changed in the admin panel's configuration section. Static settings are in the app.ini file, and you must restart the instance after editing it. The app.example.ini file and the configuration cheat sheet describe the options.

Is Gitea a good alternative to GitLab or Forgejo?

Gitea is one of several comparable self-hosted projects, alongside GitLab, Forgejo, Gogs and Bitbucket Server. Gitea aims to be a lightweight, all-in-one option, but the source does not compare performance or features in detail, so test the options against your own needs.

Where do I find security patches for Gitea?

Check the release notes and the security advisories on the project's GitHub page. The README notes that you, as the operator, must apply these patches yourself.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Gitea suits teams and developers who want to host their own Git, reviews, issues and CI/CD in one tool, and who have someone comfortable running a server and applying updates. If you only need a personal repository or have no one to maintain a server, a hosted service is the simpler choice.

Install options & downloads