go github

github

Go-GitHub es una biblioteca de clientes GO para acceder al GitHub API V3.

Go-GitHub requiere GO Versión 1.17 y mayor y la biblioteca se prueba contra GO versión 1.22 y mayor. Go-GitHub rastrea la política de soporte de la versión de Go. Hacemos todo lo posible para no romper las versiones más antiguas de GO si no tenemos que hacerlo, pero debido a las limitaciones de herramientas, no siempre probamos versiones anteriores.

Si está interesado en usar GraphQL API V4, la biblioteca recomendada es ShurCool/GitHubv4.

Instalación

Go-GitHub es compatible con las versiones de GO modernas en modo módulo, con GO instalado:

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

Resolverá y agregará el paquete al módulo de desarrollo actual, junto con sus dependencias.

Alternativamente, se puede lograr lo mismo si usa la importación en un paquete:

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

y ejecutar go get sin parámetros.

Finalmente, para usar la versión superior de este repositorio, use el siguiente comando:

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

Uso

 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

Construya un nuevo cliente GitHub, luego use los diversos servicios en el cliente para acceder a diferentes partes de la API GitHub. Por ejemplo:

 client := github . NewClient ( nil )

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

Algunos métodos API tienen parámetros opcionales que se pueden pasar. Por ejemplo:

 client := github . NewClient ( nil )

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

Los servicios de un cliente dividen la API en fragmentos lógicos y corresponden a la estructura de la documentación de la API de GitHub.

Nota: Usando el paquete de contexto, uno puede aprobar fácilmente señales y plazos de cancelación a varios servicios del cliente para manejar una solicitud. En caso de que no haya contexto disponible, context.Background() se puede usar como punto de partida.

Para obtener más fragmentos de código de muestra, diríjase al directorio de ejemplo.

Autenticación

Use el método WithAuthToken para configurar su cliente para autenticarse utilizando un token OAuth (por ejemplo, un token de acceso personal). Esto es lo que se necesita para la mayoría de los casos de uso aparte de las aplicaciones GitHub.

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

Tenga en cuenta que al usar un cliente autenticado, todas las llamadas realizadas por el cliente incluirán el token OAuth especificado. Por lo tanto, los clientes autenticados casi nunca deben compartirse entre diferentes usuarios.

Para los métodos API que requieren autenticación básica HTTP, use BasicAuthTransport .

Como una aplicación Github

La autenticación de aplicaciones GitHub puede ser proporcionada por diferentes PKG como Bradleyfalzon/Ghinstallation o JFERRL/GO-GITHUBAUTH.

Nota : La mayoría de los puntos finales (ex. GET /rate_limit ) requieren autenticación del token de acceso, mientras que algunos otros (ex. GET /app/hook/deliveries ) requieren autenticación JWT.

ghinstallation proporciona Transport , lo que implementa http.RoundTripper para proporcionar autenticación como instalación para aplicaciones GitHub.

Aquí hay un ejemplo de cómo autenticarse como una aplicación GitHub utilizando el paquete 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 implementa un conjunto de oauth2.TokenSource para ser utilizado con oauth2.Client . Se puede inyectar un oauth2.Client en el github.Client para autenticar las solicitudes.

Otro ejemplo usando 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 )
}

Nota : Para interactuar con ciertas API, por ejemplo, escribir un archivo en un repositorio, uno debe generar un token de instalación utilizando la ID de instalación de la aplicación GitHub y autenticarse con el método OAuth mencionado anteriormente. Ver los ejemplos.

Limitación de tasas

GitHub impone un límite de tarifa a todos los clientes de API. Los clientes no autenticados están limitados a 60 solicitudes por hora, mientras que los clientes autenticados pueden obtener hasta 5,000 solicitudes por hora. La API de búsqueda tiene un límite de tarifa personalizada. Los clientes no autenticados están limitados a 10 solicitudes por minuto, mientras que los clientes autenticados pueden formar hasta 30 solicitudes por minuto. Para recibir el límite de tarifas más alto al hacer llamadas que no se emiten en nombre de un usuario, use UnauthenticatedRateLimitedTransport

El valor Response.Rate devuelto. El valor de la tasa contiene la información del límite de tasa de la llamada API más reciente. Si no está disponible una respuesta lo suficientemente reciente, puede usar RateLimits para obtener los datos de límite de velocidad más actualizados para el cliente.

Para detectar un error de límite de velocidad de API, puede verificar si su tipo es *github.RateLimitError :

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

Obtenga más información sobre la limitación de la tasa de GitHub en "puntos finales REST API para los límites de velocidad".

Además de estos límites de tasa, GitHub impone un límite de tasa secundario en todos los clientes de API. Este límite de tarifa evita que los clientes realicen demasiadas solicitudes concurrentes.

Para detectar un error de límite de velocidad secundaria de API, puede verificar si su tipo es *github.AbuseRateLimitError :

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

Alternativamente, puede bloquear hasta que se restablezca el límite de velocidad utilizando el context.WithValue .

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

Puede usar gofri/git-github-ratelimit para manejar la velocidad secundaria límite de sueño yretía para usted.

Obtenga más información sobre la limitación de la tasa secundaria de GitHub en "Acerca de los límites de velocidad secundaria".

Estado aceptado

Algunos puntos finales pueden devolver un código de estado aceptado 202, lo que significa que la información requerida aún no está lista y estaba programada para reunirse en el lado de GitHub. Los métodos conocidos para comportarse así se documentan especificando este comportamiento.

Para detectar esta condición de error, puede verificar si su tipo es *github.AcceptedError :

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

Solicitudes condicionales

