Zum Hauptinhalt springen

Issues und Pull Requests

Issues und PRs sind in fremforge Standardfunktionen von Forgejo. Den vollen Funktionsumfang beschreibt die Forgejo-Dokumentation. Diese Seite behandelt die Richtlinien und Integrationen, die fremforge hinzufügt.

Audit-Logging

Jede Zustandsänderung an einem Issue oder PR (Öffnen, Schließen, Wiedereröffnen, Label-Änderung, Änderung der zugewiesenen Person, abgegebenes Review, Merge) wird im Audit-Log der Organisation erfasst. Die Einträge enthalten den Akteur, den Zeitstempel, das Repository und die Aktion. Du findest sie unter Organisationsverwaltung → Audit-Log oder über die API.

PR-Merge-Gates und Branch-Schutz

PRs in geschützte Branches müssen alle konfigurierten Regeln für den Branch-Schutz erfüllen, bevor der Merge-Button aktiv wird. Wie du die Regeln konfigurierst, steht unter Organisationsverwaltung.

Review-Vorschläge übernehmen

Forgejo stellt Codeblöcke vom Typ ```suggestion in Review-Kommentaren eines PR dar. fremforge ergänzt dazu einen Button Apply suggestion, mit dem du einen Vorschlag mit einem Klick übernimmst, genau wie in GHEC. Klicke ihn bei einem beliebigen Vorschlagskommentar an, und der vorgeschlagene Code wird im Head-Commit des PR in die Datei eingefügt, zugeschrieben der Person, die geklickt hat.

So funktioniert es:

  1. Der Button erscheint bei jedem Review-Kommentar, der einen Codeblock ```suggestion enthält. Einzeilige und mehrzeilige Vorschläge funktionieren beide.
  2. Wer den Vorschlag übernimmt, braucht die Berechtigung write oder admin auf dem Repository. Mitarbeitende mit reinem Lesezugriff sehen den Button nicht.
  3. fremforge prüft, dass der PR noch offen ist und der Head-SHA dem SHA zum Zeitpunkt der Darstellung des Vorschlags entspricht. Wurde nach der Darstellung ein Force-Push auf den PR gemacht, schlägt das Übernehmen mit 409 fehl, und du wirst gebeten, die Seite neu zu laden. So überschreibt ein veralteter Vorschlag keine neuere Arbeit.
  4. Autor des Commits ist die Person, die den Vorschlag übernimmt (kein Dienstkonto von fremforge), genau wie in GHEC.
  5. Die Aktion wird im Audit-Log der Organisation als pr.suggestion.applied erfasst, mit PR-Nummer, Dateipfad, Zeilenbereich und ID des Review-Kommentars.

Die Unterhaltung nach dem Übernehmen aufzulösen ist ein manueller Schritt (klicke in der Review-Oberfläche von Forgejo auf Resolve). fremforge löst sie nicht automatisch auf, weil sich der Resolve-Endpunkt und das Modell der Review-Threads in Forgejo in Details von GitHub unterscheiden und wir hier lieber weniger versprechen.

Auto-Merge

PRs lassen sich so einstellen, dass sie automatisch gemergt werden, sobald alle erforderlichen Checks bestanden sind. Du schaltest das am PR ein: Klicke auf das Dropdown neben Merge → Enable auto-merge. Wähle die Merge-Strategie (Merge-Commit, Squash, Rebase).

Neue Commits auf den PR zu pushen, beendet den Auto-Merge nicht. Der PR bleibt eingeplant und wird gemergt, sobald die erforderlichen Checks auf dem neuen Head-Commit bestanden sind; Ergebnisse eines früheren Commits zählen nicht. Das gilt gleichermaßen für Branches mit und ohne Merge-Queue. Verwirft die Regel für den Branch-Schutz veraltete Freigaben, entfernt ein Push auch die vorhandenen Freigaben, und der PR wartet vor dem Merge auf eine neue.

