go github
v68.0.0
Go-Github-это клиентская библиотека GO для доступа к GitHub API V3.
GO-GitHub требует версии GO 1.17 и больше , а библиотека проверяется против версии GO 1.22 и больше. Политика поддержки версий Go-Github. Мы делаем все возможное, чтобы не сломать старые версии Go, если нам не нужно, но из -за ограничений инструментов мы не всегда тестируем старые версии.
Если вы заинтересованы в использовании GraphQL API V4, рекомендуемая библиотека - Shurcool/GitHubv4.
Go-github совместим с современными выпусками GO в режиме модуля, с установленным GO:
go get github.com/google/go-github/v68Установит и добавит пакет в текущий модуль разработки, а также его зависимости.
В качестве альтернативы то же самое может быть достигнуто, если вы используете импорт в пакете:
import "github.com/google/go-github/v68/github" и запустить go get без параметров.
Наконец, чтобы использовать версию этого репо, используйте следующую команду:
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 disabledСоздайте новый клиент GitHub, затем используйте различные службы на клиенте, чтобы получить доступ к различным частям API GitHub. Например:
client := github . NewClient ( nil )
// list all organizations for user "willnorris"
orgs , _ , err := client . Organizations . List ( context . Background (), "willnorris" , nil )Некоторые методы API имеют дополнительные параметры, которые могут быть переданы. Например:
client := github . NewClient ( nil )
// list public repositories for org "github"
opt := & github. RepositoryListByOrgOptions { Type : "public" }
repos , _ , err := client . Repositories . ListByOrg ( context . Background (), "github" , opt )Услуги клиента разделяют API на логические куски и соответствуют структуре документации GitHub API.
Примечание. Используя пакет контекста, можно легко передать сигналы отмены и сроки различным службам клиента для обработки запроса. В случае отсутствия контекста, то context.Background() может использоваться в качестве отправной точки.
Для получения дополнительных примеров фрагментов кода, перейдите к примеру каталога.
Используйте метод WithAuthToken для настройки вашего клиента для аутентификации с использованием токена OAuth (например, токен для личного доступа). Это то, что необходимо для большинства вариантов использования, кроме приложений GitHub.
client := github . NewClient ( nil ). WithAuthToken ( "... your access token ..." )Обратите внимание, что при использовании аутентифицированного клиента все вызовы, сделанные клиентом, будут включать указанный токен OAuth. Поэтому аутентифицированные клиенты должны почти никогда не распространяться между разными пользователями.
Для методов API, которые требуют базовой аутентификации HTTP, используйте BasicAuthTransport .
Аутентификация приложений GitHub может быть предоставлена различными PKG, такими как Bradleyfalzon/Ghinstallation или JFERRL/GO-Githubauth.
ПРИМЕЧАНИЕ . Большинство конечных точек (например,
GET /rate_limit) требуют аутентификации токена доступа, в то время как несколько других (Ex.GET /app/hook/deliveries) требует аутентификации JWT.
ghinstallation обеспечивает Transport , который реализует http.RoundTripper для обеспечения аутентификации в качестве установки для приложений GitHub.
Вот пример того, как аутентифицировать как приложение GitHub, используя пакет 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 реализует набор oauth2.TokenSource , который будет использоваться с oauth2.Client . oauth2.Client может быть введен в github.Client для аутентификации запросов.
Другой пример с использованием 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 )
}ПРИМЕЧАНИЕ . Чтобы взаимодействовать с определенными API, например, написание файла в репо, необходимо генерировать токен установки, используя идентификатор установки приложения GitHub и аутентификацию с помощью метода OAuth, упомянутого выше. Смотрите примеры.
GitHub налагает ограничение на всех клиентов API. Несанкционированные клиенты ограничены 60 запросами в час, в то время как аутентифицированные клиенты могут выполнять до 5000 запросов в час. Поисковый API имеет пользовательский предел ставки. Несанкционированные клиенты ограничены 10 запросами в минуту, в то время как аутентифицированные клиенты могут выполнять до 30 запросов в минуту. Чтобы получить более высокий предел ставки при совершении звонков, которые не выдаются от имени пользователя, используйте UnauthenticatedRateLimitedTransport .
Возвращаемый Response.Rate Если достаточно недавний ответ недоступен, вы можете использовать RateLimits для получения самых современных данных о пределе скорости для клиента.
Чтобы обнаружить ошибку ограничения скорости API, вы можете проверить, является ли его тип *github.RateLimitError :
repos , _ , err := client . Repositories . List ( ctx , "" , nil )
if _ , ok := err .( * github. RateLimitError ); ok {
log . Println ( "hit rate limit" )
}Узнайте больше об ограничении скорости GitHub в «конечных точках API REST для ограничений по скорости».
В дополнение к этим пределам ставки GitHub налагает вторичный предел ставки на всех клиентов API. Этот предел ставки не позволяет клиентам делать слишком много параллельных запросов.
Чтобы обнаружить ошибку ограничения вторичной скорости API, вы можете проверить, является ли его тип *github.AbuseRateLimitError :
repos , _ , err := client . Repositories . List ( ctx , "" , nil )
if _ , ok := err .( * github. AbuseRateLimitError ); ok {
log . Println ( "hit secondary rate limit" )
} В качестве альтернативы, вы можете блокировать, пока предел скорости не будет сброшен, используя метод context.WithValue .
repos , _ , err := client . Repositories . List ( context . WithValue ( ctx , github . SleepUntilPrimaryRateLimitResetWhenRateLimited , true ), "" , nil )Вы можете использовать GOFRI/GO-GitHub-RATELIMIT для обработки вторичного ограничения скорости для вас.
Узнайте больше о ограничении вторичной скорости Github в «Околе вторичных ограничений».
Некоторые конечные точки могут вернуть принятый код состояния 202, а это означает, что требуемая информация еще не готова и должна была собраться на стороне GitHub. Методы, которые, как известно, ведут себя, задокументированы, указывающие это поведение.
Чтобы обнаружить это условие ошибки, вы можете проверить, является ли его тип *github.AcceptedError :
stats , _ , err := client . Repositories . ListContributorsStats ( ctx , org , repo )
if _ , ok := err .( * github. AcceptedError ); ok {
log . Println ( "scheduled on GitHub side" )
} API GitHub имеет хорошую поддержку для условных запросов, которые помогут предотвратить сжигание вашего ограничения по ставке, а также помогать ускорить ваше заявление. go-github не обрабатывает условные запросы напрямую, но вместо этого предназначен для работы с кэшированием http.Transport . Мы рекомендуем использовать Gregjones/httpcache для этого. Например:
import "github.com/gregjones/httpcache"
client := github . NewClient (
httpcache . NewMemoryCacheTransport (). Client ()
). WithAuthToken ( os . Getenv ( "GITHUB_TOKEN" ))Узнайте больше о условных запросах GitHub в «Использование условных запросов, если это необходимо».
Все структуры для ресурсов GitHub используют значения указателей для всех не повторных полей. Это позволяет различить USET Поля и те, которые устанавливаются на нулевое значение. Были предоставлены вспомогательные функции, чтобы легко создать эти указатели для значений строки, bool и int. Например:
// create a new private repository named "foo"
repo := & github. Repository {
Name : github . Ptr ( "foo" ),
Private : github . Ptr ( true ),
}
client . Repositories . Create ( ctx , "" , repo )Пользователи, которые работали с буферами протокола, должны найти этот шаблон знакомым.
Все запросы на коллекции ресурсов (RepoS, запросы на вытягивание, проблемы и т. Д.) Поддерживают страницу. Параметры странификации описаны в структуре github.ListOptions и передаются в методы списка непосредственно или в виде встроенного типа более конкретной структуры параметров списка (например, github.PullRequestListOptions ). Информация о страницах доступна через github.Response struct.
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 представляет новый пакет iter .
С пакетом enrichman/gh-iter можно создать итераторы для go-github . Итератор будет обрабатывать лиц для вас, зацикливая все доступные результаты.
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 )
} Для полного использования enrichman/gh-iter см. В полных документах.
go-github предоставляет структуры практически для всех событий GitHub Webhook, а также функций для их проверки, а также полезные нагрузки Unmarshal JSON от 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 )
...
}
}Кроме того, существуют библиотеки, такие как CBRGM/GitHubevents, которые основаны на примере выше и предоставляют функции для подписки на обратные вызовы на конкретные события.
Для полного использования GO-GitHub см. В полных документах.
go-githubRepo Migueleliasweb/Go-Github-Mock предоставляет способ издеваться над ответами. Проверьте репо для получения более подробной информации.
Вы можете запустить интеграционные тесты из test Directory. См. Интеграционные тесты Readme.
Я хотел бы осветить весь API GitHub, и вклад, конечно, всегда приветствуются. Призванный шаблон довольно хорошо установлен, поэтому добавление новых методов является относительно простым. См. CONTRIBUTING.md для деталей.
В общем, Go-Github следует за Semver так же близко, как только мы можем, за тойте выбросы пакета. Для автономных библиотек применение семантической версии является относительно простым и в целом понятно. Но поскольку GO-GitHub-это клиентская библиотека для API GitHub, которая само по себе меняет поведение, и, поскольку мы, как правило, довольно агрессивно в реализации предварительных функций API GitHub, мы приняли следующую политику версий:
Функциональность предварительного просмотра может принимать форму целых методов или просто дополнительные данные, возвращаемые из-за не подвижного метода. Обратитесь к документации GitHub API для получения подробной информации о функциональности предварительного просмотра.
По состоянию на 2022-11-28 Github объявил, что они начинают версировать свой API V3 на основе «Календарной версии».
На практике наша цель состоит в том, чтобы сделать переопределение версии за метод (по крайней мере, в основной библиотеке) редким и временным.
Наше понимание документов GitHub заключается в том, что они будут направлять весь API на каждую новую версию на основе даты, даже если только несколько методов имеют нарушающие изменения. Другие методы примут новую версию с их существующей функциональностью. Таким образом, когда выпущена новая версия API GitHub, основанную на дате, мы планируем:
Обновите каждый метод, который имел нарушающие изменения, переопределяя их заголовок версии API на метод. Это может произойти в одном или нескольких коммитах и PRS, и все это сделано в основной ветви.
Как только все методы с нарушающими изменениями были обновлены, проведут окончательный коммит, который усиливает версию API по умолчанию и удаляет все переопределения на метод. Теперь это получит крупную версию, когда будет сделан следующий релиз Go-GitHub.
В следующей таблице указана, какая версия GitHub API поддерживается этой (и прошлой) версиями этого репо (go-github). Версии до 48.2.0 не указаны.
| Go-GitHub версия | Github v3 api версия |
|---|---|
| 68.0.0 | 2022-11-28 |
| ... | 2022-11-28 |
| 48.2.0 | 2022-11-28 |
Эта библиотека распространяется по лицензии в стиле BSD, найденной в файле лицензии.
