Hotfix-herkomst

Een hotfixbranch wordt gemaakt vanaf de release die in productie draait, en de fix wordt overgenomen van de standaardbranch. Hotfix-herkomst zorgt ervoor dat er verder niets op gebeurt. Op een branch die overeenkomt met je hotfixpatroon (standaard hotfix/*) moet elke commit:

1. een git cherry-pick -x zijn van een commit op de standaardbranch van de repository;
2. waarvan de gemergede pull request je fast-tracklabel draagt (standaard fast-track);
3. en waarvan de wijziging dezelfde is als die van de broncommit.

fremforge controleert elke commit van een pull request naar een hotfixbranch, en elke commit die naar een hotfixbranch wordt gepusht, en plaatst het resultaat als de commitstatus fremforge/hotfix-provenance: success, of failure met de eerste commit die niet slaagt en de reden. Je kunt er een verplichte check van maken.

Hotfix-herkomst staat standaard uit. Een eigenaar van de organisatie zet het aan via de API.

Een hotfix maken

# 1. Fix it on the default branch first, through a pull request with the label `fast-track`.
# 2. Cut the hotfix branch from the production tag and push it:
git switch -c hotfix/1.4.2 v1.4.1
git push -u origin hotfix/1.4.2
# 3. Carry the fix over on a branch of its own. -x writes the "(cherry picked from commit ...)" line:
git switch -c backport/login-fix
git cherry-pick -x <the commit the merge put on main>
git push -u origin backport/login-fix
# 4. Open a pull request from backport/login-fix into hotfix/1.4.2.

Cherry-pick de commit die de merge op de standaardbranch heeft gezet: de squashcommit, of de mergecommit (git cherry-pick -x -m 1 <merge>). fremforge vindt de pull request van de bron via die commit. Bij rebase-merges kan op deze manier alleen de laatste commit van een gerebasete pull request worden gevonden.

Wat faalt, en waarom

De status noemt de eerste commit die faalt en het aantal andere. Elke commit staat in de uitleg.

Hoe fremforge beslist:

• Welke commits tellen. Bij een pull request naar een hotfixbranch de eigen commits ervan. Bij een push naar een hotfixbranch elke commit op de branch die niet op de standaardbranch staat. De productietag waarvan de branch is gemaakt, staat op de standaardbranch en telt dus nooit. Maak hotfixbranches vanaf een commit van de standaardbranch.
• Force-pushes worden vanaf nul gecontroleerd: fremforge kijkt naar de hele branch, nooit alleen naar de commits van de laatste push.
• De wijzigingsvergelijking werkt zoals git patch-id: ze vergelijkt de regels die elke commit toevoegt en verwijdert, bestand voor bestand, en negeert witruimte, regelnummers en de omliggende regels. Een cherry-pick op een oudere release komt daardoor overeen met zijn bron. Je kunt haar uitzetten (diff_check: false).
• Een label dat na de merge is toegevoegd, telt. fremforge leest de labels van de bron-pull-request op het moment dat het controleert. Wordt het label aan een gemergede pull request toegevoegd, dan worden de open hotfix-pull-requests van die repository binnen enkele seconden opnieuw gecontroleerd.
• Commits van bots krijgen geen vrijstelling. De backport van een bot is een cherry-pick zoals ieder ander.
• Nadat een pull request is gemerged. Bij een push telt de squash- of mergecommit die een gemergede pull request naar dezelfde hotfixbranch heeft gemaakt als gecontroleerd, mits fremforge/hotfix-provenance op die pull request is geslaagd.

De status slaagt nooit per ongeluk

Kan fremforge de controle niet afmaken, bijvoorbeeld omdat de repository niet op tijd kon worden gelezen (30 seconden), dan is de status pending, met een melding daarover, en wordt binnen 5 minuten opnieuw gecontroleerd. Hij is nooit success voor een commit die niet kon worden gecontroleerd.

Op een branch die geen hotfixbranch is, plaatst fremforge niets, tenzij de regel van die branch fremforge/hotfix-provenance vereist. Dan plaatst het success, “Not a hotfix branch”, zodat geen enkele pull request erop wacht. Hetzelfde geldt voor een repository waar hotfix-herkomst uit staat: “not evaluated”.

fremforge plaatst de status binnen enkele seconden nadat een pull request is geopend, er is gepusht, hij is bewerkt of een andere doelbranch heeft gekregen, en na een push naar een hotfixbranch. Een job die elke 5 minuten draait, controleert opnieuw elke open hotfix-pull-request waarvan de status ontbreekt of pending of failure is.

Aanzetten

curl -X PUT https://frem.sh/_app/api/v1/orgs/<org>/hotfix-provenance/settings \
  -H "Authorization: Bearer $FREMFORGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode": "on", "branch_pattern": "hotfix/*", "required_label": "fast-track"}'

Het token heeft policy:write nodig; GET op hetzelfde pad vereist policy:read. Elke wijziging wordt geaudit als hotfix_provenance.settings_updated.

Er een verplichte check van maken

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

repo is de naam van een repository, of * voor elke repository, ook repository’s die later worden aangemaakt. fremforge plaatst eerst de status op elke open pull request naar een hotfixbranch en voegt pas daarna fremforge/hotfix-provenance toe aan de branchregel met dezelfde naam als het patroon (bijvoorbeeld een regel met de naam hotfix/*), waarbij de andere checks van de regel blijven staan. Een merge vanaf de webpagina, via de API of via de merge queue wacht er dan op.

fremforge maakt nooit een branchregel aan. Een repository zonder regel voor het patroon staat in unprotected; maak de regel aan (Instellingen → Branches), en de job voegt de check binnen 5 minuten toe. DELETE op hetzelfde pad met dezelfde body haalt hem weer weg. Het token heeft policy:write nodig. Beide worden geaudit, als hotfix_provenance.enforcement_enabled en hotfix_provenance.enforcement_disabled.

Waarom een pull request slaagt of faalt

curl https://frem.sh/_app/api/v1/orgs/<org>/repos/<repo>/pulls/<number>/hotfix-provenance \
  -H "Authorization: Bearer $FREMFORGE_TOKEN"

Het antwoord noemt elke commit met of hij is geslaagd, de broncommit die zijn regel noemt, de pull request van de bron en, voor een commit die faalde, het problem en de reden in woorden. Het werkt ook als hotfix-herkomst uit staat, zodat je het eerst op een echte pull request kunt uitproberen. Het token heeft findings:read nodig, of leestoegang tot de repository.