La API de GitHub tiene un buen soporte para las solicitudes condicionales que le ayudarán a evitar que queme a través de su límite de tarifa, así como ayude a acelerar su aplicación. go-github no maneja las solicitudes condicionales directamente, sino que está diseñado para funcionar con un http.Transport en caché. Recomendamos usar Gregjones/httpcache para eso. Por ejemplo:

 import "github.com/gregjones/httpcache"

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

Obtenga más información sobre las solicitudes condicionales de GitHub en "Use solicitudes condicionales si corresponde".

Creación y actualización de recursos

Todas las estructuras para los recursos de GitHub utilizan valores de puntero para todos los campos no repetidos. Esto permite distinguir entre campos no establecidos y aquellos establecidos en un valor cero. Se han proporcionado funciones auxiliares para crear fácilmente estos punteros para valores de cadena, bool e int. Por ejemplo:

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

Los usuarios que han trabajado con buffers de protocolo deben encontrar este patrón familiar.

Paginación

Todas las solicitudes de colecciones de recursos (Repos, solicitudes de extracción, problemas, etc.) apoyan la paginación. Las opciones de paginación se describen en la estructura github.ListOptions y se pasan a los métodos de la lista directamente o como un tipo integrado de una estructura de opciones de lista más específica (por ejemplo, github.PullRequestListOptions ). La información de las páginas está disponible a través de la estructura 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
}

Iteradores ( experimental )

Go V1.23 presenta el nuevo paquete iter .

Con el paquete enrichman/gh-iter , es posible crear iteradores para go-github . El iterador manejará la paginación para usted, recorriendo todos los resultados 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 )
}

Para el uso completo de enrichman/gh-iter , consulte los documentos del paquete completo.

Webhooks

go-github proporciona estructuras para casi todos los eventos webhook de GitHub, así como funciones para validarlos y las cargas útiles JSON de la sola vez de las estructuras 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 )
	...
	}
}

Además, hay bibliotecas como CBRGM/Githubevents que se basan en el ejemplo anterior y proporcionan funciones para suscribir devoluciones de llamada a eventos específicos.

Para el uso completo de Go-GitHub, consulte los documentos de paquete completo.

Código de prueba que usa go-github

El repositorio MigueleliaSweb/Go-GitHub-Mock proporciona una forma de burlarse de las respuestas. Consulte el repositorio para obtener más detalles.

Pruebas de integración

Puede ejecutar pruebas de integración desde el directorio test . Vea las pruebas de integración ReadMe.

Que contribuye

Me gustaría cubrir toda la API de GitHub y, por supuesto, las contribuciones son siempre bienvenidas. El patrón de llamadas está bastante bien establecido, por lo que agregar nuevos métodos es relativamente sencillo. Ver CONTRIBUTING.md para más detalles.

Versiones

En general, Go-GitHub sigue a Semver lo más cerca posible para etiquetar las versiones del paquete. Para las bibliotecas independientes, la aplicación de versiones semánticas es relativamente sencilla y generalmente se entiende. Pero debido a que Go-GitHub es una biblioteca de clientes para la API de GitHub, que en sí mismo cambia el comportamiento y, por lo general, somos bastante agresivos sobre la implementación de características de vista previa de la API de GitHub, hemos adoptado la siguiente política de versiones:

• Incrementamos la versión principal con cualquier cambio incompatible a la funcionalidad no previa, incluidos los cambios en la superficie de la API de GO exportada o el comportamiento de la API.
• Incrementamos la versión menor con cualquier cambio compatible con retroceso en la funcionalidad, así como cualquier cambio en la funcionalidad de vista previa en la API de GitHub. GitHub no garantiza la estabilidad de la funcionalidad de vista previa, por lo que tampoco lo consideramos una parte estable de la API Go-GitHub.
• Incrementamos la versión del parche con cualquier corrección de errores compatible con hacia atrás.

La funcionalidad de vista previa puede tomar la forma de métodos completos o simplemente datos adicionales devueltos de un método que de otro modo no previa prevalece. Consulte la documentación de la API de GitHub para obtener detalles sobre la funcionalidad de vista previa.

Versión calendario

A partir de 2022-11-28, GitHub ha anunciado que están comenzando a verificar su API V3 basada en "Versión del calendario".

En la práctica, nuestro objetivo es hacer que las anulaciones de la versión por método (al menos en la biblioteca central) sean raras y temporales.

Nuestra comprensión de los documentos de GitHub es que acelerará toda la API a cada nueva versión basada en la fecha, incluso si solo unos pocos métodos tienen cambios rotos. Otros métodos aceptarán la nueva versión con su funcionalidad existente. Entonces, cuando se lanza una nueva versión basada en la fecha de la API de GitHub, nosotros (los mantenedores de repos) planeamos:

• Actualice cada método que tuviera cambios de ruptura, anulando su encabezado de versión API por método. Esto puede suceder en uno o múltiples compromisos y PRS, y se hace todo en la rama principal.

• Una vez que se hayan actualizado todos los métodos con cambios de ruptura, tenga una confirmación final que aumente la versión API predeterminada y elimine todas las anulaciones por método. Eso ahora obtendría un aumento de la versión principal cuando se realice el próximo lanzamiento de Go-GitHub.

Tabla de compatibilidad de la versión

La siguiente tabla identifica qué versión de la API GitHub es compatible con estas (y pasadas) versiones de este repositorio (Go-GitHub). Las versiones anteriores a 48.2.0 no se enumeran.

versión de github	Versión de la API de GitHub V3
68.0.0	2022-11-28
...	2022-11-28
48.2.0	2022-11-28

Licencia

Esta biblioteca se distribuye bajo la licencia de estilo BSD que se encuentra en el archivo de licencia.