go github
v68.0.0
Go-Github ist eine Go-Client-Bibliothek für den Zugriff auf den GitHub API V3.
Go-Github erfordert Go Version 1.17 und größer und die Bibliothek wird gegen Go Version 1.22 und größer getestet. Go-Github Tracks Go's Version Support-Richtlinie. Wir tun unser Bestes, um ältere Versionen von Go zu brechen, wenn wir es nicht müssen, aber aufgrund von Werkzeugbeschränkungen testen wir nicht immer ältere Versionen.
Wenn Sie an der Verwendung des GraphQL API V4 interessiert sind, ist die empfohlene Bibliothek Shurcool/githubv4.
Go-Github ist mit modernen GO-Veröffentlichungen im Modulmodus kompatibel, wobei GO installiert ist:
go get github.com/google/go-github/v68wird das Paket zusammen mit seinen Abhängigkeiten auflösen und zum aktuellen Entwicklungsmodul hinzufügen.
Alternativ kann das gleiche erreicht werden, wenn Sie den Import in einem Paket verwenden:
import "github.com/google/go-github/v68/github" und rennen Sie go get ohne Parameter.
Um die oberste Version dieses Repo zu verwenden, verwenden Sie schließlich den folgenden Befehl:
go get github.com/google/go-github/v68@master import "github.com/google/go-github/v68/github" // with go modules enabled (GO111MODULE=on or outside GOPATH)
import "github.com/google/go-github/github" // with go modules disabledKonstruieren Sie einen neuen GitHub -Client und verwenden Sie die verschiedenen Dienste für den Kunden, um auf verschiedene Teile der Github -API zuzugreifen. Zum Beispiel:
client := github . NewClient ( nil )
// list all organizations for user "willnorris"
orgs , _ , err := client . Organizations . List ( context . Background (), "willnorris" , nil )Einige API -Methoden haben optionale Parameter, die übergeben werden können. Zum Beispiel:
client := github . NewClient ( nil )
// list public repositories for org "github"
opt := & github. RepositoryListByOrgOptions { Type : "public" }
repos , _ , err := client . Repositories . ListByOrg ( context . Background (), "github" , opt )Die Dienste eines Kunden teilen die API in logische Stücke und entsprechen der Struktur der Github -API -Dokumentation.
HINWEIS: Mit dem Kontextpaket können Sie leicht Stornierungssignale und -fristen an verschiedene Dienste des Kunden übergeben, um eine Anfrage zu bearbeiten. Falls kein Kontext verfügbar ist, kann der context.Background() als Ausgangspunkt verwendet werden.
Weitere Beispiele -Code -Ausschnitte finden Sie in das Beispielverzeichnis.
Verwenden Sie die WithAuthToken -Methode, um Ihren Client mithilfe eines OAuth -Tokens (z. B. einem persönlichen Zugriffs -Token) zu konfigurieren. Dies ist, was für eine Mehrheit der Anwendungsfälle erforderlich ist, abgesehen von Github -Apps.
client := github . NewClient ( nil ). WithAuthToken ( "... your access token ..." )Beachten Sie, dass bei Verwendung eines authentifizierten Clients alle vom Client getätigten Anrufe das angegebene OAuth -Token enthalten. Daher sollten authentifizierte Clients fast nie zwischen verschiedenen Benutzern geteilt werden.
Verwenden Sie für API -Methoden, die eine HTTP -Basisauthentifizierung erfordern, das BasicAuthTransport .
Die Authentifizierung von Github-Apps kann von verschiedenen PKGs wie Bradleyfalzon/Ghinstallation oder Jferrl/Go-GithubAuth bereitgestellt werden.
HINWEIS : Die meisten Endpunkte (z. B.
GET /rate_limit) erfordern Zugriffsantriebsauthentifizierung, während einige andere (z. B.GET /app/hook/deliveries) eine JWT -Authentifizierung erfordern.
ghinstallation bietet Transport , das http.RoundTripper implementiert, um Authentifizierung als Installation für Github -Apps bereitzustellen.
Hier ist ein Beispiel für die Authentifizierung als GitHub -App mit dem ghinstallation :
import (
"net/http"
"github.com/bradleyfalzon/ghinstallation/v2"
"github.com/google/go-github/v68/github"
)
func main () {
// Wrap the shared transport for use with the integration ID 1 authenticating with installation ID 99.
itr , err := ghinstallation . NewKeyFromFile ( http . DefaultTransport , 1 , 99 , "2016-10-19.private-key.pem" )
// Or for endpoints that require JWT authentication
// itr, err := ghinstallation.NewAppsTransportKeyFromFile(http.DefaultTransport, 1, "2016-10-19.private-key.pem")
if err != nil {
// Handle error.
}
// Use installation transport with client.
client := github . NewClient ( & http. Client { Transport : itr })
// Use client...
} go-githubauth implementiert eine Reihe von oauth2.TokenSource , die mit oauth2.Client verwendet werden sollen. Ein oauth2.Client kann in den github.Client injiziert werden. Client, um Anforderungen zu authentifizieren.
Anderes Beispiel mit go-githubauth :
package main
import (
"context"
"fmt"
"os"
"strconv"
"github.com/google/go-github/v68/github"
"github.com/jferrl/go-githubauth"
"golang.org/x/oauth2"
)
func main () {
privateKey := [] byte ( os . Getenv ( "GITHUB_APP_PRIVATE_KEY" ))
appTokenSource , err := githubauth . NewApplicationTokenSource ( 1112 , privateKey )
if err != nil {
fmt . Println ( "Error creating application token source:" , err )
return
}
installationTokenSource := githubauth . NewInstallationTokenSource ( 1113 , appTokenSource )
// oauth2.NewClient uses oauth2.ReuseTokenSource to reuse the token until it expires.
// The token will be automatically refreshed when it expires.
// InstallationTokenSource has the mechanism to refresh the token when it expires.
httpClient := oauth2 . NewClient ( context . Background (), installationTokenSource )
client := github . NewClient ( httpClient )
}HINWEIS : Um mit bestimmten APIs zu interagieren, beispielsweise eine Datei an ein Repo zu schreiben, muss man ein Installations -Token unter Verwendung der Installations -ID der GitHub -App generieren und mit der oben genannten OAuth -Methode authentifizieren. Siehe die Beispiele.
GitHub stellt alle API -Clients eine Zinsgrenze vor. Nicht authentifizierte Kunden sind auf 60 Anfragen pro Stunde begrenzt, während authentifizierte Kunden bis zu 5.000 Anfragen pro Stunde stammen können. Die Such -API hat eine benutzerdefinierte Ratenlimit. Nicht authentifizierte Clients sind auf 10 Anfragen pro Minute begrenzt, während authentifizierte Clients bis zu 30 Anfragen pro Minute stammen können. Verwenden Sie UnauthenticatedRateLimitedTransport , um die höhere Zinsgrenze bei Anrufen zu erhalten, die nicht im Namen eines Benutzers ausgestellt werden.
Die zurückgegebene Response.Rate Der Ratenwert enthält die Ratenlimitinformationen aus dem neuesten API -Aufruf. Wenn eine kürzlich ausreichende Antwort nicht verfügbar ist, können Sie RateLimits verwenden, um die aktuellsten Rate-Limit-Daten für den Client abzurufen.
Um einen API -Ratenlimit -Fehler zu erkennen, können Sie prüfen, ob sein Typ *github.RateLimitError ist:
repos , _ , err := client . Repositories . List ( ctx , "" , nil )
if _ , ok := err .( * github. RateLimitError ); ok {
log . Println ( "hit rate limit" )
}Erfahren Sie mehr über die GitHub -Rate -Limitierung in "REST -API -Endpunkten für Ratenlimits".
Zusätzlich zu diesen Ratengrenzen stellt GitHub allen API -Clients eine sekundäre Ratengrenze vor. Diese Ratenlimit verhindert, dass Kunden zu viele gleichzeitige Anfragen stellen.
Um einen API -Sekundärrate -Limit -Fehler zu erkennen, können Sie überprüfen, ob ihr Typ *github.AbuseRateLimitError ist:
repos , _ , err := client . Repositories . List ( ctx , "" , nil )
if _ , ok := err .( * github. AbuseRateLimitError ); ok {
log . Println ( "hit secondary rate limit" )
} Alternativ können Sie blockieren, bis die Ratengrenze durch die Verwendung des context.WithValue zurückgesetzt wird.
repos , _ , err := client . Repositories . List ( context . WithValue ( ctx , github . SleepUntilPrimaryRateLimitResetWhenRateLimited , true ), "" , nil )Sie können Gofri/Go-Github-Ratelimit verwenden, um die Sekundärrate-Begrenzung für Sie zu verarbeiten.
Erfahren Sie mehr über GitHub Secondary Rate Limiting in "Über die Sekundärrategrenzen".
Einige Endpunkte können einen akzeptierten Statuscode von 202 zurückgeben, was bedeutet, dass die erforderlichen Informationen noch nicht fertig sind und auf der Github -Seite gesammelt werden sollen. Methoden, von denen bekannt ist, dass sie sich so verhalten, sind dokumentiert, dass dieses Verhalten angegeben ist.
Um diese Fehlerbedingung zu erkennen, können Sie überprüfen, ob sein Typ *github.AcceptedError ist:
stats , _ , err := client . Repositories . ListContributorsStats ( ctx , org , repo )
if _ , ok := err .( * github. AcceptedError ); ok {
log . Println ( "scheduled on GitHub side" )
} Die GitHub -API unterstützt eine gute Unterstützung für bedingte Anfragen, die Sie daran hindern, Ihre Ratenlimit zu durchbrennen und Ihre Anwendung zu beschleunigen. go-github behandelt nicht direkte Anfragen, sondern ist stattdessen so konzipiert, dass sie mit einem Caching http.Transport arbeiten. Wir empfehlen, dafür Gregjones/HTTPCache zu verwenden. Zum Beispiel:
import "github.com/gregjones/httpcache"
client := github . NewClient (
httpcache . NewMemoryCacheTransport (). Client ()
). WithAuthToken ( os . Getenv ( "GITHUB_TOKEN" ))Erfahren Sie mehr über GitHub -Anforderungen an "Bedingte Anfragen verwenden Sie gegebenenfalls".
Alle Strukturen für GitHub-Ressourcen verwenden Zeigerwerte für alle nicht wiederholten Felder. Dies ermöglicht die Unterscheidung zwischen nicht festgelegten Feldern und denjenigen, die auf einen Nullwert eingestellt sind. Es wurden Helferfunktionen bereitgestellt, um diese Zeiger für Zeichenfolge, BOOL und INT problemlos zu erstellen. Zum Beispiel:
// create a new private repository named "foo"
repo := & github. Repository {
Name : github . Ptr ( "foo" ),
Private : github . Ptr ( true ),
}
client . Repositories . Create ( ctx , "" , repo )Benutzer, die mit Protokollpuffern gearbeitet haben, sollten dieses Muster vertraut finden.
Alle Anfragen nach Ressourcensammlungen (Repos, Zuganfragen, Probleme usw.) unterstützen die Pagination. Paginierungsoptionen werden im github.ListOptions -Struktur beschrieben und direkt oder als eingebetteter Typ einer spezifischeren Listenoptionsstrukturen übergeben (z. B. github.PullRequestListOptions ). Seiteninformationen sind über die github.Response Struct verfügbar.
client := github . NewClient ( nil )
opt := & github. RepositoryListByOrgOptions {
ListOptions : github. ListOptions { PerPage : 10 },
}
// get all pages of results
var allRepos [] * github. Repository
for {
repos , resp , err := client . Repositories . ListByOrg ( ctx , "github" , opt )
if err != nil {
return err
}
allRepos = append ( allRepos , repos ... )
if resp . NextPage == 0 {
break
}
opt . Page = resp . NextPage
} Go v1.23 führt das neue iter -Paket vor.
Mit dem enrichman/gh-iter Paket ist es möglich, Iteratoren für go-github zu erstellen. Der Iterator wird Pagination für Sie abwickeln und alle verfügbaren Ergebnisse durchlaufen.
client := github . NewClient ( nil )
var allRepos [] * github. Repository
// create an iterator and start looping through all the results
repos := ghiter . NewFromFn1 ( client . Repositories . ListByOrg , "github" )
for repo := range repos . All () {
allRepos = append ( allRepos , repo )
} Für die vollständige Nutzung von enrichman/gh-iter finden Sie die vollständigen Paketdokumente.
go-github bietet Strukturen für fast alle Github-Webhook-Events sowie Funktionen, um sie zu validieren, und die Unmarshal JSON-Nutzlasten von http.Request -Strukturen.
func ( s * GitHubEventMonitor ) ServeHTTP ( w http. ResponseWriter , r * http. Request ) {
payload , err := github . ValidatePayload ( r , s . webhookSecretKey )
if err != nil { ... }
event , err := github . ParseWebHook ( github . WebHookType ( r ), payload )
if err != nil { ... }
switch event := event .( type ) {
case * github. CommitCommentEvent :
processCommitCommentEvent ( event )
case * github. CreateEvent :
processCreateEvent ( event )
...
}
}Darüber hinaus gibt es Bibliotheken wie CBRGM/Githuubvents, die auf dem obigen Beispiel aufbauen und Funktionen bereitstellen, um Rückrufe für bestimmte Ereignisse zu abonnieren.
Für die vollständige Verwendung von Go-Github finden Sie die vollständigen Paketdokumente.
go-github verwendetDas Repo Migueleliasweb/Go-Github-Mock bietet eine Möglichkeit, Antworten zu verspotten. Weitere Informationen finden Sie im Repo.
Sie können Integrationstests aus dem test ausführen. Siehe die Integrationstests Readme.
Ich möchte die gesamte Github -API abdecken und Beiträge sind natürlich immer willkommen. Das Anrufmuster ist ziemlich gut etabliert, daher ist das Hinzufügen neuer Methoden relativ einfach. Weitere Informationen finden Sie CONTRIBUTING.md .
Im Allgemeinen folgt Go-Github Semver so eng wie möglich, um die Veröffentlichungen des Pakets zu markieren. Für in sich geschlossene Bibliotheken ist die Anwendung der semantischen Versionierung relativ einfach und allgemein verstanden. Da Go-Github eine Client-Bibliothek für die Github-API ist, die das Verhalten verändert, und wir in der Regel ziemlich aggressiv sind, wenn wir die Vorschau-Funktionen der Github-API implementieren, haben wir die folgende Versionsrichtlinie übernommen:
Die Vorschau-Funktionalität kann in Form von gesamten Methoden oder einfach zusätzlichen Daten annehmen, die von einer ansonsten nicht vorbereiteten Methode zurückgegeben werden. Weitere Informationen zur Vorschau -Funktionalität finden Sie in der GitHub -API -Dokumentation.
Ab 2022-11-28 hat Github angekündigt, ihre V3-API auf der Grundlage "Kalenderverssionierung" zu verstellen.
In der Praxis ist es unser Ziel, per Methodenversion (zumindest in der Kernbibliothek) selten und vorübergehend zu überschreiben.
Unser Verständnis der Github-Dokumente ist, dass sie die gesamte API zu jeder neuen Datumsbasis-Version drehen, auch wenn nur wenige Methoden gegen Unterbrechungsänderungen verfügen. Andere Methoden akzeptieren die neue Version mit ihrer vorhandenen Funktionalität. Wenn also eine neue date-basierte Version der Github-API veröffentlicht wird, planen wir (The Repo Warders):
Aktualisieren Sie jede Methode, bei der Änderungen auftreten, und überschrieben ihren Header mit pro Method-API-Version. Dies kann in einem oder mehreren Commits und PRs geschehen und ist alles im Hauptzweig.
Sobald alle Methoden mit Bruchänderungen aktualisiert wurden, haben Sie ein endgültiges Commit, das die Standard-API-Version stößt und alle Überschreibungen pro Methoden entfernen. Das würde jetzt eine große Versionsbeule bekommen, wenn die nächste Go-Github-Veröffentlichung erstellt wird.
In der folgenden Tabelle wird festgestellt, welche Version der Github-API durch diese (und vergangenen) Versionen dieses Repo (Go-Github) unterstützt wird. Versionen vor 48.2.0 sind nicht aufgeführt.
| Go-Github-Version | Github V3 API -Version |
|---|---|
| 68.0.0 | 2022-11-28 |
| ... | 2022-11-28 |
| 48.2.0 | 2022-11-28 |
Diese Bibliothek wird unter der in der Lizenzdatei gefundenen Lizenz im BSD-Stil verteilt.
