Aller au contenu principal

Tickets et pull requests

Les tickets et les PR de fremforge sont les fonctionnalités standard de Forgejo. La documentation de Forgejo fait référence pour l’ensemble des fonctionnalités. Cette page couvre les politiques et intégrations propres à fremforge.

Journalisation d’audit

Chaque changement d’état d’un ticket ou d’une PR (ouverture, fermeture, réouverture, modification de label, modification d’assignation, revue soumise, fusion) est enregistré dans le journal d’audit de l’organisation. Les entrées du journal d’audit indiquent l’auteur, l’horodatage, le dépôt et l’action. Vous y accédez sous Administration de l’organisation → Journal d’audit ou via l’API.

Conditions de fusion des PR et protection de branche

Les PR vers des branches protégées doivent respecter toutes les règles de protection de branche configurées avant que le bouton de fusion soit activé. Voir Administration de l’organisation pour la configuration des règles.

Appliquer les suggestions de revue

Forgejo affiche les blocs de code ```suggestion dans les commentaires de revue des PR. fremforge y ajoute un bouton Apply suggestion qui applique la suggestion en un clic, avec la même expérience que GHEC. Cliquez dessus sur n’importe quel commentaire de suggestion : le code suggéré est inséré dans le fichier au niveau du commit de tête de la PR, et attribué à l’utilisateur qui a cliqué.

Fonctionnement :

  1. Le bouton apparaît sur chaque commentaire de revue qui contient un bloc de code ```suggestion. Les suggestions sur une seule ligne comme sur plusieurs lignes fonctionnent.
  2. L’utilisateur qui applique la suggestion doit disposer de la permission write ou admin sur le dépôt. Les collaborateurs en lecture seule ne voient pas le bouton.
  3. fremforge vérifie que la PR est toujours ouverte et que le SHA de tête correspond au SHA au moment où la suggestion a été affichée. Si la PR a subi un force-push après l’affichage de la suggestion, l’application échoue avec une erreur 409 et l’utilisateur est invité à actualiser la page : cela empêche une suggestion périmée d’écraser un travail plus récent.
  4. Le commit a pour auteur l’utilisateur qui applique la suggestion (et non un compte de service fremforge), exactement comme dans GHEC.
  5. L’action est enregistrée dans le journal d’audit de l’organisation sous pr.suggestion.applied, avec le numéro de la PR, le chemin du fichier, la plage de lignes et l’identifiant du commentaire de revue.

Résoudre la conversation après l’application reste une étape manuelle (cliquez sur Resolve dans l’interface de revue de Forgejo) : fremforge ne la résout pas automatiquement, car le point de terminaison de résolution et le modèle de fil de revue de Forgejo diffèrent subtilement de ceux de GitHub, et nous préférons ne pas trop promettre sur ce point.

Fusion automatique

Les PR peuvent être configurées pour fusionner automatiquement lorsque toutes les vérifications requises réussissent. Activez-la au niveau de la PR : cliquez sur le menu déroulant à côté de Merge → Enable auto-merge. Choisissez la stratégie de fusion (commit de fusion, squash, rebase).

Pousser de nouveaux commits sur la PR n’annule pas la fusion automatique. La PR reste planifiée et fusionne dès que les vérifications requises réussissent sur le nouveau commit de tête ; les résultats d’un commit antérieur ne comptent pas. Il en va de même sur les branches avec et sans file de fusion. Si la règle de protection de branche écarte les approbations périmées, un push efface aussi les approbations existantes, et la PR attend une nouvelle approbation avant de fusionner.

Pour empêcher une PR planifiée de fusionner, par exemple avant de pousser une modification que vous voulez encore relire, annulez la fusion automatique sur la PR, ou appelez DELETE /api/v1/repos/{owner}/{repo}/pulls/{index}/merge. La réactiver plus tard planifie à nouveau la fusion.

File de fusion

Une branche protégée peut utiliser une file de fusion (le paramètre merge_queue de sa règle de protection de branche). Lorsque la file est active, activer la fusion automatique place la PR dans la file, et la file la teste dans un groupe de fusion : la branche cible, plus les PR qui la précèdent dans la file, plus cette PR. Les workflows déclenchés par merge_group s’exécutent sur ce commit et publient des statuts … (merge_group). Une vérification requise X (pull_request) est satisfaite par le résultat X (merge_group) correspondant : ajoutez donc merge_group aux déclencheurs des workflows qui portent vos vérifications requises.

