go github

go-github

Go-Github est une bibliothèque client Go pour accéder à l'API GitHub v3.

Go-Github nécessite GO version 1.17 et plus et la bibliothèque est testée contre GO version 1.22 et plus. Go-Github Tracks GO de la politique de support de version de Go. Nous faisons de notre mieux pour ne pas briser les versions plus anciennes de GO si nous n'avons pas à le faire, mais en raison des contraintes d'outillage, nous ne testons pas toujours des versions plus anciennes.

Si vous souhaitez utiliser l'API GraphQL V4, la bibliothèque recommandée est ShurCool / GitHubv4.

Installation

Go-Github est compatible avec les sorties GO modernes en mode module, avec GO installé:

go get github.com/google/go-github/v68

Résoudre et ajoutera le package au module de développement actuel, ainsi que ses dépendances.

Alternativement, le même peut être réalisé si vous utilisez l'importation dans un package:

 import "github.com/google/go-github/v68/github"

et exécuter go get sans paramètres.

Enfin, pour utiliser la version haut de gamme de ce dépôt, utilisez la commande suivante:

go get github.com/google/go-github/v68@master

Usage

 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 disabled

Construisez un nouveau client GitHub, puis utilisez les différents services du client pour accéder à différentes parties de l'API GitHub. Par exemple:

 client := github . NewClient ( nil )

// list all organizations for user "willnorris"
orgs , _ , err := client . Organizations . List ( context . Background (), "willnorris" , nil )

Certaines méthodes API ont des paramètres facultatifs qui peuvent être passés. Par exemple:

 client := github . NewClient ( nil )

// list public repositories for org "github"
opt := & github. RepositoryListByOrgOptions { Type : "public" }
repos , _ , err := client . Repositories . ListByOrg ( context . Background (), "github" , opt )

Les services d'un client divisent l'API en morceaux logiques et correspondent à la structure de la documentation de l'API GitHub.

Remarque: En utilisant le package de contexte, on peut facilement passer les signaux d'annulation et les délais à divers services du client pour gérer une demande. Dans le cas où il n'y a pas de contexte disponible, alors context.Background() peut être utilisé comme point de départ.

Pour plus d'exemples d'extraits de code, rendez-vous vers l'exemple de répertoire.

Authentification

Utilisez la méthode WithAuthToken pour configurer votre client pour vous authentifier à l'aide d'un jeton OAuth (par exemple, un jeton d'accès personnel). C'est ce qui est nécessaire pour la majorité des cas d'utilisation en dehors des applications GitHub.

 client := github . NewClient ( nil ). WithAuthToken ( "... your access token ..." )

Notez que lors de l'utilisation d'un client authentifié, tous les appels passés par le client incluront le jeton OAuth spécifié. Par conséquent, les clients authentifiés ne devraient presque jamais être partagés entre différents utilisateurs.

Pour les méthodes API qui nécessitent une authentification de base HTTP, utilisez le BasicAuthTransport .

En tant qu'application GitHub

L'authentification des applications GitHub peut être fournie par différents PKG comme BradleyFalzon / Ghinstallation ou Jferrl / Go-Githubauth.

Remarque : La plupart des points de terminaison (ex. GET /rate_limit ) nécessitent une authentification de jeton d'accès tandis que quelques autres (ex. GET /app/hook/deliveries ) nécessitent une authentification JWT.

ghinstallation fournit Transport , qui implémente http.RoundTripper pour fournir l'authentification en tant qu'installation pour les applications GitHub.

Voici un exemple de la façon de s'authentifier en tant qu'application GitHub en utilisant le package 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 implémente un ensemble de oauth2.TokenSource à utiliser avec oauth2.Client . Un oauth2.Client peut être injecté dans le github.Client pour authentifier les demandes.

Autre exemple à l'aide de 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 )
}

Remarque : Afin d'interagir avec certaines API, par exemple en écrivant un fichier dans un dépôt, il faut générer un jeton d'installation en utilisant l'ID d'installation de l'application GitHub et s'authentifier avec la méthode OAuth mentionnée ci-dessus. Voir les exemples.

Limitation des taux

GitHub impose une limite de taux à tous les clients de l'API. Les clients non authentifiés sont limités à 60 demandes par heure, tandis que les clients authentifiés peuvent faire jusqu'à 5 000 demandes par heure. L'API de recherche a une limite de taux personnalisée. Les clients non authentifiés sont limités à 10 demandes par minute, tandis que les clients authentifiés peuvent faire jusqu'à 30 demandes par minute. Pour recevoir la limite de taux plus élevée lors de la réalisation d'appels qui ne sont pas émis au nom d'un utilisateur, utilisez UnauthenticatedRateLimitedTransport .

