Merge-holds

En merge-hold stoppar merges till en branch, av ett visst skäl, fram till en viss tid. Använd en vid kapning av ett release-tåg, en incident eller en migrering som inte får krocka med andra ändringar. Release-tåg sätter och häver sina egna holds (source: train), som ägs av tågets ägare.

En hold omfattar något av följande:

• alla repon i organisationen;
• en lista med repon (upp till 50);
• ett repo.

Den gäller alltid en branch, main om du inte anger en annan.

Hur en hold stoppar en merge

fremforge sätter en commit-status, fremforge/hold, på head-committen i varje öppen pull request till en branch som hålls tillbaka:

På en branch där fremforge/hold är en obligatorisk kontroll stoppar en hold i läget pending alla sätt att merga:

• Merge-knappen och API:ts merge-endpoint vägrar med “Not all required status checks successful”.
• Automatisk merge väntar. När holden hävs blir statusen success, och varje pull request som är inställd på att mergas mergas då. En pull request som ställs in under en frysning landar efter den.
• Merge-kön håller pull requesten utanför en landningsgrupp. Om holden varar längre än köns timeout för kontroller parkerar kön pull requesten och lägger tillbaka den en gång, när dess kontroller är gröna igen.

En push till en pull request under en hold, eller en ny pull request, får statusen inom några sekunder. Ett avstämningsjobb reparerar var 5:e minut varje status som saknas, är inaktuell eller har satts av någon annan.

Holds misslyckas i stängt läge. Om fremforge inte kan sätta statusen väntar en ny pull request till en branch med tillämpning tills det går.

I konsolen

Organisationsägare hanterar holds under Bygg och driftsätt → Merge-holds (https://frem.sh/<org>/_admin/merge-holds): de aktiva holdsen med ägare, slutdatum och var merge-knappen väntar, knappar för att häva, förlänga eller släppa igenom en pull request, ett formulär för att sätta en hold, reglagen för tillämpning och de holds som nyligen avslutats. Allt på sidan finns också i API:t nedan.

Slå på tillämpning

Att kräva fremforge/hold är frivilligt, per repo eller för hela organisationen, per branch. Tills du slår på det listas holds och läses av verktyg, men merge-knappen väntar inte på dem.

curl -X PUT https://frem.sh/_app/api/v1/orgs/<org>/merge-holds/enforcement \
  -H "Authorization: Bearer $FREMFORGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repo": "*", "branch": "main"}'

repo är ett reponamn, eller * för alla repon, även sådana som skapas senare. Token behöver policy:write.

När du slår på det sätter fremforge först fremforge/hold på varje öppen pull request till branchen. Först därefter läggs kontrollen till i branchens skyddsregel. Ingen pull request väntar någonsin på en kontroll som ingen har satt.

Svaret listar:

• required_on: repon där kontrollen nu är obligatorisk.
• unprotected: repon vars branch saknar skyddsregel. fremforge skapar ingen; lägg till en regel så gör avstämningsjobbet kontrollen obligatorisk inom 5 minuter.
• failed: repon vars pull requests inte kunde läsas. Deras regel lämnas orörd och jobbet försöker igen.

För att stänga av skickar du samma body med DELETE. fremforge tar bort kontrollen överallt där ingen annan aktivering fortfarande omfattar repot.

Sätt en hold

curl -X POST https://frem.sh/_app/api/v1/orgs/<org>/merge-holds \
  -H "Authorization: Bearer $FREMFORGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "repos": ["platform", "infrastructure-azure"],
        "reason": "Train 42 cut: no merges until the tst probe passes",
        "duration_minutes": 120
      }'

Token behöver deployments:write, samma scope som pausar driftsättningar. För att läsa holds behövs deployments:read.

Ägare

Varje hold tillhör en person. När du, eller en agent som agerar åt dig, sätter en hold är du dess ägare. En token som inte agerar för någon person, till exempel en CI-token, måste ange owner.

Slutdatum och larmet

Ingen hold blockerar för alltid. När en hold når sitt slutdatum häver fremforge den inom 5 minuter, registrerar merge_hold.expired i granskningsloggen och mejlar ägaren. Om merges måste fortsätta att hållas tillbaka förlänger du den innan dess:

curl -X PATCH https://frem.sh/_app/api/v1/orgs/<org>/merge-holds/<id> \
  -H "Authorization: Bearer $FREMFORGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"duration_minutes": 60}'

Lista och häv holds

# Live holds, and where enforcement is on
curl https://frem.sh/_app/api/v1/orgs/<org>/merge-holds \
  -H "Authorization: Bearer $FREMFORGE_TOKEN"

# Release one
curl -X POST https://frem.sh/_app/api/v1/orgs/<org>/merge-holds/<id>/release \
  -H "Authorization: Bearer $FREMFORGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"note": "Train 42 is out"}'

Lägg till ?state=all i listan för att ta med hävda holds. Pull requests som hölls tillbaka blir success inom några sekunder efter att holden hävts.

Att en hold sätts och hävs syns också i händelseflödet som hold.placed och hold.released, en händelse per repo som holden omfattar.

AI-assistenter som är anslutna via fremforges MCP-server kan lista holds med verktyget list_merge_holds.

Åsidosättande av administratör

Det finns två sätt att åsidosätta, och båda registreras i granskningsloggen:

• Häva någon annans hold. Varje organisationsägare kan häva vilken hold som helst. När ägaren häver den registrerar granskningsloggen merge_hold.released. När någon annan gör det registreras merge_hold.override.
• Släppa igenom en pull request. För en hotfix under en frysning undantar du en enskild pull request. Dess status blir success, och holden ligger kvar för allt annat. Ett skäl krävs. Granskningsloggen registrerar merge_hold.exempted.

curl -X POST https://frem.sh/_app/api/v1/orgs/<org>/merge-holds/<id>/exemptions \
  -H "Authorization: Bearer $FREMFORGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repo": "platform", "pr_number": 812, "reason": "INC-7 hotfix"}'

En repo-administratör kan fortfarande merga manuellt där branchregeln inte gäller administratörer. Det är nödutgången, och Forgejo registrerar den som vilken merge som helst.

Releasefrysningar från en issue

Om ditt team fryser ett repo genom att öppna en issue med etiketten release-freeze fungerar det fortfarande. I ett repo där tillämpning är påslagen gör fremforge varje öppen release-freeze-issue till en hold på det repot:

• issuens författare äger den;
• skälet är issuens titel;
• att stänga issuen, eller ta bort etiketten, häver den inom några sekunder.

Merge-knappen respekterar alltså nu också frysningen. En frysning har inget eget slutdatum, så dess hold gäller 24 timmar åt gången: medan issuen är öppen förnyar fremforge holden när den går ut och mejlar ägaren att frysningen fortfarande gäller.

Vad en hold inte gör

• Den stoppar inte direkta pushar till branchen. Använd branchskydd för att kräva pull requests.
• Den stoppar inte driftsättningar. Pausa en driftsättningsmiljö för det.
• Alla med skrivbehörighet till ett repo kan sätta en commit-status med vilket namn som helst. fremforge sätter tillbaka fremforge/hold och registrerar merge_hold.status_foreign i granskningsloggen när någon annan sätter den. Det stänger luckan inom sekunder till minuter, inte omedelbart.

Granskningshändelser