mes_skills/docs/tuto-gitea.md

Tutoriel Gitea — Installation, Configuration et Utilisation

Sources officielles :

• Documentation Gitea
• Installation binaire Linux
• Configuration SSH dans Gitea
• API Gitea

---

1. Installation sur Debian/Ubuntu

1.1 Prérequis

sudo apt update && sudo apt install -y git curl wget

1.2 Créer un utilisateur système dédié

sudo adduser --system --shell /bin/bash --gecos 'Gitea' \
  --group --disabled-password --home /home/gitea gitea

1.3 Créer l'arborescence des dossiers

sudo mkdir -p /var/lib/gitea/{custom,data,log}
sudo chown -R gitea:gitea /var/lib/gitea/
sudo chmod -R 750 /var/lib/gitea/
sudo mkdir -p /etc/gitea
sudo chown root:gitea /etc/gitea
sudo chmod 770 /etc/gitea

1.4 Télécharger Gitea

Récupère la dernière version depuis github.com/go-gitea/gitea/releases :

# Remplace x.y.z par la version actuelle
GITEA_VERSION="1.22.0"
wget -O /tmp/gitea "https://dl.gitea.com/gitea/${GITEA_VERSION}/gitea-${GITEA_VERSION}-linux-amd64"
sudo mv /tmp/gitea /usr/local/bin/gitea
sudo chmod +x /usr/local/bin/gitea
gitea --version

1.5 Créer le service systemd

sudo nano /etc/systemd/system/gitea.service

Contenu du fichier :

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

[Service]
RestartSec=2s
Type=simple
User=gitea
Group=gitea
WorkingDirectory=/var/lib/gitea/
ExecStart=/usr/local/bin/gitea web --config /etc/gitea/app.ini
Restart=always
Environment=USER=gitea HOME=/home/gitea GITEA_WORK_DIR=/var/lib/gitea

[Install]
WantedBy=multi-user.target

Activer et démarrer :

sudo systemctl daemon-reload
sudo systemctl enable --now gitea
sudo systemctl status gitea

---

2. Configuration initiale (interface web)

Ouvre http://ton-serveur:3000 dans un navigateur.

2.1 Paramètres recommandés

Paramètre	Valeur recommandée
Base de données	SQLite (simple) ou MariaDB (production)
Titre du site	mes_skills ou ton nom
URL de base	https://gitea.maison43.duckdns.org
Port SSH	22 (ou 2222 si conflit)
Port HTTP	3000
Dossier des dépôts	/var/lib/gitea/data/repositories

2.2 Création du compte administrateur

Remplis les champs "Compte administrateur" pendant l'installation. Ce compte aura tous les droits.

---

3. Configuration SSH

3.1 Générer une clé SSH sur ta machine locale (si pas déjà fait)

ssh-keygen -t ed25519 -C "ton@email.com"
# Clé publique générée dans : ~/.ssh/id_ed25519.pub

3.2 Ajouter la clé dans Gitea

1. Connecte-toi à Gitea
2. Paramètres (icône profil) → Paramètres → Clés SSH / GPG
3. Cliquer Ajouter une clé
4. Coller le contenu de ~/.ssh/id_ed25519.pub

3.3 Tester la connexion SSH

ssh -T git@gitea.maison43.duckdns.org
# Réponse attendue :
# Hi gilles! You've successfully authenticated, but Gitea does not provide shell access.

3.4 Configurer ~/.ssh/config (optionnel mais recommandé)

Host gitea.maison43.duckdns.org
    HostName gitea.maison43.duckdns.org
    User git
    IdentityFile ~/.ssh/id_ed25519
    Port 22

---

4. Créer et utiliser un dépôt

4.1 Créer un dépôt via l'interface

1. Cliquer + → Nouveau dépôt
2. Nom : mes_skills
3. Visibilité : Privé ou Public selon ton choix
4. Initialiser avec un README : optionnel
5. Valider

4.2 Cloner un dépôt existant

# Via SSH (recommandé)
git clone git@gitea.maison43.duckdns.org:gilles/mes_skills.git

# Via HTTPS
git clone https://gitea.maison43.duckdns.org/gilles/mes_skills.git

4.3 Configurer le remote sur un dépôt local existant

git remote add origin git@gitea.maison43.duckdns.org:gilles/mes_skills.git
git push -u origin main

4.4 Workflow git quotidien

git add fichier.md
git commit -m "feat: ajout skill debugging"
git push

# Récupérer les modifications distantes
git pull

---

5. Tokens d'accès API

Utile pour les scripts bash, l'installeur de skills, ou l'automatisation.

5.1 Créer un token

