go github
v68.0.0
Go-Githubは、GitHub API V3にアクセスするためのGOクライアントライブラリです。
Go-GithubにはGOバージョン1.17以上が必要であり、ライブラリはGOバージョン1.22以上に対してテストされます。 Go-GitHub Tracks Goのバージョンサポートポリシー。必要でない場合は、古いバージョンのGOのバージョンを破らないように最善を尽くしますが、ツールの制約により、常に古いバージョンをテストするとは限りません。
GraphQL API V4の使用に興味がある場合は、推奨ライブラリはShurcool/Githubv4です。
Go-Githubは、モジュールモードのMossent 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クライアントを構築し、クライアントのさまざまなサービスを使用して、Github APIのさまざまな部分にアクセスします。例えば：
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トークンが含まれることに注意してください。したがって、認証されたクライアントは、異なるユーザー間でほとんど共有されるべきではありません。
HTTP Basic認証を必要とするAPIメソッドの場合、 BasicAuthTransportを使用します。
GitHub Apps認証は、Bradleyfalzon/GhinstallationやJFerrl/Go-GithubauthなどのさまざまなPKGによって提供できます。
注：ほとんどのエンドポイント（例：
GET /rate_limit）にアクセストークン認証が必要ですが、他のいくつか（ex。getGET /app/hook/deliveries）にはJWT認証が必要です。
ghinstallation Transportを提供します。これにより、 http.RoundTripperを実装して、Githubアプリのインストールとして認証を提供します。
ghinstallationパッケージを使用してGitHubアプリとして認証する方法の例を次に示します。
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.Clientで使用するoauth2.TokenSourceのセットを実装します。 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アプリのインストールIDを使用してインストールトークンを生成し、上記のOAUTHメソッドで認証する必要があります。例を参照してください。
GitHubは、すべてのAPIクライアントにレート制限を課します。認証されていないクライアントは1時間あたり60のリクエストに制限されていますが、認証されたクライアントは1時間あたり最大5,000のリクエストを作成できます。検索APIにはカスタムレート制限があります。認証されていないクライアントは1分あたり10回のリクエストに制限されていますが、認証されたクライアントは1分あたり最大30のリクエストを作成できます。ユーザーに代わって発行されない電話をかけるときに高い料金制限を受信するには、 UnauthenticatedRateLimitedTransportを使用してください。
返されたResponse.Rate値には、最新のAPI呼び出しからのレート制限情報が含まれています。最近の十分な応答が利用できない場合は、 RateLimitsを使用して、クライアントの最新のレート制限データを取得できます。
APIレート制限エラーを検出するには、そのタイプが*github.RateLimitErrorであるかどうかを確認できます。
repos , _ , err := client . Repositories . List ( ctx , "" , nil )
if _ , ok := err .( * github. RateLimitError ); ok {
log . Println ( "hit rate limit" )
}「レート制限のためのREST APIエンドポイント」でGitHubレートの制限の詳細をご覧ください。
これらのレート制限に加えて、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" )
}GitHub APIは、レートの制限を燃やすのを防ぎ、アプリケーションのスピードを上げるのに役立つ条件付きリクエストを適切にサポートしています。 go-github条件付きリクエストを直接処理しませんが、代わりにキャッシュhttp.Transportで動作するように設計されています。そのためには、gregjones/httpcacheを使用することをお勧めします。例えば：
import "github.com/gregjones/httpcache"
client := github . NewClient (
httpcache . NewMemoryCacheTransport (). Client ()
). WithAuthToken ( os . Getenv ( "GITHUB_TOKEN" ))「必要に応じて条件付きリクエストを使用」でGitHub条件要求の詳細をご覧ください。
GitHubリソースのすべての構造体は、すべての非繰り返しフィールドにポインター値を使用します。これにより、絶え間ないフィールドとゼロ値に設定されたフィールドを区別できます。ヘルパー関数が提供されており、弦、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 )プロトコルバッファーを扱ったユーザーは、このパターンが馴染みのあるものであることがわかります。
リソースコレクション（リポジトリ、プルリクエスト、問題など）のすべてのリクエストは、ページネーションをサポートします。ページネーションオプションは、 github.ListOptions structで説明され、直接リストメソッドに渡されるか、より具体的なリストオプション構造の埋め込み型（ 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イベントの構造体と、それらを検証する機能と、 http.Request structsのJSONペイロードを除外します。
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-githubを使用するテストコードRepo MigueleliasWeb/Go-Github-Mockは、応答を模倣する方法を提供します。詳細については、レポを確認してください。
testディレクトリから統合テストを実行できます。統合テストreadmeを参照してください。
Github API全体をカバーしたいと思います。もちろん、貢献は常に大歓迎です。呼び出しパターンはかなり確立されているため、新しい方法を追加することは比較的簡単です。詳細については、 CONTRIBUTING.mdを参照してください。
一般に、Go-Githubは、パッケージのリリースにタグを付けるためにできる限りSemverを密接に追跡します。自己完結型ライブラリの場合、セマンティックバージョンの適用は比較的簡単で、一般的に理解されています。しかし、Go-GithubはGithub API自体のクライアントライブラリであるため、動作自体が変化し、Github APIのプレビュー機能を実装することに通常かなり攻撃的であるため、次のバージョン化ポリシーを採用しました。
プレビュー機能は、メソッド全体の形または単に非プレビューメソッドから返される追加データを取得する場合があります。プレビュー機能の詳細については、GitHub APIドキュメントを参照してください。
2022-11-28の時点で、Githubは「カレンダーバージョン」に基づいてV3 APIのバージョンを開始し始めていると発表しました。
実際には、私たちの目標は、メソッドごとのバージョンを（少なくともコアライブラリで）無効化することです。
GitHubドキュメントについての私たちの理解は、たとえいくつかの方法が変更されている場合でも、新しい日付ベースのバージョンごとにAPI全体を回転させることです。他の方法では、既存の機能を使用して新しいバージョンを受け入れます。したがって、GitHub APIの新しい日付ベースのバージョンがリリースされると、次のように計画しています。
壊れた変更がある各メソッドを更新し、Method Per-Method APIバージョンヘッダーをオーバーライドします。これは、1つまたは複数のコミットと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スタイルのライセンスの下に配布されています。
