agence66-borgmatic/docs/GITEA-ACTIONS.md

Déploiement Automatique avec Gitea Actions

Ce document explique comment configurer le déploiement automatique de la configuration Borgmatic via Gitea Actions.

Fonctionnement

Lorsque vous poussez des modifications sur la branche main, Gitea Actions va automatiquement :

1. Se connecter au serveur de production via SSH
2. Faire un git pull pour récupérer les derniers changements
3. Exécuter make install pour installer la nouvelle configuration

Configuration Initiale

1. Préparer une Clé SSH de Déploiement

Sur votre machine locale (pas sur le serveur), créez une paire de clés SSH dédiée au déploiement :

# Générer une clé Ed25519 pour le déploiement
ssh-keygen -t ed25519 -C "gitea-deploy-borgmatic" -f ~/.ssh/gitea-deploy-borgmatic

# Afficher la clé publique
cat ~/.ssh/gitea-deploy-borgmatic.pub

# Afficher la clé privée (à copier dans les secrets Gitea)
cat ~/.ssh/gitea-deploy-borgmatic

2. Installer la Clé Publique sur le Serveur

Connectez-vous au serveur et ajoutez la clé publique :

# Sur le serveur
mkdir -p ~/.ssh
chmod 700 ~/.ssh

# Ajouter la clé publique aux clés autorisées
echo "VOTRE_CLE_PUBLIQUE" >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

Ou utilisez ssh-copy-id :

# Depuis votre machine locale
ssh-copy-id -i ~/.ssh/gitea-deploy-borgmatic.pub user@server

3. Tester la Connexion SSH

Vérifiez que la connexion fonctionne sans mot de passe :

ssh -i ~/.ssh/gitea-deploy-borgmatic user@server

Si cela fonctionne, vous pouvez continuer.

4. Configurer les Secrets dans Gitea

Dans votre repository Gitea, allez dans Settings → Secrets et ajoutez les secrets suivants :

Nom du Secret	Valeur	Description
SERVER_HOST	votre-serveur.example.com ou IP	Adresse du serveur
SERVER_USER	root ou votre utilisateur	Nom d'utilisateur SSH
SSH_PRIVATE_KEY	Contenu de ~/.ssh/gitea-deploy-borgmatic	Clé privée SSH (tout le fichier)
SSH_PORT	22	Port SSH (optionnel, 22 par défaut)

Important : Pour SSH_PRIVATE_KEY, copiez TOUT le contenu du fichier, y compris les lignes -----BEGIN OPENSSH PRIVATE KEY----- et -----END OPENSSH PRIVATE KEY-----.

5. Activer Gitea Actions

Assurez-vous que Gitea Actions est activé sur votre instance Gitea :

1. Dans le fichier de configuration de Gitea (app.ini), vérifiez :

   [actions]
   ENABLED = true
   

2. Redémarrez Gitea si nécessaire

3. Vérifiez qu'un runner Gitea Actions est configuré et en cours d'exécution

Structure du Workflow

Le fichier .gitea/workflows/deploy.yml se trouve dans ce repository (pas dans Gitea) :

agence66-borgmatic/
├── .gitea/
│   └── workflows/
│       └── deploy.yml    ← Workflow de déploiement
├── config.yaml
├── Makefile
└── ...

C'est similaire à GitHub Actions qui utilise .github/workflows/.

Utilisation

Une fois configuré, le déploiement est automatique :

1. Faites vos modifications localement
2. Committez et poussez :

   git add .
   git commit -m "Update configuration"
   git push origin main
   

3. Gitea Actions se déclenche automatiquement
4. Consultez l'onglet Actions dans votre repository Gitea pour voir le statut

Vérification du Déploiement

Après chaque déploiement, vous pouvez vérifier :

# Sur le serveur
cd /opt/borgmatic
git log -1                    # Voir le dernier commit
sudo borgmatic config validate # Valider la configuration

Déploiement Manuel (si besoin)

Si vous devez déployer manuellement sans passer par Gitea Actions :

# Sur le serveur
cd /opt/borgmatic
git pull origin main
make install

Ou utilisez le script dédié :

sudo /opt/borgmatic/scripts/deploy.sh

Sécurité

Bonnes Pratiques

1. Clé SSH dédiée : Utilisez une clé SSH spécifique pour le déploiement (ne réutilisez pas votre clé personnelle)
2. Permissions minimales : L'utilisateur de déploiement ne devrait avoir accès qu'au dossier /opt/borgmatic
3. Secrets protégés : Les secrets Gitea sont chiffrés et ne sont jamais exposés dans les logs
4. Restriction de commandes : Vous pouvez limiter les commandes SSH autorisées dans ~/.ssh/authorized_keys

Restreindre les Commandes SSH (Optionnel)

Pour plus de sécurité, vous pouvez restreindre la clé de déploiement à exécuter uniquement le script de déploiement :

Éditez ~/.ssh/authorized_keys sur le serveur :

command="/opt/borgmatic/scripts/deploy.sh",no-port-forwarding,no-X11-forwarding,no-agent-forwarding ssh-ed25519 AAAAC3... gitea-deploy-borgmatic

Puis modifiez le workflow pour simplement se connecter (le script s'exécutera automatiquement).

Dépannage

Le workflow ne se déclenche pas

• Vérifiez que Gitea Actions est activé dans app.ini
• Vérifiez qu'un runner est en cours d'exécution
• Consultez les logs de Gitea

Erreur d'authentification SSH

Permission denied (publickey)

• Vérifiez que la clé publique est bien dans ~/.ssh/authorized_keys sur le serveur
• Vérifiez les permissions : ~/.ssh doit être 700, authorized_keys doit être 600
• Vérifiez que vous avez copié toute la clé privée dans le secret SSH_PRIVATE_KEY

Le script ne trouve pas le repository

cd: /opt/borgmatic: No such file or directory

• Assurez-vous que le repository est cloné dans /opt/borgmatic sur le serveur
• Vérifiez le chemin dans le workflow .gitea/workflows/deploy.yml

Permission denied lors de make install

• Le script nécessite sudo pour installer les fichiers dans /etc/borgmatic
• Assurez-vous que l'utilisateur de déploiement peut exécuter make install avec sudo
• Ou ajoutez sudo dans le workflow (nécessite configuration sudoers)

Logs et Monitoring

• Logs Gitea Actions : Consultez l'onglet "Actions" dans votre repository Gitea
• Logs serveur : journalctl -xe pour voir les logs système
• Logs Git : cd /opt/borgmatic && git log pour voir l'historique

Alternative : Déploiement Manuel

Si vous préférez ne pas utiliser Gitea Actions, vous pouvez :

1. Désactiver le workflow en renommant .gitea/workflows/deploy.yml en .gitea/workflows/deploy.yml.disabled
2. Déployer manuellement avec : ssh server 'cd /opt/borgmatic && git pull && make install'
3. Ou utiliser un simple cron job pour vérifier les mises à jour

Références

• Documentation Gitea Actions
• SSH Action GitHub