Intermédiaire ⏱ 25 min de mise en œuvre Mis à jour le 11 août 2026

Héberger Gitea : votre GitHub privé sur un VPS

Vos dépôts, vos issues, vos pull requests, sur votre serveur. Gitea est une forge Git légère et open source, alternative crédible à GitHub et GitLab. Voici comment la déployer proprement.

Héberger son propre service Git permet de garder la maîtrise des dépôts, des comptes et des sauvegardes. Pour une équipe qui développe un produit interne, manipule du code client ou souhaite réduire sa dépendance à une plateforme américaine, cette souveraineté peut compter autant que les fonctionnalités.

Gitea fournit l’essentiel d’une forge moderne : dépôts Git privés, gestion des issues, pull requests, organisations, webhooks et automatisation CI avec Gitea Actions. Son interface rappelle GitHub, mais son empreinte reste nettement plus légère que celle de GitLab. GitHub demeure plus riche en intégrations et GitLab propose une plateforme DevOps très complète, au prix de besoins en ressources plus importants. Gitea convient bien aux petites équipes, aux agences et aux projets personnels qui cherchent une forge simple à administrer.

Installé sur un VPS situé en France, il permet également de mieux contrôler la localisation du code et les conditions de traitement des données. Les VPS TalCloud sont disponibles à partir de 4,99 € par mois, avec des serveurs en France, du stockage NVMe, une protection Anti-DDoS Netrix et un support humain. Dimensionnez le serveur selon le nombre d’utilisateurs, la taille des dépôts et la charge CI attendue.

Prérequis

Pour suivre ce guide, préparez :

un VPS Linux avec un accès administrateur ;
Docker Engine et le module Docker Compose (voir installer Docker sur un VPS) ;
un nom de domaine ou un sous-domaine, par exemple git.exemple.fr ;
un enregistrement DNS de type A, et éventuellement AAAA, pointant vers le VPS ;
les ports 80 et 443 accessibles pour le Web ;
un port TCP disponible pour les connexions Git en SSH.

Gitea est léger, mais les runners CI peuvent consommer beaucoup plus de mémoire, de processeur et d’espace disque que la forge elle-même. Il est souvent préférable d’exécuter les runners sur une machine séparée, surtout lorsque les pipelines construisent des images Docker.

Créez un répertoire dédié au projet, puis placez-y le fichier compose.yaml présenté dans la section suivante. Utilisez un mot de passe PostgreSQL long et unique. Dans un environnement réel, stockez-le dans un fichier .env protégé plutôt que dans l’historique Git.

Installer Gitea avec Docker Compose

Cette configuration lance Gitea avec PostgreSQL. Les données de l’application et de la base sont conservées dans deux volumes Docker persistants.

services:
  db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: gitea
      POSTGRES_USER: gitea
      POSTGRES_PASSWORD: changez-ce-mot-de-passe
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U gitea -d gitea"]
      interval: 10s
      timeout: 5s
      retries: 5

  gitea:
    image: gitea/gitea:latest
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    environment:
      USER_UID: 1000
      USER_GID: 1000
      GITEA__database__DB_TYPE: postgres
      GITEA__database__HOST: db:5432
      GITEA__database__NAME: gitea
      GITEA__database__USER: gitea
      GITEA__database__PASSWD: changez-ce-mot-de-passe
      GITEA__server__DOMAIN: git.exemple.fr
      GITEA__server__ROOT_URL: https://git.exemple.fr/
      GITEA__server__SSH_DOMAIN: git.exemple.fr
      GITEA__server__SSH_PORT: 2222
      GITEA__server__SSH_LISTEN_PORT: 22
    volumes:
      - gitea_data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "127.0.0.1:3000:3000"
      - "2222:22"

volumes:
  postgres_data:
  gitea_data:

Le port HTTP 3000 est lié uniquement à l’adresse locale du VPS. Il sera exposé publiquement par le reverse proxy HTTPS. Le service SSH écoute sur le port 22 dans le conteneur, mais Docker le publie ici sur le port 2222 du VPS.

Démarrez les services :

docker compose up -d
docker compose ps
docker compose logs -f gitea

Évitez de conserver indéfiniment une image non figée. Une fois l’installation validée, relevez la version utilisée et remplacez latest par une étiquette de version précise. Avant chaque mise à jour, consultez les notes de version et réalisez une sauvegarde.

Gérer le port SSH de Gitea

Le serveur SSH du système utilise normalement le port 22. Docker ne peut donc pas publier simultanément le port SSH de Gitea sur cette même adresse et ce même port.

La solution la plus simple consiste à conserver le SSH système sur 22 et à publier Gitea sur un port dédié, comme 2222. La variable GITEA__server__SSH_PORT indique à Gitea le port à afficher dans les URL de clonage. Le port interne du conteneur reste 22 grâce à GITEA__server__SSH_LISTEN_PORT.