Quel build compte pendant qu’une PR est dans la file

  • L’exécution du groupe de fusion tient lieu de build de la PR. Lorsque la PR entre dans un groupe de fusion, ses exécutions pull_request en cours de chaque workflow également déclenché par merge_group sont annulées, afin que le même workflow ne construise pas deux fois. Sur la PR, ces vérifications indiquent Superseded by the merge queue et reprennent le résultat du groupe de fusion.
  • Les workflows sans déclencheur merge_group continuent de s’exécuter sur la PR, et leurs résultats comptent comme avant. Un job que le groupe de fusion ignore (par exemple avec un if: qui exclut merge_group) ne remplace pas non plus la vérification propre à la PR ; c’est l’exécution de la PR elle-même qui tranche.
  • Quitter la file rétablit les vérifications normales. Si le groupe de fusion échoue et que la PR est retirée de la file, ou si la fusion automatique est annulée, les exécutions pull_request annulées sont relancées sur le commit de la PR. Un nouveau push donne au nouveau commit ses propres exécutions pull_request, comme toujours.
  • Un push retire une PR de la file, mais pas de la fusion automatique. La PR conserve sa fusion automatique et rejoint la file en dernière position dès que ses vérifications réussissent sur le nouveau commit. Annulez la fusion automatique si elle ne doit pas fusionner.
  • Un groupe de fusion en échec ne fusionne jamais la PR. Le statut fremforge/merge-queue de la PR indique Merge group failed — removed from the merge queue, un commentaire sur la PR en donne la raison, et l’exécution en échec figure dans la liste Actions du dépôt en tant qu’exécution merge_group.

Quand la file annule la fusion automatique

Si la file retire une PR et que rien ne la ferait revenir d’elle-même, elle peut aussi annuler la fusion automatique de la PR. Ainsi, un push ultérieur qui fait passer les vérifications au vert ne fusionne pas la PR avant que quelqu’un l’ait réexaminée. Cela s’applique lorsque :

  • l’une des vérifications requises propres à la PR échoue pendant qu’elle est dans la file ;
  • son groupe de fusion échoue, dépasse le délai ou entre en conflit avec les PR qui la précèdent, une fois épuisées les nouvelles tentatives automatiques lorsque main avance ;
  • ses propres vérifications restent en attente au-delà du délai de la file pour la seconde fois ;
  • la file ne parvient pas à renommer l’une de ses nouvelles migrations pour les remettre dans l’ordre (voir l’option .forgejo/merge-queue-restamp).

Une PR qui rejoindra encore la file d’elle-même conserve sa fusion automatique : lorsqu’une nouvelle tentative est prévue, après un push, en tant que brouillon ou après la perte de ses approbations. Il en va de même pour une PR dont la fusion automatique a été activée par un bot tel que Renovate. L’annulation apparaît sur la PR sous la forme auto merge cancelled par forgejo-actions. Un commentaire en donne la raison, et le statut fremforge/merge-queue se termine par Auto-merge cancelled.

Pour réarmer : corrigez ce qui a retiré la PR, puis réactivez la fusion automatique. Utilisez le bouton Auto merge when checks succeed sur la PR, ou l’API :

curl -X POST -H "Authorization: token $TOKEN" -H "Content-Type: application/json" \
  https://frem.sh/api/v1/repos/<org>/<repo>/pulls/<number>/merge \
  -d '{"Do":"squash","merge_when_checks_succeed":true}'

La PR rejoint ensuite la file dès que ses propres vérifications réussissent.

Le paramètre. merge_queue_disarm_on_removal sur la règle de protection de branche vaut default, on ou off. Définissez-le avec l’API de protection de branche (PATCH /api/v1/repos/<org>/<repo>/branch_protections/<rule>). merge_queue_disarm_on_removal_effective dans la réponse indique s’il s’applique. Pour les organisations clientes, default signifie actuellement off : la fusion automatique survit donc à un retrait, comme auparavant. Définissez on pour activer ce comportement sur un dépôt.

Priorité dans la file

La file teste les PR dans l’ordre où elles l’ont rejointe. Pour faire passer une PR devant, par exemple un correctif pour un main cassé ou un hotfix, donnez-lui la priorité high. Une PR prioritaire passe devant toutes les PR normales qui ne sont pas encore dans un groupe de fusion. Elle n’interrompt ni ne reconstruit jamais un groupe de fusion déjà en cours : elle attend donc la fin des groupes en cours et passe ensuite. Deux PR prioritaires conservent l’ordre dans lequel elles ont rejoint la file.

Définissez la priorité lorsque vous activez la fusion automatique, ou plus tard pendant que la PR est dans la file :

# when enabling auto-merge
curl -X POST -H "Authorization: token $TOKEN" -H "Content-Type: application/json" \
  https://frem.sh/api/v1/repos/<org>/<repo>/pulls/<number>/merge \
  -d '{"Do":"squash","merge_when_checks_succeed":true,"merge_queue_priority":"high"}'

# on a PR that already has auto-merge
curl -X PUT -H "Authorization: token $TOKEN" -H "Content-Type: application/json" \
  https://frem.sh/api/v1/repos/<org>/<repo>/pulls/<number>/merge-queue/priority \
  -d '{"priority":"high","reason":"fixes the red main"}'

Un GET sur le même chemin affiche la priorité de la PR, qui l’a définie, sa place dans la file et la longueur de la file. DELETE la ramène à la priorité normale.

  • Qui peut la définir : toute personne qui peut fusionner la PR, c’est-à-dire disposant d’un accès en écriture au dépôt et, si la règle en comporte une, d’une place sur la liste des personnes autorisées à fusionner dans la branche. Toute autre personne reçoit une erreur 403.
  • Elle est liée à la fusion automatique. Annuler la fusion automatique, ou la réactiver, ramène la PR à la priorité normale. Définir une priorité sur une PR sans fusion automatique renvoie 409.
  • Chaque changement est enregistré. Un commentaire sur la PR indique qui a modifié la priorité, de quelle valeur à quelle valeur, et la raison si elle a été donnée (200 caractères au maximum).

