Login Logout

Howto Gitea

Gitea est un logiciel libre de gestion de code source permettant de créer des projets avec un dépôt Git, des tickets, un wiki et une collaboration autour du code (fork, pull requests, etc.). Gitea est un fork de Gogs qui ressemble fortement au logiciel propriétaire Github, il est écrit en Go et nous le trouvons simple à installer et maintenir contrairement à Gitlab.

Installation

Malheureusement, Gitea n’est pas encore distribué sous forme de paquet Debian. Une alternative est donc d’utiliser directement les binaires produits par les développeurs de Gitea. Ils sont récupérables sur https://dl.gitea.io/gitea/.

# cd /usr/local/bin
# wget https://dl.gitea.io/gitea/1.5.2/gitea-1.5.2-linux-amd64
# chmod +x gitea-1.5.2-linux-amd64
# ln -s gitea-1.5.2-linux-amd64 gitea

# mkdir /etc/gitea/

# gitea --version
Gitea version 1.5.2 built with: bindata, sqlite

Note : Même si gitea peut fonctionner de manière autonome avec SQLite, à partir d’une certaine taille/utilisation, il est préférable de basculer vers un moteur de base de données tel que HowtoMySQL ou HowtoPostgreSQL et d’ajouter HowtoRedis pour le cache/sessions.

Mise à jour

Le processus de mise à jour est assez simple et similaire au processus d’installation. Après avoir regardé s’il n’y a pas d’actions à faire manuellement, on peut simplement télécharger le dernier binaire dans /usr/local/bin/. Lui appliquer les bon droits (chmod 755) et mettre à jour le lien symbolique /usr/local/bin/gitea vers ce nouveau binaire.

Il ne reste plus qu’à redémarrer l’instance. C’est terminé !

Configuration

Dans la suite de cette documentation, on se place dans le cas d’une instance simple, fonctionnant avec l’utilisateur git. On part du principe que :

  • MySQL est déjà installé
  • Le compte UNIX git existe sur la machine.
  • La configuration sera écrire dans /etc/gitea/git.ini
  • Tous les fichiers de gitea seront dans /home/git/
  • L’adresse de l’instance sera gitea.example.org

Au final, Côté fichiers applicatifs, on va se retrouver avec la hiérarchie suivante :

$ tree /home/git
├── internals 
│   ├── custom            << Fichiers de customisation de l'interface web de gitea
│   │   ├── public        << Fichiers servis par le serveur web
│   │   └── templates     << Templates des pages
│   │       └── home.tmpl
│   │ 
│   └── data              << Toutes les données de gitea (autres que les dépôts git)
│       ├── avatars
│       ├── indexers
│       ├── lfs
│       └── sessions
│
├── log                    << Journaux applicatifs
│   ├── gitea.log
│   ├── http.log
│   ├── serv.log
│   └── xorm.log
│
└── repositories            << Données des dépôts git
    └── foo
        └── hello_world.git

Ces dossiers seront créés au premier lancement de Gitea. Il faut donc s’assurer que certaines variables d’environnement sont bien positionnées.

Lors de la première exécution de Gitea, une page d’installation va demander tous les paramètres nécessaires pour initialiser l’instance. Celle-ci va aussi permettre de créer le premier compte administrateur.

/etc/gitea/git.ini

Avant de commencer, on doit initialiser le fichier de configuration de gitea avec les commandes suivantes. A noter qu’on ne laisse les droits d’écritures uniquement pour l’installation.

# touch /etc/gitea/git.ini
# chown root:git /etc/gitea/git.ini
# chmod g+rw /etc/gitea/git.ini

On ajoute aussi quelques réglages initiaux, pour que l’interface de Gitea soit directement fonctionnelle (avec des logs en cas de souci) :

# cat /etc/gitea/git.ini
APP_NAME = Gitea
RUN_USER = git
RUN_MODE = prod

[server]
PROTOCOL               = unix
DOMAIN                 = gitea.example.org
HTTP_ADDR              = /home/git/gitea.sock
UNIX_SOCKET_PERMISSION = 660
OFFLINE_MODE           = true
SSH_DOMAIN             = gitea.example.org
ROOT_URL               = http://gitea.example.org/

[repository]
ROOT                   = /home/git/repositories

[log]
ROOT_PATH              = /home/git/log/
MODE                   = file
LEVEL                  = Info

[i18n]
LANGS = fr-FR, en-US
NAMES = Français,English

systemd

On peut utiliser l’unité systemd suivante. Elle est inspirée de celle proposée par les développeurs de gitea. Nous l’avons ajustée pour correspondre au dossiers et réglages choisis plus haut.

# cat /etc/systemd/system/gitea.service

[Unit]
Description=Gitea (Git with a cup of tea) 
After=syslog.target
After=network.target

[Service]
User=git
Group=git

Type=simple
RestartSec=2s
Restart=always

WorkingDirectory=/home/git
ExecStart=/usr/local/bin/gitea web --config /etc/gitea/git.ini
Environment=GITEA_WORK_DIR=/home/git/internals 


[Install]
WantedBy=multi-user.target

MySQL

Par défaut, Gitea utilise une base SQLite. Mais on peut utiliser MySQL (ou PostgreSQL). Gitea nécessite seulement une base MySQL avec un compte.

# mysqladmin create git
# mysql
mysql> GRANT ALL PRIVILEGES ON git.* TO 'git'@localhost IDENTIFIED BY 'PASSWORD';

Côté gitea.ini, la base de donnée MySQL se configure avec la section ci-dessous.

Note : La page d’installation peut remplir cette section de la configuration automatiquement.