Um einen eingeplanten PR am Mergen zu hindern, etwa bevor du eine Änderung pushst, die du noch prüfen willst, brich den Auto-Merge am PR ab oder rufe DELETE /api/v1/repos/{owner}/{repo}/pulls/{index}/merge auf. Schaltest du ihn später wieder ein, wird der Merge neu eingeplant.

Merge-Queue

Ein geschützter Branch kann eine Merge-Queue verwenden (die Einstellung merge_queue seiner Regel für den Branch-Schutz). Ist die Queue an, stellt das Einschalten von Auto-Merge den PR in die Queue, und die Queue testet ihn in einer Merge-Gruppe: dem Ziel-Branch plus den PRs, die in der Queue vor ihm stehen, plus diesem PR. Workflows, die auf merge_group auslösen, laufen auf diesem Commit und melden Status der Form … (merge_group). Ein erforderlicher Check X (pull_request) ist durch das passende Ergebnis X (merge_group) erfüllt. Nimm merge_group also in die Auslöser der Workflows hinter deinen erforderlichen Checks auf.

Welcher Build zählt, während ein PR in der Queue steht

  • Der Lauf der Merge-Gruppe ist der Build des PR. Kommt der PR in eine Merge-Gruppe, werden seine laufenden pull_request-Läufe jedes Workflows abgebrochen, der auch auf merge_group auslöst, damit derselbe Workflow nicht zweimal baut. Am PR lauten diese Checks dann Superseded by the merge queue und übernehmen das Ergebnis der Merge-Gruppe.
  • Workflows ohne Auslöser merge_group laufen am PR weiter, und ihre Ergebnisse zählen wie bisher. Ein Job, den die Merge-Gruppe überspringt (zum Beispiel mit einem if:, das merge_group ausschließt), ersetzt den eigenen Check des PR ebenfalls nicht; darüber entscheidet der eigene Lauf des PR.
  • Wer die Queue verlässt, bekommt die normalen Checks zurück. Schlägt die Merge-Gruppe fehl und wird der PR aus der Queue entfernt, oder wird der Auto-Merge abgebrochen, laufen die abgebrochenen pull_request-Läufe erneut auf dem Commit des PR. Ein neuer Push bekommt wie immer eigene pull_request-Läufe für den neuen Commit.
  • Ein Push nimmt einen PR aus der Queue, nicht aus dem Auto-Merge. Der PR behält seinen Auto-Merge und stellt sich hinten wieder an, sobald seine Checks auf dem neuen Commit bestanden sind. Brich den Auto-Merge ab, wenn er nicht gemergt werden soll.
  • Eine fehlgeschlagene Merge-Gruppe mergt den PR nie. Der Status fremforge/merge-queue des PR lautet dann Merge group failed — removed from the merge queue, ein Kommentar am PR nennt den Grund, und der fehlgeschlagene Lauf steht in der Actions-Liste des Repositorys als merge_group-Lauf.

Wann die Queue den Auto-Merge abbricht

Entfernt die Queue einen PR und würde ihn nichts von selbst zurückbringen, kann sie auch seinen Auto-Merge abbrechen. Dann mergt ein späterer Push, der die Checks grün macht, den PR nicht, bevor ihn sich jemand noch einmal angesehen hat. Das gilt, wenn:

  • einer der eigenen erforderlichen Checks des PR fehlschlägt, während er in der Queue steht;
  • seine Merge-Gruppe fehlschlägt, in ein Timeout läuft oder mit den PRs vor ihm in Konflikt gerät, nachdem die automatischen Wiederholungen bei einer Bewegung von main aufgebraucht sind;
  • seine eigenen Checks ein zweites Mal über das Timeout der Queue hinaus ausstehen;
  • die Queue eine seiner neuen Migrationen nicht in die richtige Reihenfolge umbenennen kann (siehe das Opt-in .forgejo/merge-queue-restamp).