La valeur Response.Rate retournée.Rate contient les informations de limite de taux de l'appel API le plus récent. Si une réponse suffisamment récente n'est pas disponible, vous pouvez utiliser RateLimits pour récupérer les données de limite de taux les plus à jour pour le client.

Pour détecter une erreur de limite de débit API, vous pouvez vérifier si son type est *github.RateLimitError :

 repos , _ , err := client . Repositories . List ( ctx , "" , nil )
if _ , ok := err .( * github. RateLimitError ); ok {
	log . Println ( "hit rate limit" )
}

En savoir plus sur la limitation du taux GitHub dans les "points de terminaison de l'API REST pour les limites de taux".

En plus de ces limites de taux, GitHub impose une limite de taux secondaire à tous les clients de l'API. Cette limite de taux empêche les clients de faire trop de demandes simultanées.

Pour détecter une erreur de limite de taux secondaire de l'API, vous pouvez vérifier si son type est *github.AbuseRateLimitError :

 repos , _ , err := client . Repositories . List ( ctx , "" , nil )
if _ , ok := err .( * github. AbuseRateLimitError ); ok {
	log . Println ( "hit secondary rate limit" )
}

Alternativement, vous pouvez bloquer jusqu'à ce que la limite de taux soit réinitialisée en utilisant le context.WithValue .

 repos , _ , err := client . Repositories . List ( context . WithValue ( ctx , github . SleepUntilPrimaryRateLimitResetWhenRateLimited , true ), "" , nil )

Vous pouvez utiliser GOFRI / Go-Github-Ratelimit pour gérer la limite de taux secondaire Sleep-and-Retry pour vous.

En savoir plus sur la limitation du taux secondaire GitHub dans "About Secondary Taux Limits".

Statut accepté

Certains points de terminaison peuvent renvoyer un code d'état accepté 202, ce qui signifie que les informations requises ne sont pas encore prêtes et devaient être recueillies du côté GitHub. Les méthodes connues pour se comporter comme celle-ci sont documentées spécifiant ce comportement.

Pour détecter cette condition d'erreur, vous pouvez vérifier si son type est *github.AcceptedError :

 stats , _ , err := client . Repositories . ListContributorsStats ( ctx , org , repo )
if _ , ok := err .( * github. AcceptedError ); ok {
	log . Println ( "scheduled on GitHub side" )
}

Demandes conditionnelles

L'API GitHub a un bon support pour les demandes conditionnelles qui vous aideront à vous empêcher de brûler dans votre limite de taux, ainsi que pour accélérer votre application. go-github ne gère pas directement les demandes conditionnelles, mais est plutôt conçu pour fonctionner avec un http.Transport de mise en cache. Nous vous recommandons d'utiliser Gregjones / HttpCache pour cela. Par exemple:

 import "github.com/gregjones/httpcache"

	client := github . NewClient (
		httpcache . NewMemoryCacheTransport (). Client ()
    ). WithAuthToken ( os . Getenv ( "GITHUB_TOKEN" ))

En savoir plus sur les demandes conditionnelles GitHub dans "Utiliser les demandes conditionnelles si appropriées".

Création et mise à jour des ressources

Toutes les structures pour les ressources GitHub utilisent des valeurs de pointeur pour tous les champs non répétés. Cela permet de distinguer entre les champs non définis et ceux qui sont définis sur une valeur zéro. Des fonctions d'assistance ont été fournies pour créer facilement ces pointeurs pour les valeurs String, Bool et int. Par exemple:

 // create a new private repository named "foo"
repo := & github. Repository {
	Name :    github . Ptr ( "foo" ),
	Private : github . Ptr ( true ),
}
client . Repositories . Create ( ctx , "" , repo )

Les utilisateurs qui ont travaillé avec des tampons de protocole devraient trouver ce modèle familier.

Pagination

Toutes les demandes de collections de ressources (repos, demandes de traction, de problèmes, etc.) prennent en charge la pagination. Les options de pagination sont décrites dans la structure github.ListOptions et transmises directement aux méthodes de liste ou en tant que type intégré d'une structure d'options de liste plus spécifique (par exemple github.PullRequestListOptions ). Les informations sur les pages sont disponibles via la structure github.Response .

 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
}

Itérateurs ( expérimentaux )

