Création d’un jeton Gitea / Forgejo (Codeberg)

Le canal Git avec provider = "gitea" ou provider = "forgejo" s’authentifie avec un jeton d’accès personnel auprès de l’API REST compatible Gitea de l’instance, et répond en tant que propriétaire du jeton. Les deux fournisseurs partagent une seule implémentation interne ; la seule véritable différence par rapport à GitHub est qu’il n’y a pas d’application, seulement un jeton et une URL de base d’API explicite.

Les exemples ci-dessous utilisent Codeberg (une instance publique Forgejo). Pour une instance Gitea ou Forgejo auto-hébergée, remplacez par votre propre hôte.

Documentation officielle : La portée du jeton d’accès de Forgejo est la référence amont pour les portées de jetons ; sur Codeberg, suivez Génération d’un jeton d’accès. Les instances Gitea exposent la même interface utilisateur pour les jetons.

1. Utilisez un compte de bot dédié

Créez le token sur un compte bot distinct, et non sur votre compte opérateur. Le canal ignore ses propres activités : si le propriétaire du token est également l’utilisateur qui @-mentionne l’application, ces messages seront ignorés silencieusement. Un compte dédié permet de garder distinctes les réponses du bot de vos propres commentaires.

Sur Codeberg, créez un deuxième compte normal pour le bot et invitez-le aux dépôts cibles (ou à l’organisation) avec un accès en écriture.

2. Générer le jeton

En tant que compte bot : Paramètres → Applications → Gérer les jetons d’accès (Codeberg : https://codeberg.org/user/settings/applications).

1. Attribuez un nom au jeton (par ex. zeroclaw).
2. Sélectionnez les portées. Le canal nécessite, au minimum :
   • read:user : le canal résout sa propre identité de bot à partir de /user au démarrage.
   • Dépôt Lecture + écriture pour les issues/PR. Sur Forgejo/Codeberg, les scopes sont regroupés read:repository + write:repository et read:issue + write:issue. Si l’interface ne propose que des scopes génériques repository / issue, cochez-les.
3. Générer le jeton et copiez-le. Il ne s’affiche qu’une seule fois.

Le jeton nécessite un accès en lecture aux dépôts ainsi qu’un accès en écriture aux commentaires d’issues/PR pour les réponses et les réactions. N’accordez rien au-delà de ce que les dépôts cibles exigent.

3. Trouver l’URL de base de l’API

C’est la partie sans valeur par défaut. Le canal échoue en mode fermé au démarrage si api_base_url n’est pas défini, car chaque requête transporte le jeton en tant qu’identifiant bearer et il ne devinera pas d’hôte vers lequel l’envoyer.

La valeur est la racine de l’instance plus /api/v1 :

• Codeberg: `https://codeberg.org/api/v1`
• Service Gitea public : https://gitea.com/api/v1
• Auto-hébergé : https://git.example.org/api/v1

4. Associer à la configuration

Définissez chaque champ ci-dessous sur la surface de votre choix. Le jeton d’accès est un secret chiffré et dispose de son propre widget masqué ; les autres sont des champs simples.

provider: gitea pour une instance Gitea, forgejo pour une instance Forgejo (y compris Codeberg). Ils se comportent de manière identique, et une valeur inconnue provoque une erreur de démarrage explicite plutôt qu’un repli silencieux.

zeroclaw config set channels.git.<alias>.provider <value>

api_base_url : la racine de l’instance suivie de /api/v1 (étape 3). Requis ; le démarrage échoue de manière sécurisée sans ce paramètre.

zeroclaw config set channels.git.<alias>.api_base_url <value>

access_token: le token de l’étape 2.

channels.git.<alias>.access_token est un secret. Stocké chiffré, jamais en clair dans config.toml. Définissez-le via l’une de ces méthodes, qui chiffrent lors de l’écriture :

zeroclaw config set channels.git.<alias>.access_token    # demande une saisie masquée, stocke de manière chiffrée

repos: la liste owner/repo` à surveiller. Laissez vide pour interroger tous les dépôts que le jeton peut voir.

zeroclaw config set channels.git.<alias>.repos <value>

Pour la référence complète des champs, consultez la page Canal Git.

5. Vérifier

Le canal Git est inclus dans les artefacts de distribution standard, mais pas dans la configuration Cargo minimale par défaut. Pour une compilation personnalisée à partir des sources, incluez channel-git (ainsi que agent-runtime lors de la désactivation des fonctionnalités par défaut) :

cargo build --features channel-git

channel-git intègre tous les fournisseurs forge câblés en une seule compilation ; il n’existe pas de sous-ensemble plus petit par fournisseur, et compiler une fonctionnalité provider-* nue sans channel-git n’enregistre pas le canal.

Au démarrage, le canal appelle /user pour résoudre son login bot, journalise une ligne IDENTITY OK et commence le polling. @-mentionnez le bot sur une issue ou une PR dans un dépôt configuré pour confirmer qu’il répond. Si le démarrage échoue en se plaignant de api_base_url, l’URL de base est manquante ou vide. Consultez la page Git channel pour le routage des événements, la liaison des peer-groups et les notes d’exploitation.

Étapes suivantes

• Retour au canal : canal Git pour le routage des événements, le streaming, le budget de débit et la sécurité.
• Restreindre qui peut joindre l’agent : Peer Groups.
• Piloter l’automatisation à partir des événements forge : Procédures Opérationnelles Standard et le fan-in Git des SOP.
• Vous découvrez ZeroClaw ? Quickstart et Concepts.