GitHub

Co robi

Po połączeniu Speedwave pracuje z repozytorium tak jak programista: zagląda do jego zawartości, śledzi pull requesta przez kolejne commity i uruchomienia CI, a do tego zostawia uwagi w przeglądzie kodu.

Z czego się składa

GitHub działa jako osobny worker, czyli kontener, który ma dostęp wyłącznie do tokenów GitHub. Speedwave zapisuje twój token w katalogu tokenów projektu i podpina go do workera tylko do odczytu pod ścieżką /tokens/token, więc kontener dosięga jedynie GitHub.com i nic poza tym. To, jak takie podpięcie i uprawnienia plików wyglądają w każdej integracji, opisuje rozdział Dane uwierzytelniające.

Jak to działa

Połączenie przebiega przez OAuth device flow GitHuba: Speedwave wyświetla kod, ty zatwierdzasz go na https://github.com/login/device, a token ląduje na dysku, ani razu nie zahaczając o interfejs projektu w przeglądarce. Aplikacja OAuth Speedwave prosi o zakresy repo i read:user, czyli o odczyt i zapis w repozytoriach prywatnych i publicznych, w issues, pull requestach, wydaniach i Actions, a na dokładkę o odczyt twojego konta na potrzeby testu połączenia.

Ręczny token przydaje się awaryjnie, kiedy device flow się nie sprawdza, na przykład przy konfiguracji bezgłowej. Wklej token zaczynający się od gho_ (token użytkownika aplikacji OAuth), github_pat_ (fine-grained PAT) albo ghp_ (klasyczny PAT); worker weźmie każdy z nich i nie przygląda się prefiksowi, więc sam zadbaj o to, żeby obejmował te same zakresy co wyżej.

Od tej chwili worker daje ci do ręki 45 narzędzi ułożonych w grupy: repozytoria, pull requesty, przeglądy pull requestów, gałęzie, commity, zawartość repozytorium, Actions, issues, etykiety i wydania. Kilka z nich warto poznać bliżej:

createPrComment zostawia ogólny komentarz w wątku rozmowy, a createPrReviewComment przypina komentarz do konkretnej linii w diffie, bo GitHub udostępnia do tego dwa osobne endpointy. createPrReview i listPrReviews działają na poziomie całego przeglądu, co ma znaczenie, gdy zaprzęgasz Speedwave do przeglądu kodu.
triggerWorkflow odpala ręczne wykonanie workflow_dispatch, a rerunWorkflow powtarza już istniejące. getRunLogs i downloadArtifact zwracają krótko ważny download_url prowadzący do pliku ZIP, zamiast pobierać go i rozpakowywać za ciebie; listWorkflowRunArtifacts najpierw pokaże ci, co jest do wzięcia. Pobieraj od razu, bo adres szybko traci ważność.
getFileContents odczytuje plik, a getTree wypisuje drzewo katalogu; jeśli nie podasz gałęzi, oba biorą domyślną gałąź repozytorium, a jeśli wskażesz którymś z nich katalog tam, gdzie oczekiwany jest plik, dostaniesz zrozumiały błąd. createOrUpdateFile zapisuje plik i sam dobiera bieżące SHA blobu, gdy go nie podasz.
createRelease sam założy tag, jeśli takiego jeszcze nie ma, więc nie musisz wcześniej sięgać po createTag.

Worker łączy się z GitHub.com wyłącznie przez https://api.github.com; GitHub Enterprise Server nie jest obsługiwany. Brakuje też narzędzia do blame, bo REST API GitHuba nie ma endpointu blame na poziomie linii.

Co potrafi Speedwave

