Jesse Laprade

Setting up a Git forge with Gitea

This page guides you through setting up a Git forge using Gitea.

Page overview


Most of the documentation found here was referenced from Gitea’s documentation.

Reasoning for this guide

As someone who is learning how to maintain servers and online services, I had a bit of trouble following the documentation, because the documentation for setting up Gitea wasn’t as linear as I was used to. I found myself jumping back and forth between the navigation sidebar, so I decided to create a more linear set of instructions for setting up Gitea for other people who had trouble with setting up Gitea.

Page conventions


This guide assumes:


Preparing your system

Before using Gitea, you need to prepare DNS records and create a git user.

This section consists of the following topics:

Setting up DNS records on DigitalOcean

Setting up DNS records for a allows you to redirect users back to your server, so nginx can redirect users to specific paths or ports on your server.

To setup DNS records on DigitalOcean
  1. Add an A record for to your DigitalOcean droplet
  2. Add an AAAA record for to your DigitalOcean droplet

Creating a git user

Creating a git user allows you to run Gitea as a different user from root. This is a safer option, especially if you intend to push to your repositories using SSH or have multiple users on your Gitea instance.

To create a git user
  1. Run the following command:

    sudo adduser \
      --system \
      --shell /bin/bash \
      --gecos 'Git Version Control' \
      --group \
      --disabled-password \
      --home /home/git \

Source: Gitea’s Prepare environment section.

Adding the git user to your SSH server’s AllowedUsers list

Pushing Git commits over SSH is convenient because you don’t need to enter a username and password like you would over HTTPS. You need to add the git user to your SSH server’s AllowedUsers list to use Git over SSH.

To add the git user to your SSH server’s AllowedUsers list
  1. Open /etc/ssh/sshd_config
  2. Find AllowUsers
  3. Add git to list of users

Creating the required directories

Gitea doesn’t have the permissions to create directories in root directories, so you need to do this yourself.

To create the required directories
  1. Run sudo mkdir -p /var/lib/gitea/{custom,data,log}
  2. Run sudo chown -R git:git /var/lib/gitea/
  3. Run sudo chmod -R 750 /var/lib/gitea/
  4. Run sudo mkdir /etc/gitea
  5. Run sudo chown root:git /etc/gitea
  6. Run sudo chmod 770 /etc/gitea

Source: Gitea’s Create required directory structure section.

Setting up Gitea

Gitea simplifies installation by providing a binary. You can download this binary and move it to a globally-accessible directory.

This section contains the following topics:

Downloading Gitea

Downloading Gitea provides you with the proper resources for running Gitea.

To download Gitea
  1. Run sudo su git
  2. Run cd
  3. Run wget -O gitea
  4. Run chmod +x gitea

Note: In this section, we are downloading Gitea version 1.13.1. For the latest version, check out Gitea’s Install from binary section.

Source: Gitea’s Download section.

Installing Gitea

Installing Gitea makes the Gitea binary globally accessible on your system.

To install Gitea
  1. Run cp gitea /usr/local/bin/gitea

Source: Gitea’s Copy Gitea binary to global location section.

Auto-starting Gitea on system boot

Auto-starting Gitea can be convenient if you need to restart your server after updates or changes, and have several other services that you need to auto-start.

To auto-start Gitea on system boot
  1. Add the following in /etc/systemd/system/gitea.service:

    Description=Gitea (Git with a cup of tea)
    # Don't forget to add the database service requirements
    # If using socket activation for main http/s
    # (You can also provide gitea an http fallback and/or ssh socket too)
    # An example of /etc/systemd/system/gitea.main.socket
    ## [Unit]
    ## Description=Gitea Web Socket
    ## PartOf=gitea.service
    ## [Socket]
    ## Service=gitea.service
    ## ListenStream=<some_port>
    ## NoDelay=true
    ## [Install]
    # Modify these two values and uncomment them if you have
    # repos with lots of files and get an HTTP error 500 because
    # of that
    # If using Unix socket: tells systemd to create the /run/gitea folder, which contains the gitea.sock file
    # (manually creating /run/gitea doesn't work, because it would not persist across reboots)
    ExecStart=/usr/local/bin/gitea web --config /etc/gitea/app.ini
    Environment=USER=git HOME=/home/git GITEA_WORK_DIR=/var/lib/gitea
    # If you install Git to directory prefix other than default PATH (which happens
    # for example if you install other versions of Git side-to-side with
    # distribution version), uncomment below line and add that prefix to PATH
    # Don't forget to place git-lfs binary on the PATH below if you want to enable
    # Git LFS support
    # If you want to bind Gitea to a port below 1024, uncomment
    # the two values below, or use socket activation to pass Gitea its ports as above
  2. Run sudo systemctl enable gitea

  3. Run sudo systemctl start gitea

