Naar de hoofdinhoud

Issues en pull requests

Issues en pull requests zijn in fremforge standaardfuncties van Forgejo. De Forgejo-documentatie is de referentie voor alle functies. Deze pagina behandelt het beleid en de integraties die specifiek zijn voor fremforge.

Auditlogging

Elke statuswijziging van een issue of pull request (openen, sluiten, heropenen, labels wijzigen, toegewezen persoon wijzigen, review indienen, mergen) wordt vastgelegd in het auditlog van de organisatie. Elke regel bevat de uitvoerder, het tijdstip, de repository en de actie. Je vindt het onder Organisatiebeheer → Auditlog of via de API.

Merge-gates en branchbeveiliging voor pull requests

Pull requests naar beveiligde branches moeten aan alle ingestelde regels voor branchbeveiliging voldoen voordat de mergeknop actief wordt. Zie Organisatiebeheer voor het instellen van de regels.

Reviewsuggesties toepassen

Forgejo toont codeblokken ```suggestion in reviewopmerkingen van pull requests. fremforge voegt daar een knop Apply suggestion aan toe die met één klik werkt, met dezelfde werking als in GHEC. Klik erop bij een opmerking met een suggestie en de voorgestelde code wordt in het bestand gezet op de head-commit van de pull request, op naam van de gebruiker die klikte.

Zo werkt het:

  1. De knop verschijnt bij elke reviewopmerking met een codeblok ```suggestion. Suggesties van één regel en van meerdere regels werken allebei.
  2. De gebruiker die de suggestie toepast, moet schrijf- of beheerrechten op de repository hebben. Medewerkers met alleen leestoegang zien de knop niet.
  3. fremforge controleert dat de pull request nog open is en dat de head-SHA gelijk is aan de SHA van het moment waarop de suggestie werd getoond. Is er na het tonen van de suggestie een force-push gedaan, dan mislukt het toepassen met een 409 en wordt de gebruiker gevraagd de pagina te vernieuwen. Zo overschrijft een verouderde suggestie geen nieuwer werk.
  4. De auteur van de commit is de gebruiker die de suggestie toepast (geen serviceaccount van fremforge), precies zoals in GHEC.
  5. De actie wordt in het auditlog van de organisatie vastgelegd als pr.suggestion.applied, met het nummer van de pull request, het bestandspad, het regelbereik en de id van de reviewopmerking.

Het gesprek oplossen na het toepassen doe je zelf (klik op Resolve in de reviewweergave van Forgejo). fremforge doet dat niet automatisch, omdat het resolve-endpoint en het model van reviewthreads in Forgejo net iets anders werken dan bij GitHub, en we hier liever niet te veel beloven.

Auto-merge

Je kunt pull requests automatisch laten mergen zodra alle verplichte checks slagen. Zet het aan op de pull request: klik op het dropdownmenu naast Merge → Enable auto-merge. Kies de mergestrategie (merge commit, squash, rebase).

Nieuwe commits naar de pull request pushen annuleert auto-merge niet. De pull request blijft ingepland en merget zodra de verplichte checks slagen op de nieuwe head-commit; resultaten van een eerdere commit tellen niet. Dat geldt voor branches met en zonder merge queue. Trekt de branchbeveiligingsregel verouderde goedkeuringen in, dan wist een push ook bestaande goedkeuringen en wacht de pull request op een nieuwe goedkeuring voordat hij merget.

Wil je voorkomen dat een ingeplande pull request merget, bijvoorbeeld voordat je een wijziging pusht die je nog wilt reviewen, annuleer dan auto-merge op de pull request of roep DELETE /api/v1/repos/{owner}/{repo}/pulls/{index}/merge aan. Zet je het later weer aan, dan wordt de merge opnieuw ingepland.

Merge queue

Een beveiligde branch kan een merge queue gebruiken (de instelling merge_queue van de branchbeveiligingsregel). Staat de queue aan, dan zet auto-merge aanzetten de pull request in de queue, en test de queue hem in een merge group: de doelbranch, plus de pull requests die vóór hem in de queue staan, plus deze pull request. Workflows die op merge_group starten, draaien op die commit en melden statussen … (merge_group). Een verplichte check X (pull_request) wordt vervuld door het bijbehorende resultaat X (merge_group), dus voeg merge_group toe aan de triggers van de workflows achter je verplichte checks.

