# 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](/pl/docs/security/credentials/).

## 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](/pl/docs/features/code-review/).
- `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

1. Otwórz integracje projektu i wybierz **GitHub**.

2. Kliknij **Sign in with GitHub** i zatwierdź kod urządzenia, który Speedwave pokaże ci na `https://github.com/login/device`.

3. Gdy tylko zatwierdzisz, Speedwave zapisuje otrzymany token w katalogu tokenów projektu, a GitHub od razu jest w projekcie gotowy do pracy.

<DesktopFrame screen="integrations" />

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](/pl/docs/under-the-hood/tool-gateway/), 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](/pl/docs/features/code-review/): worker może działać na pull requeście, a mimo to nie widzi danych uwierzytelniających żadnej innej integracji.