Une URL de clonage prendra alors cette forme :

git clone ssh://git@git.exemple.fr:2222/equipe/projet.git

Une autre possibilité consiste à déplacer le SSH d’administration du VPS vers un autre port, puis à publier Gitea avec "22:22". Cette opération doit être préparée avec prudence pour ne pas perdre l’accès au serveur.

Le passthrough SSH permet aussi au service SSH du système de recevoir les connexions sur le port 22 et de transmettre les commandes de l’utilisateur git à gitea serv dans le conteneur. Cette méthode offre des URL plus courtes, mais demande une configuration rigoureuse des clés, des commandes forcées et de leur synchronisation. Pour une première installation, le port 2222 reste plus facile à maintenir.

Activer HTTPS avec un reverse proxy

Gitea écoute localement sur 127.0.0.1:3000. Un reverse proxy peut gérer les certificats TLS et transmettre les requêtes. Avec Caddy installé sur le VPS, un fichier Caddyfile minimal suffit :

git.exemple.fr {
    reverse_proxy 127.0.0.1:3000
}

Rechargez ensuite Caddy selon son mode d’installation. Lorsque le DNS pointe correctement vers le serveur et que les ports 80 et 443 sont ouverts, Caddy obtient automatiquement un certificat TLS.

Avec Nginx Proxy Manager ou Traefik, le principe reste identique : terminer HTTPS sur le proxy, transmettre les en-têtes d’origine et rediriger le trafic vers le port 3000. La valeur de ROOT_URL doit rester https://git.exemple.fr/, faute de quoi Gitea peut générer des liens ou des URL de clonage incorrects.

Créer le premier compte administrateur

Ouvrez https://git.exemple.fr. Lors de la première installation, vérifiez les paramètres affichés, notamment le domaine, l’URL racine, la base PostgreSQL et le port SSH.

Le premier utilisateur inscrit devient administrateur sur une instance neuve. Créez donc immédiatement ce compte avec une adresse contrôlée et un mot de passe unique, puis activez l’authentification à deux facteurs depuis ses paramètres.

Après la création des comptes nécessaires, désactivez l’inscription publique en ajoutant cette variable au service gitea :

GITEA__service__DISABLE_REGISTRATION: "true"

Appliquez la modification :

docker compose up -d

Les administrateurs pourront toujours gérer les utilisateurs depuis l’interface d’administration ou avec la commande gitea admin user create exécutée dans le conteneur.

Utiliser votre GitHub privé

Depuis l’interface, sélectionnez la création d’un dépôt, choisissez son propriétaire et définissez sa visibilité. Pour un dépôt privé accessible en HTTPS :

git clone https://git.exemple.fr/equipe/projet.git

Pour utiliser SSH sur le port dédié, ajoutez d’abord votre clé publique dans les paramètres du compte, puis clonez le dépôt :

git clone ssh://git@git.exemple.fr:2222/equipe/projet.git

Vous pouvez ensuite travailler avec les commandes Git habituelles :

git add .
git commit -m "Ajout de la configuration initiale"
git push origin main

Les issues servent à suivre les anomalies et les tâches. Les pull requests permettent de relire une branche avant sa fusion. Les organisations regroupent les dépôts, les équipes et leurs permissions. Pour la CI, Gitea Actions exécute des workflows proches de ceux de GitHub Actions, mais nécessite au moins un runner enregistré et correctement isolé.

Forgejo constitue une alternative issue d’un fork de Gitea, avec une gouvernance communautaire et une expérience d’administration très proche.

Sécuriser et sauvegarder l’instance

Mettez régulièrement à jour le système, Docker, PostgreSQL et Gitea. Limitez les ports exposés avec le pare-feu du VPS, activez la double authentification et évitez de donner des droits administrateur sans nécessité. Les runners CI doivent être considérés comme des environnements capables d’exécuter du code potentiellement dangereux.

Une sauvegarde exploitable doit couvrir le volume gitea_data, qui contient notamment les dépôts et la configuration, ainsi que la base PostgreSQL. Une copie isolée de ces éléments doit être envoyée vers un autre serveur ou un stockage objet, avec une politique de rétention. Notre guide sur la stratégie de sauvegarde d’un serveur détaille cette approche.

Pour exporter explicitement la base :

docker compose exec -T db pg_dump -U gitea -d gitea > gitea-db.sql

Gitea fournit également la commande dump, à exécuter avec l’utilisateur git du conteneur :

docker compose exec -u git gitea gitea dump -c /data/gitea/conf/app.ini

La commande indique le nom de l’archive créée. Copiez cette archive hors du volume et conservez avec elle le fichier compose.yaml, les secrets nécessaires et la version exacte des images. Testez enfin la restauration sur une instance séparée : une sauvegarde n’est validée qu’après récupération d’un dépôt, connexion d’un utilisateur et vérification des issues.