Konverzace v PR

Pull request už je místo, kde se o kódu mluví. Konverzace v PR z něj udělají plochu pracovního prostoru Control Center, stejně jako chatový most udělá plochu ze Slacku: zmíníš bota GitHub App serveru na PR, odpovíš v jeho vláknech revize, nebo přidáš štítek ai-review, a práce proběhne v prostoru kontroly toho PR — se stejným připsáním a stejnými guardraily jako cokoli napsané v aplikaci. Komentář navíc podléhá členství; štítek ne, protože nemá autora. Odpovědi bota se vracejí na GitHub, do té stopy, ve které se ptalo.

Funkci tvarují tři rozhodnutí a každé je totéž rozhodnutí, které chatový most udělal pro chat, jen přeřčené pro hostitele kódu: kterým směrem spojení běží, co autorizuje komentář, který přijde zvenku, a komu se připisuje každá strana.

Transportem je obchůzka

Jediný push kanál, který GitHub aplikaci dává, je webhook a webhook potřebuje příchozí URL — to jediné, co tahle plocha záměrně nikdy nevyžaduje. Objevování je proto obchůzka: zhruba každou minutu se jedno hledání s aliasy na každou instalaci aplikace zeptá GitHubu na PR, které zmiňují bota (nebo jeho krátký slug), a na otevřené PR se štítkem kontroly. PR, které už mají prostor kontroly, si nechají přečíst vlákna komentářů a všechno se porovná podle id komentáře s tím, co viděla minulá obchůzka.

Důsledky návrhu stojí za pojmenování:

Latence je interval obchůzky, ne událost. Potvrzení 👀 přijde zhruba do minuty. Nic naléhavého na tom nestojí.
Přesně jednou, na každý komentář. Id komentářů jsou na GitHubu jedinečná; každé se zapíše v okamžiku, kdy se klasifikuje jako způsobilé, dřív než s ním cokoli začne jednat. Pád může zpracování komentáře ztratit, dvakrát ho nespustí.
Výpadek se dožene, nepřehrává. Množina viděného se ukládá, takže restart doručí to, co přišlo, když byl server dole. Jediná výjimka je úplně první obchůzka: bez paměti, proti které by se porovnávalo, se všechno, co ještě visí, zapíše potichu — operátor, který dvaceti PR přidal štítek dřív, než tenhle server existoval, se nesmí vrátit k dvaceti rozjetým kontrolám.
Štítek je množina, ne událost. Hledání hlásí přítomnost štítku, takže označený PR spustí akci jednou a pak už nikdy. Štítek odebraný a znovu přidaný obchůzka nevidí; cestou k opětovnému spuštění je zmínka.

Hledání běží jednou na každý účet instalace, na vlastním klientovi toho vlastníka, protože token instalace vidí jen repozitáře své instalace — jeden přihlašovací údaj pro celý server by potichu minul každý PR pod ostatními instalacemi aplikace.

Autorizuje členství, ne komentář

Komentář u PR přijde skoro jen s loginem autora — neověřená vnější identita, dokud se neprokáže. Bot ji vyřeší proti reverznímu indexu členů pracovního prostoru a jejich připojených účtů GitHub, který se přebuduje podle TTL, protože se lidé přihlašují a dostávají pozvánky, zatímco server běží.

Selhání do zamítnutí má podobu žebříku a každý stupeň odpovídá ve vlákně, které odmítl:

Neznámý login — nepřipojený, nebo připojený někým, kdo není členem tohoto pracovního prostoru — dostane vzkaz, ať se přihlásí a ověří, že sem patří
Člen jen ke čtení (viewer nebo guest) dostane vzkaz, že jeho role práci spustit nemůže

Oba případy neznámého loginu sdílejí jednu odpověď: reverzní index vrací jen člena tohoto pracovního prostoru, takže nepřipojený účet a připojený nečlen jsou tentýž neúspěch. Nikdo z nich dál nepokračuje. Komentář se nikdy nepřipíše někomu, kdo ho neposlal, a slova cizího člověka nikdy nevstoupí do pracovního prostoru, do kterého nevidí.

Štítek ai-review nemá autora, kterého by šlo vyřešit, takže po tomhle žebříku nestoupá. Jeho přidání spustí kontrolu v pracovním prostoru, který ten repozitář už propojuje.

Dvě identity, schválně

Každá strana konverzace nese jinou identitu a ten rozdíl je ta funkce:

Na GitHubu je bot server. Každý komentář, reakce i odpověď, které most pošle, jedou na tokenu instalace aplikace. V klientovi nikdo nic neklikl, takže se nepůjčuje účet člověka — stejné pravidlo, které drží webhooky i obchůzku mimo lidské přihlašovací údaje.
V prostoru je otázka tvoje. Zpráva se připíše členovi, na kterého se autor vyřešil, a běh agenta se vykoná jeho jménem: commity ho zapíšou jako spoluautora a volič autonomie prostoru i guardraily akcí platí přesně tak jako u zprávy napsané v aplikaci. Zápisy na hostitele kódu z běhu pořád odcházejí jako aplikace — stejné pravidlo jako v odrážce výše — ne na osobním tokenu člena.

Zveřejnit zjištění kontroly zpět na GitHub zůstává rozhodnutím člověka a padá v Control Center. Zmínka může kontrolu spustit; zveřejní ji jen člověk.

Pojistka proti smyčce a krátké jméno

Všechno, co napsal účet bota, se zahodí dřív, než se spustí jakákoli brána — náš konkrétně a každá přípona [bot], aby kontrolní bot jiné aplikace neprobudil ani toho našeho. Bez toho by vlastní odpovědi bota přicházely jako nové komentáře a spouštěly ho donekonečna.

Přípona [bot] je taky důvod, proč existuje krátký tvar. GitHub login účtu aplikace natvrdo nastaví na <slug>[bot], nenabízí na něj doplňování a @slug na aplikaci nikdy nevyřeší — přijmout holý slug je tedy rozhodnutí našeho porovnávače a najít ho chce vyhledávací stopu nad surovým textem komentáře, ne index zmínek GitHubu. Cena se pojmenuje, nezamlčí: člověk, který má stejný slug jako aplikace, osloví bota každou zmínkou sebe sama v krátkém tvaru. U výrazných jmen aplikace ta kolize zůstane hypotetická.

Co záměrně nenabízíme

Žádné automatické zveřejnění. Zjištění skončí v prostoru kontroly; zveřejnění na GitHub je samostatná lidská akce
Žádná přibližná identita. Autor se vyřeší na právě jednoho člena, nebo se odmítne — žádné připsání podle nejlepšího odhadu
Žádný webhook GitHub App. Tahle plocha ho nikdy neregistruje, takže pro komentáře u PR není příchozí URL, kterou by šlo vystavit. Ostatní webhooky produktu (pipelines, synchronizace ticketů) jsou samostatné volitelné nastavení.

Viz také

Mluvte s Control Center z GitHub PR: návod k tomu všemu
Chatové mosty: tatáž tři rozhodnutí, udělaná pro chat
Vytvořte GitHub App: odkud se bere identita bota
Multiplayer — identita, členství a přítomnost: principálové a role, přes které se login vyřeší
Guardraily: co smí dělat agent, který odpovídá
Používejte AI kontrolu: pipeline, kterou spustí zmínka nebo štítek