Difference between revisions of "Gitea"

From ArchWiki
Jump to navigation Jump to search
(→‎MariaDB/MySQL: Add a warning that mariadb does not work out of the box)
(→‎Installation: Mention the official gitea package instead)
Line 11: Line 11:
== Installation ==
== Installation ==
[[Install]] the {{AUR|gitea}}, {{AUR|gitea-bin}} or, {{AUR|gitea-git}} package.
[[Install]] the {{Pkg|gitea}}, {{AUR|gitea-bin}} or, {{AUR|gitea-git}} package.
Gitea requires the use of a database backend, the following are supported:
Gitea requires the use of a database backend, the following are supported:

Revision as of 04:49, 13 October 2018

Tango-view-fullscreen.pngThis article or section needs expansion.Tango-view-fullscreen.png

Reason: Missing PostgreSQL, Apache proxy example, etc. (Discuss in Talk:Gitea#)

Gitea is a community managed fork of Gogs, lightweight code hosting solution written in Go and published under the MIT license.


Install the gitea, gitea-binAUR or, gitea-gitAUR package.

Gitea requires the use of a database backend, the following are supported:


The user configuration file should be located at /etc/gitea/app.ini. Do not edit the main configuration file (/var/lib/gitea/conf/app.ini), since this file is included in the binary and will be overwritten on each update. Instead copy (if not exists already) /var/lib/gitea/custom/conf/app.ini.sample to /etc/gitea/app.ini.

Gitea repository data will be saved into /var/lib/gitea/repos/, or if using gitea-gitAUR into /home/gitea/gitea-repositories. It is possible to set overrule this location in /etc/gitea/app.ini.

See the Gitea docs for more configuration examples.


Note: MySQL socket support can be enabled by using /var/run/mysqld/mysqld.sock as the listen address.
Warning: Gitea does not work with MariaDB < 10.2 out of the box (workaround), and the mariadb package is hold on 10.1 to keep compatibility with depending packages.

The following is an example of setting up MariaDB, setting your desired password:

$ mysql -u root -p
mysql> CREATE DATABASE `gitea` DEFAULT CHARACTER SET `utf8mb4` COLLATE `utf8mb4_unicode_ci`;
mysql> CREATE USER `gitea`@'localhost' IDENTIFIED BY 'password';
mysql> GRANT ALL PRIVILEGES ON `gitea`.* TO `gitea`@`localhost`;
mysql> \q

Try connecting to the new database with the new user:

$ mysql -u gitea -p -D gitea

Configure MariaDB on first run or update app.ini:

DB_TYPE  = mysql
HOST     = ; or /var/run/mysqld/mysqld.sock
NAME     = gitea
USER     = gitea
PASSWD   = password


Start/enable gitea.service, the webinterface should listen on http://localhost:3000.

When running Gitea for the first time it should redirect to http://localhost:3000/install.

Note: If you want Gitea to listen on all interfaces, set HTTP_ADDR = in /etc/gitea/app.ini.

Tips and tricks

Enable SSH Support

Make sure SSH has been properly configured and running.

Setup git user

Note: The package gitea-gitAUR uses gitea as user/group instead of git. Users should only have to #Configure SSH.

Create the git group and home directory for git:

# groupadd --system git
# usermod -d /home/git -s /usr/bin/bash git
# mkhomedir_helper git

Update /etc/gitea/app.ini with the home-directory of the user:

; Disable SSH feature when not available
; Domain name to be exposed in clone URL
; Port number to be exposed in clone URL
; Root path of SSH directory, default is '~/.ssh', but you have to use '/home/git/.ssh'.
SSH_ROOT_PATH = /home/git/.ssh ; /home/gitea/.ssh when using gitea-git

Configure SSH

Update the SSH configuration with AuthorizedKeysFile .ssh/authorized_keys and AllowUsers git or AllowUsers gitea when using gitea-gitAUR, e.g.:

Port 22
AuthorizedKeysFile .ssh/authorized_keys
UseDNS no
PermitUserEnvironment yes
PermitRootLogin no
PasswordAuthentication no
PermitEmptyPasswords no
AllowUsers archie git
PubkeyAuthentication yes
PrintMotd no
Subsystem sftp /usr/lib/ssh/sftp-server

Make sure to set the correct permissions for the SSH keys.

Restart gitea.service and sshd.service

Add SSH-keys for an user

Generate a SSH key pair on the client (if not exists already).

Copy the contents of the (newly) generated ~/.ssh/id_rsa.pub to Add Key on the Your Settings, SSH Keys on the Gitea webinterface.

You should now be able to use SSH-authentication to manage the repositories, without entering an username/password.

Disable HTTP protocol

By default, the ability to interact with repositories by HTTP protocol is enabled. You may want to disable HTTP-support if using SSH, by setting DISABLE_HTTP_GIT to true.

Configure nginx as reverse proxy

Tip: Let’s Encrypt is a free, automated, and open certificate authority. A plugin is available to request valid SSL certificates straight from the command line and automatic configuration.

The following is an example of using nginx as reverse proxy for Gitea including OpenSSL:

upstream gitea {

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name git.domain.tld;
    root /var/lib/gitea/public;
    access_log off;
    error_log off;

    location / {
      try_files maintain.html $uri $uri/index.html @node;

    location @node {
      client_max_body_size 0;
      proxy_pass http://localhost:3000;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header Host $http_host;
      proxy_set_header X-Forwarded-Ssl on;
      proxy_set_header X-Forwarded-Proto $scheme;
      proxy_max_temp_file_size 0;
      proxy_redirect off;
      proxy_read_timeout 120;

Update the server section of app.ini:

PROTOCOL               = http
DOMAIN                 = git.domain.tld
Note: You do not need to activate any SSL certificate options in /etc/gitea/app.ini.

Finally update the cookie section - set COOKIE_SECURE to true.

Enable Dark Theme

In the ui section, you can set the DEFAULT_THEME to arc-green for making the web interface use a dark background.


Database error on startup after upgrade to 1.5.0

A problem can appear after the upgrade to 1.5.0. The service will not start, and the following error is present in the logs:

2018/08/21 16:11:12 [...itea/routers/init.go:60 GlobalInit()] [E] Failed to initialize ORM engine: migrate: do migrate: Sync2: Error 1071: Specified key was too long; max key length is 767 bytes

To fix this problem, run the following command as the `root` user on your MySQL/MariaDB server

$ mysql -u root -p
MariaDB> set global innodb_large_prefix = `ON`;

gitea should stop complaining about key size and startup properly.

See also