Ein PR, der sich ohnehin von selbst wieder anstellt, behält seinen Auto-Merge: solange eine Wiederholung ansteht, nach einem Push, als Entwurf oder nachdem er seine Freigaben verloren hat. Dasselbe gilt für einen PR, dessen Auto-Merge ein Bot wie Renovate eingeschaltet hat. Der Abbruch erscheint am PR als auto merge cancelled durch forgejo-actions. Ein Kommentar nennt den Grund, und der Status fremforge/merge-queue endet mit Auto-merge cancelled.

Erneut scharf schalten: Behebe, was den PR entfernt hat, und schalte den Auto-Merge wieder ein. Nutze dazu den Button Auto merge when checks succeed am PR oder die 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}'

Der PR kommt dann in die Queue, sobald seine eigenen Checks bestanden sind.

Die Einstellung. merge_queue_disarm_on_removal in der Regel für den Branch-Schutz ist default, on oder off. Du setzt sie über die API für den Branch-Schutz (PATCH /api/v1/repos/<org>/<repo>/branch_protections/<rule>). merge_queue_disarm_on_removal_effective in der Antwort sagt, ob sie greift. Für Kundenorganisationen bedeutet default derzeit off, sodass der Auto-Merge wie bisher eine Entfernung übersteht. Setze on, um ein Repository einzubeziehen.

Priorität in der Queue

Die Queue testet PRs in der Reihenfolge, in der sie sich angestellt haben. Um einen PR vorzuziehen, zum Beispiel einen Fix für ein kaputtes main oder einen Hotfix, gib ihm die Priorität high. Ein PR mit hoher Priorität kommt vor jeden normalen PR, der noch in keiner Merge-Gruppe ist. Eine bereits laufende Merge-Gruppe hält er nie an und baut sie auch nicht neu; er wartet auf die laufenden Gruppen und ist dann als Nächster dran. Zwei PRs mit hoher Priorität behalten die Reihenfolge, in der sie sich angestellt haben.

Setze die Priorität beim Einschalten des Auto-Merge oder später, während der PR in der Queue steht:

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

Ein GET auf denselben Pfad zeigt die Priorität des PR, wer sie gesetzt hat, seinen Platz in der Queue und die Länge der Queue. DELETE setzt sie auf normal zurück.

  • Wer sie setzen darf: jeder, der den PR mergen darf, also mit Schreibzugriff auf das Repository und, falls die Regel eine hat, einem Platz auf der Merge-Allowlist des Branches. Alle anderen bekommen 403.
  • Sie gehört zum Auto-Merge. Den Auto-Merge abzubrechen oder erneut einzuschalten setzt den PR auf normal zurück. Eine Priorität auf einem PR ohne Auto-Merge zu setzen, wird mit 409 beantwortet.
  • Jede Änderung wird festgehalten. Ein Kommentar am PR nennt, wer die Priorität von was auf was geändert hat, und den Grund, falls einer angegeben wurde (bis zu 200 Zeichen).

Nutze die hohe Priorität für den PR, auf den andere warten, nicht als Standard. Haben alle PRs hohe Priorität, geht die Queue wieder nach der Reihenfolge des Anstellens.

Merge-Strategien

Merge-Commit, Squash-Merge und Rebase-Merge sind pro Repository verfügbar. Die erlaubten Strategien und den Standard wählst du unter Repository → Einstellungen → Einheiten → Pull-Requests (Merge-Stile, Standard-Mergeverhalten). Owner der Organisation legen die Standard-Merge-Methode für neue Repositorys unter Organisationsverwaltung → Sicherheit → Richtlinien → Repository-Regeln fest (Standard-Merge-Methode); jedes Repository kann sie überschreiben.