Réservez la priorité haute à la PR que d’autres attendent, et n’en faites pas une valeur par défaut. Lorsque toutes les PR sont prioritaires, la file revient à l’ordre d’arrivée.

Stratégies de fusion

Le commit de fusion, la fusion squash et la fusion rebase sont toutes disponibles pour chaque dépôt. Choisissez les stratégies autorisées et celle par défaut sous Dépôt → Paramètres → Fonctionnalités → Demandes d’ajout (Styles de fusion, Style de fusion par défaut). Les propriétaires de l’organisation définissent la méthode de fusion par défaut des nouveaux dépôts sous Administration de l’organisation → Sécurité → Politiques → Règles des dépôts (Méthode de fusion par défaut) ; chaque dépôt peut la remplacer.

Un nouveau dépôt supprime la branche d’une pull request lorsqu’elle est fusionnée, et fusionne en squash par défaut. fremforge définit ces deux réglages à la création du dépôt, à partir de la configuration de base de l’organisation sous Organisation › Dépôts (/<org>/_admin/repos-overview#org-baseline), où un propriétaire de l’organisation peut les modifier pour les dépôts créés à partir de ce moment-là. Les dépôts existants conservent leur propre réglage (Dépôt → Paramètres), et une branche dont la pull request a été fusionnée auparavant n’est pas touchée.

Commits signés lors de la fusion

Si les commits signés sont exigés sur une branche, le commit de fusion est signé par l’utilisateur qui effectue la fusion, avec sa clé de signature SSH ou GPG enregistrée. Voir Sécurité et chaîne d’approvisionnement.

Références aux tickets et aux PR dans la CI

Les exécutions de workflow sont liées à la PR qui les a déclenchées. Depuis une PR, cliquez sur l’onglet Checks pour voir toutes les exécutions de workflow du commit de tête de la PR. Depuis une exécution de workflow, la PR qui l’a déclenchée est liée dans le résumé de l’exécution.

Références entre dépôts

Faites référence à des tickets et des PR d’autres dépôts en utilisant le slug complet : <org>/<repo>#<number> (par exemple acme/backend#42). Les références entre dépôts créent une mention liée dans les deux tickets.

Fermer des tickets via une PR

Utilisez des mots-clés dans la description de la PR ou dans les commits : Closes #42, Fixes #42, Resolves #42. Le ticket référencé se ferme automatiquement lorsque la PR est fusionnée dans la branche par défaut. Pour les autres branches, le ticket se ferme lorsque cette branche devient la branche par défaut du dépôt.

Rappels d’échéance

fremforge vous envoie des e-mails au sujet des tickets dotés d’une date d’échéance, comme le fait GitLab. Forgejo enregistre la date d’échéance d’un ticket mais n’envoie jamais rien à ce sujet.

  • La veille de l’échéance d’un ticket, les personnes qui y sont assignées reçoivent un rappel. Si personne n’est assigné, c’est la personne qui a ouvert le ticket qui le reçoit.
  • Une fois l’échéance dépassée, le rappel se répète au plus une fois par semaine, pendant quatre semaines au maximum après la date d’échéance.
  • Un e-mail par jour au maximum. Tout ce qui arrive à échéance le lendemain et tout ce qui est en retard est regroupé dans un seul e-mail, en deux sections : Échéance demain et En retard. Chaque élément renvoie au ticket et indique sa date d’échéance.
  • Quels tickets : les tickets ouverts, et non les pull requests, dans les dépôts de vos organisations. Les tickets fermés, les dépôts archivés et les dépôts d’un espace de noms personnel ne sont pas inclus.
  • Horaire : l’e-mail part à 05:15 UTC (07:15 à Copenhague en été, 06:15 en hiver). « Demain » désigne le jour calendaire suivant à Copenhague. La date d’échéance est celle que Forgejo affiche sur le ticket.
  • Accès : vous ne recevez de rappels que pour les dépôts que vous pouvez encore lire au moment de l’envoi de l’e-mail. Si vous perdez l’accès à un dépôt après y avoir été assigné, ses tickets disparaissent de vos rappels.
  • Langue : l’e-mail est rédigé dans la langue que vous avez choisie dans Forgejo, parmi l’anglais, le danois, l’allemand, le français, le néerlandais, le norvégien et le suédois. Les autres langues reçoivent l’anglais.
  • Qui est exclu : les bots, les comptes désactivés et les comptes sans adresse e-mail vérifiée.

Pour arrêter les rappels, désactivez Rappels d’échéance des tickets pour une organisation dans les paramètres de notification, ou utilisez le lien de désinscription en un clic en bas de n’importe quel rappel, qui les désactive pour toutes les organisations couvertes par ce rappel. Pour les réactiver, passez par les paramètres de notification.

Export de données

Tous les tickets et toutes les PR sont inclus dans le bundle d’export complet des données de l’organisation. Voir Export de données.

Références croisées