1. Paramètres → Applications → Générer un nouveau token
2. Nom : mes_skills_installer
3. Durée : illimitée ou 1 an
4. Permissions : Repository → Read (pour lire) / Write (pour pousser)
5. Copier le token immédiatement — il ne sera plus affiché

5.2 Utiliser le token dans un script bash

GITEA_TOKEN="ton_token_ici"
GITEA_URL="https://gitea.maison43.duckdns.org"

# Lister les dépôts
curl -s -H "Authorization: token $GITEA_TOKEN" \
  "${GITEA_URL}/api/v1/repos/search" | jq '.data[].name'

# Créer un fichier dans un dépôt
curl -s -X POST \
  -H "Authorization: token $GITEA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"feat: nouveau skill","content":"'"$(base64 -w0 mon_fichier.md)"'"}' \
  "${GITEA_URL}/api/v1/repos/gilles/mes_skills/contents/skills/dev/mon-skill/claude-code.md"

5.3 Stocker le token de façon sécurisée

# Dans ~/.config/mes_skills/config (permissions 600)
mkdir -p ~/.config/mes_skills
echo "GITEA_TOKEN=ton_token_ici" > ~/.config/mes_skills/config
chmod 600 ~/.config/mes_skills/config

# Charger dans un script
source ~/.config/mes_skills/config

---

6. Accès depuis l'extérieur (DuckDNS + reverse proxy)

6.1 DuckDNS (DNS dynamique)

Ton instance est accessible via gitea.maison43.duckdns.org.

Pour maintenir le DNS à jour (si IP dynamique) :

# Cron toutes les 5 minutes
*/5 * * * * curl -s "https://www.duckdns.org/update?domains=maison43&token=TON_TOKEN_DUCKDNS&ip=" > /dev/null

6.2 Reverse proxy Nginx (HTTPS)

server {
    listen 443 ssl;
    server_name gitea.maison43.duckdns.org;

    ssl_certificate     /etc/letsencrypt/live/gitea.maison43.duckdns.org/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/gitea.maison43.duckdns.org/privkey.pem;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
    }
}

Certificat Let's Encrypt :

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d gitea.maison43.duckdns.org

---

7. Utilisation avec mes_skills

7.1 Pousser des skills vers Gitea

cd ~/Documents/vscode/mes_skills/mes_skills

# Ajouter un nouveau skill
cp templates/claude-code.md skills/dev/mon-nouveau-skill/claude-code.md
# Éditer le fichier...

git add skills/dev/mon-nouveau-skill/
git commit -m "feat: ajout skill mon-nouveau-skill"
git push

7.2 Installer les skills depuis Gitea

# Installation standard (clone depuis Gitea)
curl -fsSL https://gitea.maison43.duckdns.org/gilles/mes_skills/raw/branch/main/install.sh | bash

# Installation depuis le dépôt local (développement)
SKILLS_REPO=/chemin/local bash install.sh

7.3 URL utiles de ton instance

Usage	URL
Interface web	https://gitea.maison43.duckdns.org
Dépôt mes_skills	https://gitea.maison43.duckdns.org/gilles/mes_skills
install.sh brut	https://gitea.maison43.duckdns.org/gilles/mes_skills/raw/branch/main/install.sh
API	https://gitea.maison43.duckdns.org/api/v1
Swagger API	https://gitea.maison43.duckdns.org/api/swagger

---

8. Workflow git pas à pas — pour débutant

Le cycle de travail en 4 étapes

Modifier des fichiers
        ↓
   git add        ← "je veux inclure ces fichiers dans mon enregistrement"
        ↓
   git commit     ← "j'enregistre une version avec un message"
        ↓
   git push       ← "j'envoie mon travail vers Gitea"

Et dans l'autre sens :

   git pull       ← "je récupère les modifications de Gitea vers ma machine"
        ↓
Modifier des fichiers
        ↓
   ...

---

Étape 0 — Vérifier où on en est (toujours commencer par là)

git status

Ce que ça dit :

• "nothing to commit" → tout est propre, rien à faire
• "Changes not staged" → tu as modifié des fichiers mais pas encore fait git add
• "Changes to be committed" → tu as fait git add, prêt pour git commit
• "Your branch is ahead of origin" → tu as des commits locaux à push

💡 Règle d'or : lance git status avant de faire quoi que ce soit. C'est ton tableau de bord.

---

Étape 1 — git add — Préparer les fichiers à enregistrer

git add ne sauvegarde rien encore. Il dit juste à git : "ces fichiers feront partie de mon prochain enregistrement".

# Ajouter un fichier précis
git add skills/dev/debugging/claude-code.md