GO V1.23 présente le nouveau package iter .

Avec le package enrichman/gh-iter , il est possible de créer des itérateurs pour go-github . L'Itérateur gérera la pagination pour vous, en faisant une boucle à travers tous les résultats disponibles.

 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 )
}

Pour une utilisation complète d' enrichman/gh-iter , consultez les documents de package complet.

Webhooks

go-github fournit des structures pour presque tous les événements GitHub WebHook ainsi que des fonctions pour les valider et les charges utiles JSON de JSON de http.Request .

 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 )
	...
	}
}

En outre, il existe des bibliothèques comme CBRGM / GitHuBevents qui s'appuient sur l'exemple ci-dessus et fournissent des fonctions pour souscrire des rappels à des événements spécifiques.

Pour une utilisation complète de Go-Github, consultez les documents de package complet.

Tester le code qui utilise go-github

Le repo MigueleliaSweb / Go-Github-Mock fournit un moyen de se moquer des réponses. Vérifiez le dépôt pour plus de détails.

Tests d'intégration

Vous pouvez exécuter des tests d'intégration à partir du répertoire test . Voir les tests d'intégration Readme.

Contributif

Je voudrais couvrir toute l'API GitHub et les contributions sont bien sûr toujours les bienvenues. Le modèle d'appel est assez bien établi, donc l'ajout de nouvelles méthodes est relativement simple. Voir CONTRIBUTING.md pour plus de détails.

Versioning

En général, Go-Github suit Semver aussi étroitement que possible pour le marquage des versions du package. Pour les bibliothèques autonomes, l'application du versioning sémantique est relativement simple et généralement comprise. Mais parce que Go-Github est une bibliothèque client pour l'API GitHub, qui elle-même modifie le comportement, et parce que nous sommes généralement assez agressifs quant à la mise en œuvre des fonctionnalités d'aperçu de l'API GitHub, nous avons adopté la politique de version suivante:

• Nous incrémentons la version principale avec tout changement incompatible dans les fonctionnalités non révisées, y compris les modifications de la surface de l'API GO exportée ou du comportement de l'API.
• Nous incrémentons la version mineure avec toutes les modifications compatibles en arrière de la fonctionnalité, ainsi que toute modification de la fonctionnalité de prévisualisation dans l'API GitHub. GitHub ne garantit pas la stabilité de la fonctionnalité de prévisualisation, donc nous ne le considérons pas non plus comme une partie stable de l'API Go-Github.
• Nous incrémentons la version du patch avec toutes les corrections de bugs compatibles vers l'arrière.

La fonctionnalité d'aperçu peut prendre la forme de méthodes entières ou simplement des données supplémentaires renvoyées d'une méthode autrement non vue. Reportez-vous à la documentation de l'API GitHub pour plus de détails sur la fonctionnalité d'aperçu.

Version de calendrier

En 2022-11-28, GitHub a annoncé qu'ils commençaient à version à leur API V3 sur la base de "Calendar-Versioning".

Dans la pratique, notre objectif est de rendre les remplacements de version par méthode (au moins dans la bibliothèque de base) rares et temporaires.

Notre compréhension des documents GitHub est qu'ils recouvrent toute l'API à chaque nouvelle version basée sur les dates, même si seulement quelques méthodes ont des changements de rupture. D'autres méthodes accepteront la nouvelle version avec leurs fonctionnalités existantes. Ainsi, lorsqu'une nouvelle version basée sur les dates de l'API GitHub est publiée, nous (les agents de repos) prévoyons:

• Mettez à jour chaque méthode qui avait des changements de rupture, en remplaçant leur en-tête de version API par méthode. Cela peut se produire dans un ou plusieurs engins et PRS, et se fait dans la branche principale.

• Une fois que toutes les méthodes avec des modifications de rupture ont été mises à jour, ont un engagement final qui baisse la version API par défaut et supprime tous les remplacements par méthode. Cela obtiendrait maintenant une bosse de version majeure lorsque la prochaine version de Go-Github sera effectuée.

Table de compatibilité des versions

Le tableau suivant identifie la version de l'API GitHub est prise en charge par ces versions (et passées) de ce repo (Go-Github). Les versions avant 48.2.0 ne sont pas répertoriées.

Version Go-Github	Version de l'API GitHub V3
68.0.0	2022-11-28
...	2022-11-28
48.2.0	2022-11-28

Licence

Cette bibliothèque est distribuée sous la licence de style BSD trouvée dans le fichier de licence.