Source: Gitea’s Using systemd section.

Setting up nginx

Gitea is a web application, so you need to setup nginx to serve the interface.

This section consists of the following topics:

Adding a reverse proxy

Gitea runs on port 3000 by default, so you need to configure nginx to redirect users to port 3000 on your server when they visit

To add a reverse proxy
  1. Add the following in /etc/nginx/sites-available/ as root:

    server {
      listen 80;
      location / {
        proxy_pass http://localhost:3000;
  2. Run the following command:

    sudo ln -s /etc/nginx/sites-available/ /etc/nginx/sites-enabled/
  3. Run sudo systemctl restart nginx

Source: Gitea’s Nginx section.

Setting up your git domain with certbot

Before you can access your website, you need to allow a secure connection before you sign up for the initial Gitea account, which can optionally be used as an administrator account as well as a regular user account.

To setup up your git domain with certbot
  1. Run sudo certbot
  2. Follow the prompts
  3. Run sudo systemctl restart nginx

Finalizing your Gitea setup

Before you can use Gitea, you need to access the web installer. The web installer guides you through a setup process, and user registration. The first user who signs up has the option to become an administrator user who can also use Gitea as a regular user.

This section consists of the following topics:

Accessing the web interface

Gitea provides a web interface for configuring and installing Gitea. You can access the web interface using a web browser.

To access the web interface
  1. Navigate to in your browser

    Tip: If this doesn’t work, try navigating to

  2. Choose SQLite

  3. Change “SSH Server Domain” to

  4. Change “Gitea Base URL” to

  5. Choose your desired settings for the remaining configuration options

  6. Click “Install Gitea”

Removing the write permission for the git user

In previous sections, /etc/gitea has write permissions for the git user, so the web installer could write to the configuration file. You should change the permissions back to read-only for security purposes.

To remove the write permission for the git user
  1. Run sudo chmod 750 /etc/gitea
  2. Run sudo chmod 640 /etc/gitea/app.ini

Source: Gitea’s Create required directory structure section.

Setting up fail2ban

fail2ban protects your server against repeated attacks if you have a publicly-facing authentication system, such as a sign-in page or a register page.

In this guide, we disable the registration page, but the sign-in page needs to be protected.

To setup fail2ban
  1. Add the following to /etc/fail2ban/filter.d/gitea.conf as root:

    failregex =  .*(Failed authentication attempt|invalid credentials|Attempted access of unknown user).* from <HOST>
    ignoreregex =
  2. Add the following to /etc/fail2ban/jail.d/gitea.conf as root:

    enabled = true
    filter = gitea
    logpath = /var/lib/gitea/log/gitea.log
    maxretry = 10
    findtime = 3600
    bantime = 900
    action = iptables-allports
  3. Run touch /var/lib/gitea/log/gitea.log as root

  4. Run systemctl restart fail2ban

Source: Gitea’s Fail2ban setup to block users after failed login attempts page.

Tweaking Gitea

Gitea provides an app.ini file that allows you to modify Gitea to your liking.

This section consists of the following topics:

Disabling registrations

After you created the first user, you can disable registrations to prevent unknown users from registering on your Gitea.

Note: If you wish to add a user in the future, you can use Gitea’s built-in “Create User Account” button found in “Site Administration” > “User Accounts”.

To disable registrations
  1. Edit /etc/gitea/app.ini as root

  2. Find the [service] section

  3. Change DISABLE_REGISTRATION’s value to true

    Example: Your [service] section might look like the one below:

    REGISTER_EMAIL_CONFIRM            = false
    ENABLE_NOTIFY_MAIL                = false
    DISABLE_REGISTRATION              = true
    ENABLE_CAPTCHA                    = false
    REQUIRE_SIGNIN_VIEW               = false
    NO_REPLY_ADDRESS                  = noreply.localhost

Changing the default branch name

Gitea allows you to set a default branch name when creating new repositories.

To change the default branch name
  1. Edit /etc/gitea/app.ini as root

  2. Find the [repository] section

  3. Change DEFAULT_BRANCH’s value to main

    Example: Your [repository] section might look like the one below:

    ROOT = /home/git/gitea-repositories

    Note: Other common default branch names could be trunk or default

Setting up garbage collection

Setting a garbage collection value prevents incremental memory consumption over time. Setting this keeps CPU usage at a constant level. Without this set, the CPU usage rises over time.

To setup garbage collection
  1. Edit /etc/gitea/app.ini as root

  2. Find the [session] section

  3. Add GC_INTERVAL_TIME = 86400 under PROVIDER = file

    Example: Your [session] section might look like the one below:

    PROVIDER = file
    GC_INTERVAL_TIME = 86400