Narzędzie	Co robi
`listRepos`	Wypisuje lub wyszukuje repozytoria widoczne dla konta.
`getRepo`	Odczytuje szczegóły jednego repozytorium.
`searchCode`	Wyszukuje kod w GitHubie, opcjonalnie w obrębie jednego repozytorium.
`listPullRequests`	Wypisuje pull requesty z filtrami stanu, gałęzi lub bazy.
`getPullRequest`	Odczytuje szczegóły jednego pull requesta.
`createPullRequest`	Zakłada nowy pull request, roboczy albo gotowy do przeglądu.
`updatePullRequest`	Zmienia tytuł, opis, gałąź bazową lub stan pull requesta.
`mergePullRequest`	Scala pull request. Działanie nieodwracalne.
`getPrDiff`	Zwraca ujednolicony diff pull requesta jako tekst.
`getPrFiles`	Wypisuje zmienione pliki pull requesta wraz ze statystykami dla każdego z nich.
`listPrCommits`	Wypisuje commity wchodzące w skład pull requesta.
`listPrReviews`	Wypisuje przeglądy zgłoszone dla pull requesta.
`createPrReview`	Zgłasza przegląd: zatwierdzenie, prośbę o zmiany albo komentarz, wraz z opcjonalnymi komentarzami inline.
`listPrComments`	Wypisuje ogólne (nie przeglądowe) komentarze do pull requesta.
`createPrComment`	Dodaje ogólny komentarz do pull requesta.
`createPrReviewComment`	Dodaje komentarz przeglądu przypięty do linii w diffie.
`listBranches`	Wypisuje gałęzie repozytorium.
`getBranch`	Odczytuje szczegóły jednej gałęzi.
`createBranch`	Tworzy gałąź z commita lub innej gałęzi.
`deleteBranch`	Usuwa gałąź. Działanie nieodwracalne.
`compareBranches`	Porównuje dwie gałęzie lub commity.
`listCommits`	Wypisuje commity z filtrami gałęzi, ścieżki, autora i zakresu dat.
`listBranchCommits`	Wypisuje commity na konkretnej gałęzi.
`searchCommits`	Wyszukuje wiadomości commitów w GitHubie.
`getCommitDiff`	Zwraca ujednolicony diff jednego commita jako tekst.
`getTree`	Wypisuje drzewo plików lub katalogów repozytorium.
`getFileContents`	Odczytuje zawartość pliku; zwraca błąd, jeśli ścieżka wskazuje katalog.
`createOrUpdateFile`	Zapisuje plik razem z commitem, sam dobierając bieżące SHA blobu, jeśli go nie podasz.
`listWorkflowRuns`	Wypisuje uruchomienia workflow Actions, z filtrowaniem po gałęzi lub statusie.
`getWorkflowRun`	Odczytuje szczegóły jednego uruchomienia workflow.
`getRunLogs`	Zwraca krótko ważny adres do pobrania ZIP-a z logami uruchomienia.
`rerunWorkflow`	Ponawia istniejące uruchomienie workflow.
`triggerWorkflow`	Uruchamia ręczne wykonanie `workflow_dispatch`.
`listWorkflowRunArtifacts`	Wypisuje artefakty wytworzone przez uruchomienie workflow.
`downloadArtifact`	Zwraca krótko ważny adres do pobrania ZIP-a z artefaktem.
`listIssues`	Wypisuje issues, pomijając pull requesty, z filtrami stanu i etykiet.
`getIssue`	Odczytuje szczegóły jednego issue.
`createIssue`	Otwiera nowe issue.
`updateIssue`	Zmienia w issue tytuł, opis, stan, etykiety lub przypisane osoby.
`closeIssue`	Zamyka issue.
`listLabels`	Wypisuje etykiety zdefiniowane w repozytorium.
`createLabel`	Tworzy nową etykietę.
`createTag`	Tworzy tag Git, lekki lub z opisem.
`deleteTag`	Usuwa tag Git. Działanie nieodwracalne.
`createRelease`	Tworzy wydanie, najpierw tworząc jego tag, jeśli to potrzebne.

Skonfiguruj

Otwórz integracje projektu i wybierz GitHub.
Kliknij Sign in with GitHub i zatwierdź kod urządzenia, który Speedwave pokaże ci na https://github.com/login/device.
Gdy tylko zatwierdzisz, Speedwave zapisuje otrzymany token w katalogu tokenów projektu, a GitHub od razu jest w projekcie gotowy do pracy.

Kiedy wywołanie GitHuba się nie uda, worker przekłada odpowiedź na prostą wskazówkę:

Status	Znaczenie
`401`	Token stracił ważność. Połącz GitHub jeszcze raz, żeby dostać nowy.
`403`, limit żądań	Wyczerpany limit żądań. Worker sam ponawia próbę do dwóch razy; odczekaj chwilę i spróbuj jeszcze raz.
`403`, uprawnienia	Token nie ma do tego uprawnień. Połącz się na nowo przez OAuth, żeby ponownie przyznać zakresy, albo sprawdź uprawnienia ręcznego PAT.
`404`	Nie znaleziono elementu.
`422`	Walidacja się nie powiodła; komunikat mówi, co poszło nie tak.
`5xx`	Błąd serwera po stronie GitHuba.
Błąd sieci	Workerowi nie udało się połączyć z `api.github.com`; sprawdź swoje połączenie.

Granice bezpieczeństwa

Worker GitHuba czyta wyłącznie tokeny GitHub. Nie ma wglądu w dane uwierzytelniające żadnej innej usługi, a hub, który przekazuje mu wywołania narzędzi, sam nie trzyma żadnych tokenów, więc zasięg przejętego workera kończy się na GitHubie. Ta granica trzyma się nawet wtedy, gdy Speedwave zostawia automatyczne komentarze w ramach przeglądu kodu: worker może działać na pull requeście, a mimo to nie widzi danych uwierzytelniających żadnej innej integracji.