Welke build telt terwijl een pull request in de queue staat

  • De run van de merge group is de build van de pull request. Komt de pull request in een merge group, dan worden zijn lopende pull_request-runs geannuleerd van elke workflow die ook op merge_group start, zodat dezelfde workflow niet twee keer bouwt. Op de pull request staat bij die checks Superseded by the merge queue en nemen ze het resultaat van de merge group over.
  • Workflows zonder merge_group-trigger blijven op de pull request draaien, en hun resultaten tellen zoals voorheen. Een job die de merge group overslaat (bijvoorbeeld met een if: die merge_group uitsluit), vervangt ook de eigen check van de pull request niet; die wordt bepaald door de eigen run van de pull request.
  • Verlaat de pull request de queue, dan komen de normale checks terug. Mislukt de merge group en wordt de pull request uit de queue gehaald, of wordt auto-merge geannuleerd, dan draaien de geannuleerde pull_request-runs opnieuw op de commit van de pull request. Een nieuwe push geeft de nieuwe commit zoals altijd zijn eigen pull_request-runs.
  • Een push haalt een pull request uit de queue, niet uit auto-merge. De pull request houdt zijn auto-merge en sluit achteraan weer aan in de queue zodra zijn checks op de nieuwe commit slagen. Annuleer auto-merge als hij niet mag mergen.
  • Een mislukte merge group merget de pull request nooit. De status fremforge/merge-queue van de pull request luidt Merge group failed — removed from the merge queue, een opmerking op de pull request legt uit waarom, en de mislukte run staat in de Actions-lijst van de repository als merge_group-run.

Wanneer de queue auto-merge annuleert

Haalt de queue een pull request eruit en zou niets hem vanzelf terugbrengen, dan kan de queue ook de auto-merge van de pull request annuleren. Een latere push die de checks groen maakt, merget de pull request dan niet voordat iemand er opnieuw naar heeft gekeken. Dat gebeurt als:

  • een van de eigen verplichte checks van de pull request mislukt terwijl hij in de queue staat;
  • zijn merge group mislukt, een time-out krijgt of conflicteert met de pull requests vóór hem, nadat de automatische nieuwe pogingen bij het verschuiven van main op zijn;
  • zijn eigen checks voor de tweede keer na de time-out van de queue nog in behandeling zijn;
  • de queue een van zijn nieuwe migraties niet in de juiste volgorde kan hernoemen (zie de opt-in .forgejo/merge-queue-restamp).

Een pull request die nog vanzelf terugkomt, houdt zijn auto-merge: als er nog een nieuwe poging gepland staat, na een push, als concept, of na het verlies van zijn goedkeuringen. Dat geldt ook voor een pull request waarvan een bot zoals Renovate de auto-merge heeft aangezet. Het annuleren verschijnt op de pull request als auto merge cancelled door forgejo-actions. Een opmerking legt uit waarom, en de status fremforge/merge-queue eindigt op Auto-merge cancelled.

Opnieuw inschakelen: los op waardoor de pull request eruit is gehaald en zet auto-merge daarna weer aan. Gebruik de knop Auto merge when checks succeed op de pull request, of de 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}'

De pull request sluit dan aan in de queue zodra zijn eigen checks slagen.

De instelling. merge_queue_disarm_on_removal op de branchbeveiligingsregel is default, on of off. Stel hem in met de API voor branchbeveiliging (PATCH /api/v1/repos/<org>/<repo>/branch_protections/<rule>). merge_queue_disarm_on_removal_effective in het antwoord geeft aan of hij van toepassing is. Voor klantorganisaties betekent default op dit moment uit, dus de auto-merge blijft na verwijdering staan zoals voorheen. Zet hem op on om een repository mee te laten doen.

Prioriteit in de queue

De queue test pull requests in de volgorde waarin ze zijn aangesloten. Wil je er één naar voren halen, bijvoorbeeld een fix voor een kapotte main of een hotfix, geef hem dan hoge prioriteit. Een pull request met hoge prioriteit gaat vóór elke normale pull request die nog niet in een merge group zit. Hij stopt of herbouwt nooit een merge group die al draait; hij wacht dus op de groepen die lopen en is daarna aan de beurt. Twee pull requests met hoge prioriteit houden de volgorde waarin ze aansloten.

Stel de prioriteit in wanneer je auto-merge aanzet, of later terwijl de pull request in de queue staat:

# 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"}'

GET op hetzelfde pad toont de prioriteit van de pull request, wie die heeft ingesteld, de plaats in de queue en de lengte van de queue. DELETE zet hem terug op normaal.

  • Wie het mag instellen: iedereen die de pull request mag mergen, dus met schrijftoegang tot de repository, plus een plek op de merge-allowlist van de branch als de regel er een heeft. Ieder ander krijgt 403.
  • Het hoort bij de auto-merge. Auto-merge annuleren of opnieuw aanzetten zet de pull request terug op normaal. Een prioriteit instellen op een pull request zonder auto-merge geeft 409.
  • Elke wijziging wordt vastgelegd. Een opmerking op de pull request vermeldt wie de prioriteit heeft gewijzigd, van wat naar wat, en de reden als die is opgegeven (maximaal 200 tekens).