Ein neues Repository löscht den Branch eines Pull Requests beim Merge und mergt standardmäßig per Squash. fremforge setzt beides beim Anlegen des Repositorys, aus der Baseline der Organisation unter Organisation › Repositorys (/<org>/_admin/repos-overview#org-baseline), wo ein Owner der Organisation sie für ab dann angelegte Repositorys ändern kann. Bestehende Repositorys behalten ihre eigene Einstellung (Repository → Einstellungen), und ein Branch, dessen Pull Request früher gemergt wurde, bleibt unangetastet.

Signierte Commits beim Merge

Sind auf einem Branch signierte Commits vorgeschrieben, wird der Merge-Commit von der Person signiert, die den Merge ausführt, mit ihrem hinterlegten SSH- oder GPG-Signaturschlüssel. Siehe Sicherheit und Lieferkette.

Verweise auf Issues und PRs in CI

Workflow-Läufe sind mit dem PR verknüpft, der sie ausgelöst hat. Klicke in einem PR auf den Tab Checks, um alle Workflow-Läufe für den Head-Commit des PR zu sehen. In einem Workflow-Lauf ist der auslösende PR in der Zusammenfassung des Laufs verlinkt.

Verweise über Repositorys hinweg

Verweise auf Issues und PRs in anderen Repositorys mit dem vollständigen Slug: <org>/<repo>#<number> (z. B. acme/backend#42). Verweise über Repositorys hinweg erzeugen in beiden Issues eine verknüpfte Erwähnung.

Issues per PR schließen

Verwende Schlüsselwörter im Text des PR oder in Commits: Closes #42, Fixes #42, Resolves #42. Das referenzierte Issue wird automatisch geschlossen, wenn der PR in den Standard-Branch gemergt wird. Bei anderen Branches wird das Issue geschlossen, sobald dieser Branch als Standard-Branch des Repositorys gesetzt wird.

Erinnerungen an Fälligkeitsdaten

fremforge schickt dir wie GitLab E-Mails zu Issues mit Fälligkeitsdatum. Forgejo speichert das Fälligkeitsdatum eines Issues, verschickt dazu aber nie etwas.

  • Am Tag vor der Fälligkeit eines Issues bekommen die zugewiesenen Personen eine Erinnerung. Ist niemand zugewiesen, bekommt sie die Person, die das Issue eröffnet hat.
  • Sobald es überfällig ist, wiederholt sich die Erinnerung höchstens einmal pro Woche, bis zu vier Wochen nach dem Fälligkeitsdatum.
  • Höchstens eine E-Mail pro Tag. Alles, was morgen fällig ist, und alles Überfällige wird in einer E-Mail mit zwei Abschnitten gesammelt: Morgen fällig und Überfällig. Jeder Eintrag verlinkt auf das Issue und zeigt sein Fälligkeitsdatum.
  • Welche Issues: offene Issues, keine Pull Requests, in den Repositorys deiner Organisationen. Geschlossene Issues, archivierte Repositorys und Repositorys in einem persönlichen Namensraum sind nicht dabei.
  • Zeitpunkt: Die E-Mail geht um 05:15 UTC raus (in Kopenhagen 07:15 im Sommer, 06:15 im Winter). „Morgen“ ist der nächste Kalendertag in Kopenhagen. Das Fälligkeitsdatum ist das Datum, das Forgejo am Issue anzeigt.
  • Zugriff: Du bekommst nur Erinnerungen zu Repositorys, die du beim Versand der E-Mail noch lesen kannst. Verlierst du nach der Zuweisung den Zugriff auf ein Repository, fallen dessen Issues aus deinen Erinnerungen heraus.
  • Sprache: Die E-Mail kommt in der Sprache, die du in Forgejo gewählt hast, auf Englisch, Dänisch, Deutsch, Französisch, Niederländisch, Norwegisch oder Schwedisch. Andere Sprachen bekommen Englisch.
  • Wer ausgelassen wird: Bots, deaktivierte Konten und Konten ohne bestätigte E-Mail-Adresse.

Um die Erinnerungen abzustellen, schalte Erinnerungen an Fälligkeitsdaten von Issues für eine Organisation in den Benachrichtigungseinstellungen aus, oder nutze den Abmeldelink unten in jeder Erinnerung, der sie mit einem Klick für alle Organisationen abschaltet, die die Erinnerung abgedeckt hat. Wieder einschalten kannst du sie in den Benachrichtigungseinstellungen.

Datenexport

Alle Issues und PRs sind im vollständigen Datenexport-Bundle der Organisation enthalten. Siehe Datenexport.

Querverweise