[database]
DB_TYPE  = mysql
HOST     = /run/mysqld/mysqld.sock
NAME     = git
USER     = git
PASSWD   = PASSWORD

Nginx

# cat /etc/nginx/sites-enabled/git
upstream gitea_git {
    server unix:/home/git/gitea.sock;
}

server {
    listen 0.0.0.0:80;
    listen [::]:80;
    #listen 0.0.0.0:443 ssl http2;
    #listen [::]:443 ssl http2;

    server_name gitea.example.org;

    #include /etc/nginx/letsencrypt.conf;
    #include /etc/nginx/ssl/git.conf;

    #if ( $scheme = http ) {
    #    return 301 https://$server_name$request_uri;
    #}

    location / {
        proxy_pass http://gitea_git;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_read_timeout 10;
    }
}

Redis

On peut utiliser Redis comme support pour les sessions et le cache de Gitea.

Cache

# cat /etc/gitea/git.ini
[cache]
ADAPTER = redis
HOST    = network=tcp,addr=127.0.0.1:6379,password=PASSWORD,db=1,pool_size=100,idle_timeout=180

Sessions

# cat /etc/gitea/git.ini
[session]
PROVIDER         = redis
PROVIDER_CONFIG  = network=tcp,addr=127.0.0.1:6379,password=PASSWORD,db=0,pool_size=100,idle_timeout=180

HTTPS

Après avoir activé le HTTPS sur le vhost nginx faisant office de reverse-proxy, il est utile d’ajuster quelques paramètres de configuration.

  • Mettre à jour le ROOT_URL pour remplacer http://gitea.example.org par https://gitea.example.org
  • Ajouter COOKIE_SECURE = true dans la section [session]
  • (Optionnel) Rajouter le préfixe __Secure- au nom des cookies. Il s’agit des paramètres COOKIE_NAME dans la section [session] ainsi que COOKIE_USERNAME et COOKIE_REMEMBER_NAME dans la section [security]

Avancé

Multiples instances

La simplicité de gitea permet d’heberger plusieurs instances sur une même machine.

Comme pour la première instance, il a besoin de :

  • D’un nouveau compte unix spécifique
  • (Si MySQL) D’un nouveau compte avec une base associée.

On peut ainsi basculer sur une unité systemd avec paramètre comme celle donnée en exemple. Ainsi, les instances seront manipulées avec systemctl (start|restart|stop) gitea@INSTANCE où INSTANCE se trouve être le nom de compte dédié à l’instance gitea

# cat /etc/systemd/system/gitea@.service

[Unit]
Description=Gitea (Git with a cup of tea) for %i
After=syslog.target
After=network.target
After=mysqld.service

[Service]
User=%i
Group=%i

Type=simple
RestartSec=2s
Restart=always

WorkingDirectory=/home/%i
ExecStart=/usr/local/bin/gitea web --config /etc/gitea/%i.ini
Environment=GITEA_WORK_DIR=/home/%i/internals 

[Install]
WantedBy=multi-user.target

Miroir

Les dépôts peuvent être configurés en miroir d’autres forges, ou pour mettre à jour des miroir sur d’autres forges.

Gitlab (push)

Pour maintenir un miroir sur une instance de Gitlab, les quelques étapes suivantes suffisent.

  1. Créer un jeton d’accès personnel sur Gitlab avec portée (« scope ») write_repository.
  • Sélectionner l’avatar en haut à droite.
  • Sélectionner « Modifier le profil » (« Edit profile »).
  • Dans la barre de gauche, sélectionner « Jetons d’accès » (« Access Tokens »).
  • Saisir un nom et éventuellement un date d’expiration pour le jeton.
  • Sélectionner la portée (« scope ») write_repository.
  • Cliquer sur « Créer jeton d’accès personnel » (« Create personal access token »).

  1. Dans les réglages (« Settings » en haut à droite) du dépôt sur Gitea, entrer l’URL du dépôt distant (« Git Remote Repository URL ») dans les réglages du miroir (« Mirror Settings ») : https://<hôte_de_destination>/<nom_ou_groupe_gitlab>/<projet_gitlab>.git.

  2. Remplir les champs d’autorisation « Authorization » avec oauth2 comme nom d’utilisateur (« Username ») et le jeton d’accès personnel précédent comme mot de passe (« Password »).

  3. Cliquer sur « Add Push Mirror » pour sauvegarder la configuration.

FAQ / Plomberie

Erreur d’enregistrement avec SHOW_REGISTRATION_BUTTON = false

A l’heure actuelle (Nov. 2018) il n’est pas possible de laisser les inscriptions actives (DISABLE_REGISTRATION = false) tout en masquant le lien d’inscription (SHOW_REGISTRATION_BUTTON = false). Le formulaire d’inscription sera bien accessible. Mais quand on le valide, une erreur 403 est retournée.

C’est un bug connu par les développeurs de Gitea.

La page d’accueil d’un projet ne se met pas à jour après le premier push

Il faut s’assurer que la partition qui contient le dossier des dépôts gits ne soit pas en noexec

Impossible de visionner le diff d’un gros commit

File diff suppressed because it is too large.

L’astuce consiste à mettre dans le fichier de configuration :

[git]
MAX_GIT_DIFF_LINES = 1000000

Augmenter à la valeur de votre choix.

Chercher tous les accès d’un compte

# mysql
MariaDB [(none)]> use git
MariaDB [git]> select repository.name, user.name, access.mode from access  INNER JOIN user ON user.id = access.user_id INNER JOIN repository ON repository.id = access.repo_id WHERE user.name like '%USER%' \G
*************************** 1. row ***************************
name: REPO
name: USER
mode: 2
1 row in set (0.00 sec)