go github
v68.0.0
Go-Github는 Github API V3에 액세스하기위한 GO 클라이언트 라이브러리입니다.
Go-Github에는 GO 버전 1.17 이상이 필요하며 라이브러리는 GO 버전 1.22 이상에 대해 테스트됩니다. go-github는 Go의 버전 지원 정책을 추적합니다. 우리는 필요하지 않으면 이전 버전의 GO를 깨지 않기 위해 최선을 다하지만 툴링 제약으로 인해 항상 이전 버전을 테스트하지는 않습니다.
GraphQL API V4 사용에 관심이 있으시면 권장 라이브러리는 Shurcool/Githubv4입니다.
Go-Github는 GO가 설치된 모듈 모드의 Modern 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 기본 인증이 필요한 API 메소드의 경우 BasicAuthTransport 사용하십시오.
GitHub 앱 인증은 Bradleyfalzon/Ghinstallation 또는 Jferrl/Go-Githubauth와 같은 다양한 PKG에서 제공 할 수 있습니다.
참고 : 대부분의 엔드 포인트 (ex.
GET /rate_limit)는 액세스 토큰 인증이 필요하지만 다른 몇 가지 (ex.GET /app/hook/deliveries)는 JWT 인증이 필요합니다.
ghinstallation http.RoundTripper 구현하여 GitHub 앱 설치로 인증을 제공하는 Transport 제공합니다.
다음은 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와 상호 작용하기 위해, 예를 들어 파일을 Repo에 작성하려면 GitHub 앱의 설치 ID를 사용하여 설치 토큰을 생성하고 위에서 언급 한 OAUTH 방법으로 인증해야합니다. 예제를 참조하십시오.
Github는 모든 API 클라이언트에 요율 제한을 부과합니다. 인증되지 않은 고객은 시간당 60 개의 요청으로 제한되며 인증 된 고객은 시간당 최대 5,000 개의 요청을 구성 할 수 있습니다. 검색 API에는 사용자 정의 속도 제한이 있습니다. 인증되지 않은 고객은 분당 10 개의 요청으로 제한되며 인증 된 고객은 분당 최대 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" )
}"속도 제한에 대한 API 엔드 포인트"에서 Github 요금 제한에 대해 자세히 알아보십시오.
이러한 비율 제한 외에도 GitHub는 모든 API 클라이언트에 2 차 요율 제한을 부과합니다. 이 요율 제한은 고객이 너무 많은 동시 요청을하지 못하게합니다.
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를 사용하여 2 차 속도 제한 수면 및 레트로를 처리 할 수 있습니다.
"2 차 요율 제한"에서 Github 2 차 요율 제한에 대해 자세히 알아보십시오.
일부 엔드 포인트는 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 리소스의 모든 스트러크는 반복되지 않은 모든 필드에 포인터 값을 사용합니다. 이를 통해 UNSET 필드와 제로 가치로 설정된 필드를 구별 할 수 있습니다. 스트링, 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 )프로토콜 버퍼와 함께 일한 사용자는이 패턴이 익숙하다는 것을 알게됩니다.
리소스 컬렉션 (저장소, 풀 요청, 문제 등)에 대한 모든 요청은 페이지 매김을 지원합니다. Pagination 옵션은 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 용 반복자를 만들 수 있습니다. 반복자는 사용 가능한 모든 결과를 반복하여 Pagination을 처리합니다.
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에서이를 검증하고 Unmarshal 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는 "Calendar-Versioning"을 기반으로 V3 API 버전을 시작한다고 발표했습니다.
실제로, 우리의 목표는 메드 당 버전을 (적어도 핵심 라이브러리에서) 희귀하고 일시적으로 무시하는 것입니다.
GitHub 문서에 대한 우리의 이해는 몇 가지 방법 만 변경을 해제하더라도 전체 API를 각각의 새로운 날짜 기반 버전으로 회복시킬 것이라는 점입니다. 다른 방법은 기존 기능으로 새 버전을 허용합니다. 따라서 새로운 날짜 기반 버전의 GitHub API 버전이 출시되면 우리는 다음을 계획합니다.
메모드 당 API 버전 헤더를 우선시하여 변경 사항을 깨뜨린 각 방법을 업데이트하십시오. 이것은 하나 또는 다중 커밋 및 PR에서 발생할 수 있으며 모두 메인 브랜치에서 수행됩니다.
변경 사항이 중단 된 모든 메소드가 업데이트되면 기본 API 버전을 충돌시키는 최종 커밋을 사용하고 메드 당 모든 것을 제거하십시오. 다음 Go-Github 릴리스가 만들어지면 이제 주요 버전 범프가 발생합니다.
다음 표는이 Repo (go-github) 의이 (및 과거) 버전에서 어떤 버전의 Github API를 지원하는지 식별합니다. 48.2.0 이전 버전은 나열되지 않습니다.
| go-github 버전 | Github v3 API 버전 |
|---|---|
| 68.0.0 | 2022-11-28 |
| ... | 2022-11-28 |
| 48.2.0 | 2022-11-28 |
이 라이브러리는 라이센스 파일에있는 BSD 스타일 라이센스에 따라 배포됩니다.