# Ajouter tous les fichiers modifiés d'un dossier
git add skills/dev/debugging/

# Ajouter tous les fichiers modifiés du projet (à utiliser avec précaution)
git add .

Après un git add, refais git status pour voir ce qui est "en attente de commit" (en vert).

---

Étape 2 — git commit — Enregistrer une version

git commit crée un point de sauvegarde local avec un message qui explique ce que tu as fait et pourquoi.

git commit -m "feat: ajout skill debugging pour claude-code"

💡 Un bon message de commit répond à la question : "Si je lis ça dans 6 mois, je comprends ce qui a changé ?"

Conventions de messages (optionnel mais utile) :

Préfixe	Usage
feat:	Nouveau skill, nouvelle fonctionnalité
fix:	Correction d'une erreur
docs:	Modification de documentation
chore:	Maintenance, nettoyage

À ce stade, ton travail est sauvegardé localement mais pas encore sur Gitea.

---

Étape 3 — git push — Envoyer vers Gitea

git push envoie tes commits locaux vers ton dépôt Gitea. C'est à ce moment que les autres (ou toi depuis une autre machine) peuvent voir ton travail.

# Premier push sur une nouvelle branche
git push -u origin main

# Tous les push suivants (plus court)
git push

Si ça demande un mot de passe → tu utilises HTTPS. Passe en SSH (voir section 3) pour ne plus jamais avoir à saisir de mot de passe.

---

Étape 4 — git pull — Récupérer les modifications de Gitea

git pull télécharge les modifications faites sur Gitea (par toi depuis une autre machine, ou par quelqu'un d'autre) et les intègre à ta copie locale.

git pull

💡 Bonne habitude : fais toujours git pull avant de commencer à travailler, pour être sûr d'avoir la version la plus récente.

---

Exemple complet — Ajouter un skill et le pousser

# 1. Récupérer les dernières modifications de Gitea
git pull

# 2. Vérifier l'état du dépôt
git status

# 3. Créer ton nouveau skill
cp templates/claude-code.md skills/jardinage/arrosage/claude-code.md
# Éditer le fichier avec ton éditeur...

# 4. Vérifier ce qui a changé
git status
# → "Untracked files: skills/jardinage/arrosage/claude-code.md"

# 5. Préparer le fichier pour l'enregistrement
git add skills/jardinage/arrosage/claude-code.md

# 6. Vérifier (optionnel mais recommandé)
git status
# → "Changes to be committed: new file: skills/jardinage/..."

# 7. Enregistrer la version avec un message
git commit -m "feat: ajout skill arrosage pour jardinage"

# 8. Envoyer vers Gitea
git push

Résultat : ton skill est visible sur https://gitea.maison43.duckdns.org/gilles/mes_skills

---

Voir l'historique de tes commits

# Compact (une ligne par commit)
git log --oneline -10

# Avec dates et auteur
git log --oneline --graph -10

---

Annuler des erreurs courantes

# J'ai fait git add par erreur sur un fichier → l'enlever de la sélection
git restore --staged fichier.md

# J'ai modifié un fichier et je veux revenir à la version du dernier commit
git restore fichier.md

# Je veux voir ce que j'ai modifié avant de committer
git diff

# Je veux voir ce qui est dans le "add" (staged)
git diff --staged

---

9. Commandes git essentielles

# Statut du dépôt
git status

# Historique compact
git log --oneline -10

# Voir les modifications avant commit
git diff

# Annuler les modifications d'un fichier (non commité)
git restore fichier.md

# Créer une branche
git checkout -b ma-branche

# Revenir sur main
git checkout main

# Fusionner une branche
git merge ma-branche

# Voir les remotes
git remote -v

---

9. Mise à jour de Gitea

sudo systemctl stop gitea

# Télécharger la nouvelle version
wget -O /tmp/gitea "https://dl.gitea.com/gitea/NOUVELLE_VERSION/gitea-NOUVELLE_VERSION-linux-amd64"
sudo mv /tmp/gitea /usr/local/bin/gitea
sudo chmod +x /usr/local/bin/gitea

sudo systemctl start gitea
gitea --version

---

10. Dépannage courant

Problème	Solution
Port 3000 inaccessible	sudo ufw allow 3000 ou vérifier le firewall
Push SSH refusé	Vérifier la clé SSH dans Gitea, tester avec ssh -T git@...
git push demande mot de passe	Utiliser SSH au lieu de HTTPS, ou configurer un credential helper
Gitea ne démarre pas	sudo journalctl -u gitea -n 50 pour voir les logs
Clone lent	Vérifier la connexion réseau, utiliser --depth=1 pour les gros dépôts