Gebruik hoge prioriteit voor de pull request waarop anderen wachten, niet als standaard. Heeft elke pull request hoge prioriteit, dan werkt de queue weer gewoon in volgorde van aansluiten.

Mergestrategieën

Merge commit, squash merge en rebase merge zijn per repository allemaal beschikbaar. Kies de toegestane strategieën en de standaard onder Repository → Instellingen → Onderdelen → Pull requests (Samenvoegstijl, Standaard samenvoegstijl). Eigenaren van een organisatie stellen de standaard merge-methode voor nieuwe repository’s in onder Organisatiebeheer → Beveiliging → Beleid → Repositoryregels (Standaard merge-methode); elke repository kan die overschrijven.

Een nieuwe repository verwijdert de branch van een pull request zodra die merget, en gebruikt standaard squash merge. fremforge stelt beide in wanneer de repository wordt aangemaakt, op basis van de basisinstellingen van de organisatie onder Organisatie › Repositories (/<org>/_admin/repos-overview#org-baseline). Daar kan een eigenaar van de organisatie ze wijzigen voor repository’s die vanaf dat moment worden aangemaakt. Bestaande repository’s houden hun eigen instelling (Repository → Instellingen), en een branch waarvan de pull request eerder is gemerged, blijft ongemoeid.

Ondertekende commits bij een merge

Zijn ondertekende commits op een branch verplicht, dan wordt de merge-commit ondertekend door de gebruiker die merget, met diens geregistreerde SSH- of GPG-ondertekeningssleutel. Zie Beveiliging en supply chain.

Verwijzingen naar issues en pull requests in CI

Workflowruns zijn gekoppeld aan de pull request die ze heeft gestart. Klik vanuit een pull request op het tabblad Checks om alle workflowruns voor de head-commit van de pull request te zien. Vanuit een workflowrun is de pull request die hem startte gelinkt in de samenvatting van de run.

Verwijzingen tussen repository’s

Verwijs naar issues en pull requests in andere repository’s met de volledige slug: <org>/<repo>#<number> (bijvoorbeeld acme/backend#42). Zo’n verwijzing maakt in beide issues een gekoppelde vermelding aan.

Issues sluiten via een pull request

Gebruik trefwoorden in de beschrijving van de pull request of in commits: Closes #42, Fixes #42, Resolves #42. Het genoemde issue wordt automatisch gesloten wanneer de pull request in de standaardbranch merget. Bij andere branches wordt het issue gesloten zodra die branch de standaardbranch van de repository wordt.

Herinneringen aan vervaldatums

fremforge mailt je over issues met een vervaldatum, zoals GitLab dat doet. Forgejo slaat de vervaldatum van een issue wel op, maar stuurt er nooit iets over.

  • De dag voordat een issue vervalt, krijgen de toegewezen personen een herinnering. Is niemand toegewezen, dan krijgt de persoon die het issue heeft geopend hem.
  • Zodra het te laat is, wordt de herinnering hoogstens één keer per week herhaald, tot vier weken na de vervaldatum.
  • Hoogstens één e-mail per dag. Alles wat morgen vervalt en alles wat te laat is, wordt in één e-mail verzameld, in twee onderdelen: Verloopt morgen en Te laat. Elk item linkt naar het issue en toont de vervaldatum.
  • Welke issues: open issues, geen pull requests, in de repository’s van je organisaties. Gesloten issues, gearchiveerde repository’s en repository’s in een persoonlijke namespace tellen niet mee.
  • Tijdstip: de e-mail gaat om 05:15 UTC de deur uit (07:15 in Kopenhagen in de zomer, 06:15 in de winter). “Morgen” is de volgende kalenderdag in Kopenhagen. De vervaldatum is de datum die Forgejo bij het issue toont.
  • Toegang: je krijgt alleen herinneringen over repository’s die je op het moment van verzenden nog kunt lezen. Verlies je na het toewijzen de toegang tot een repository, dan verdwijnen de issues daarvan uit je herinneringen.
  • Taal: de e-mail is in de taal die je in Forgejo hebt gekozen: Engels, Deens, Duits, Frans, Nederlands, Noors of Zweeds. Bij andere talen krijg je Engels.
  • Wie wordt overgeslagen: bots, gedeactiveerde accounts en accounts zonder geverifieerd e-mailadres.

Wil je de herinneringen niet meer, zet dan Herinneringen aan vervaldatums van issues uit voor een organisatie in de meldingsinstellingen, of gebruik de afmeldlink onderaan een herinnering. Die zet ze in één klik uit voor elke organisatie waarover de herinnering ging. Weer aanzetten doe je in de meldingsinstellingen.

Data-export

Alle issues en pull requests zitten in de volledige data-exportbundel van de organisatie. Zie Data-export.

Kruisverwijzingen