Merge-holds

En merge-hold stopper merges til én branch, af en bestemt grund, indtil et bestemt tidspunkt. Brug en til at skære et release-tog, under en hændelse eller ved en migrering, der ikke må komme i konflikt med andre ændringer. Release-tog sætter og ophæver deres egne holds (source: train), som ejes af togets ejer.

En hold dækker én af disse:

• alle organisationens repositories;
• en liste af repositories (op til 50);
• ét repository.

Den gælder altid for én branch, main, medmindre du angiver en anden.

Sådan stopper en hold en merge

fremforge sætter en commit-status, fremforge/hold, på head-commit’en i hver åben pull request til en branch med en hold:

På en branch, hvor fremforge/hold er et påkrævet check, stopper en pending hold enhver måde at merge på:

• Merge-knappen og API’ets merge-endpoint afviser med “Not all required status checks successful”.
• Auto-merge venter. Når holden ophæves, skifter statussen til success, og enhver pull request, der er sat til at blive merget, merges da. En pull request, der sættes til auto-merge under en frysning, lander efter den.
• Merge-køen holder pull requesten ude af en merge-gruppe. Varer holden længere end køens timeout for checks, parkerer køen pull requesten og sætter den tilbage én gang, når dens checks er grønne igen.

Pusher du til en pull request under en hold, eller åbner du en ny, får den statussen inden for få sekunder. Et afstemningsjob reparerer hvert 5. minut enhver status, der mangler, er forældet eller er sat af en anden.

Holds fejler lukket. Hvis fremforge ikke kan sætte statussen, venter en ny pull request til en branch med håndhævede holds, indtil det kan.

I konsollen

Organisationens ejere administrerer holds under Byg og udrul → Merge-holds (https://frem.sh/<org>/_admin/merge-holds): de aktive holds med ejer, udløb og hvor merge-knappen venter, knapper til at ophæve, forlænge eller slippe én pull request igennem, en formular til at sætte en hold, kontakterne til håndhævelse og de holds, der er afsluttet for nylig. Alt på siden findes også i API’et nedenfor.

Slå håndhævelse til

At kræve fremforge/hold er et tilvalg, pr. repository eller for hele organisationen, pr. branch. Indtil du vælger det til, vises holds og læses af værktøjer, men merge-knappen venter ikke 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 er et repositorynavn eller * for alle repositories, også dem, der oprettes senere. Tokenet skal have policy:write.

Når du vælger det til, sætter fremforge først fremforge/hold på alle åbne pull requests til branchen. Først derefter tilføjer det checket til branchens beskyttelsesregel. Ingen pull request venter nogensinde på et check, som intet har sat.

Svaret indeholder:

• required_on: repositories, hvor checket nu er påkrævet.
• unprotected: repositories, hvis branch ikke har en beskyttelsesregel. fremforge opretter ikke en; tilføj en regel, så kræver afstemningsjobbet checket inden for 5 minutter.
• failed: repositories, hvis pull requests ikke kunne læses. Deres regel lades i fred, og jobbet prøver igen.

Vil du fravælge det, så send samme body med DELETE. fremforge fjerner checket overalt, hvor intet andet tilvalg stadig dækker repositoriet.

Sæt 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
      }'

Tokenet skal have deployments:write, det scope, der også sætter udrulninger på pause. At læse holds kræver deployments:read.

Ejer

Hver hold tilhører en person. Når du, eller en agent, der handler på dine vegne, sætter en hold, er du dens ejer. Et token, der ikke handler på vegne af en person, for eksempel et CI-token, skal angive owner.

Udløb og alarmen

Ingen hold blokerer for evigt. Når en hold når sit udløb, ophæver fremforge den inden for 5 minutter, registrerer merge_hold.expired i revisionsloggen og sender ejeren en e-mail. Skal merges fortsat holdes tilbage, så forlæng den inden da:

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

Vis og ophæ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"}'

Tilføj ?state=all til listen for at få ophævede holds med. Pull requests under en hold skifter til success få sekunder efter en ophævelse.

At sætte og ophæve en hold vises også i hændelsesstrømmen som hold.placed og hold.released, én hændelse pr. repository, holden dækker.

AI-assistenter, der er forbundet via fremforges MCP-server, kan vise holds med værktøjet list_merge_holds.

Tilsidesættelse for administratorer

Der findes to tilsidesættelser, og begge registreres i revisionsloggen:

• Ophæv en andens hold. Enhver ejer af organisationen kan ophæve enhver hold. Når ejeren af holden ophæver den, registrerer revisionsloggen merge_hold.released. Når en anden gør det, registreres merge_hold.override.
• Slip én pull request igennem. Til et hotfix under en frysning kan du undtage en enkelt pull request. Dens status skifter til success, og holden gælder fortsat for alt andet. En begrundelse er påkrævet. Revisionsloggen registrerer 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 repository-administrator kan stadig merge manuelt, hvor branchreglen ikke gælder for administratorer. Det er nødudgangen, og Forgejo registrerer det som enhver anden merge.

Frysninger af releases fra et issue

Hvis dit team fryser et repository ved at åbne et issue med labelen release-freeze, virker det fortsat. I et repository, hvor håndhævelse er slået til, gør fremforge hvert åbent release-freeze-issue til en hold på det repository:

• issuets forfatter ejer den;
• begrundelsen er issuets titel;
• lukker du issuet eller fjerner labelen, ophæves den inden for få sekunder.

Så nu respekterer merge-knappen også frysningen. En frysning har ikke selv et sluttidspunkt, så dens hold løber 24 timer ad gangen: mens issuet er åbent, fornyer fremforge holden, når den udløber, og sender ejeren en e-mail om, at frysningen stadig er aktiv.

Hvad en hold ikke gør

• Den stopper ikke direkte push til branchen. Brug branchbeskyttelse til at kræve pull requests.
• Den stopper ikke udrulninger. Sæt et udrulningsmiljø på pause til det.
• Alle med skriveadgang til et repository kan sætte en commit-status under et hvilket som helst navn. fremforge sætter fremforge/hold tilbage og registrerer merge_hold.status_foreign i revisionsloggen, når en anden sætter den. Det lukker hullet inden for sekunder til minutter, ikke øjeblikkeligt.

Revisionshændelser