• Stars
    star
    9,941
  • Rank 3,281 (Top 0.07 %)
  • Language
    Go
  • License
    BSD 3-Clause "New...
  • Created almost 11 years ago
  • Updated about 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Go library for accessing the GitHub v3 API

go-github

go-github release (latest SemVer) GoDoc Test Status Test Coverage Discuss at go-github@googlegroups.com CII Best Practices

go-github is a Go client library for accessing the GitHub API v3.

Currently, go-github requires Go version 1.13 or greater. go-github tracks Go's version support policy. We do our best not to break older versions of Go if we don't have to, but due to tooling constraints, we don't always test older versions.

If you're interested in using the GraphQL API v4, the recommended library is shurcooL/githubv4.

Installation

go-github is compatible with modern Go releases in module mode, with Go installed:

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

will resolve and add the package to the current development module, along with its dependencies.

Alternatively the same can be achieved if you use import in a package:

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

and run go get without parameters.

Finally, to use the top-of-trunk version of this repo, use the following command:

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

Usage

import "github.com/google/go-github/v60/github"	// with go modules enabled (GO111MODULE=on or outside GOPATH)
import "github.com/google/go-github/github" // with go modules disabled

Construct a new GitHub client, then use the various services on the client to access different parts of the GitHub API. For example:

client := github.NewClient(nil)

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

Some API methods have optional parameters that can be passed. For example:

client := github.NewClient(nil)

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

The services of a client divide the API into logical chunks and correspond to the structure of the GitHub API documentation at https://docs.github.com/en/rest .

NOTE: Using the context package, one can easily pass cancelation signals and deadlines to various services of the client for handling a request. In case there is no context available, then context.Background() can be used as a starting point.

For more sample code snippets, head over to the example directory.

Authentication

Use the WithAuthToken method to configure your client to authenticate using an OAuth token (for example, a personal access token). This is what is needed for a majority of use cases aside from GitHub Apps.

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

Note that when using an authenticated Client, all calls made by the client will include the specified OAuth token. Therefore, authenticated clients should almost never be shared between different users.

For API methods that require HTTP Basic Authentication, use the BasicAuthTransport.

As a GitHub App

GitHub Apps authentication can be provided by the ghinstallation package.

Note: Most endpoints (ex. GET /rate_limit) require access token authentication while a few others (ex. GET /app/hook/deliveries) require JWT authentication.

import (
	"net/http"

	"github.com/bradleyfalzon/ghinstallation/v2"
	"github.com/google/go-github/v60/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...
}

Note: In order to interact with certain APIs, for example writing a file to a repo, one must generate an installation token using the installation ID of the GitHub app and authenticate with the OAuth method mentioned above. See the examples.

Rate Limiting

GitHub imposes a rate limit on all API clients. Unauthenticated clients are limited to 60 requests per hour, while authenticated clients can make up to 5,000 requests per hour. The Search API has a custom rate limit. Unauthenticated clients are limited to 10 requests per minute, while authenticated clients can make up to 30 requests per minute. To receive the higher rate limit when making calls that are not issued on behalf of a user, use UnauthenticatedRateLimitedTransport.

The returned Response.Rate value contains the rate limit information from the most recent API call. If a recent enough response isn't available, you can use RateLimits to fetch the most up-to-date rate limit data for the client.

To detect an API rate limit error, you can check if its type is *github.RateLimitError:

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

Learn more about GitHub rate limiting at https://docs.github.com/en/rest/rate-limit .

In addition to these rate limits, GitHub imposes a secondary rate limit on all API clients. This rate limit prevents clients from making too many concurrent requests.

To detect an API secondary rate limit error, you can check if its type is *github.AbuseRateLimitError:

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

You can use go-github-ratelimit to handle secondary rate limit sleep-and-retry for you.

Learn more about GitHub secondary rate limiting at https://docs.github.com/en/rest/overview/resources-in-the-rest-api#secondary-rate-limits .

Accepted Status

Some endpoints may return a 202 Accepted status code, meaning that the information required is not yet ready and was scheduled to be gathered on the GitHub side. Methods known to behave like this are documented specifying this behavior.

To detect this condition of error, you can check if its type is *github.AcceptedError:

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

Conditional Requests

The GitHub API has good support for conditional requests which will help prevent you from burning through your rate limit, as well as help speed up your application. go-github does not handle conditional requests directly, but is instead designed to work with a caching http.Transport. We recommend using https://github.com/gregjones/httpcache for that. For example:

import "github.com/gregjones/httpcache"

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

Learn more about GitHub conditional requests at https://docs.github.com/en/rest/overview/resources-in-the-rest-api#conditional-requests.

Creating and Updating Resources

All structs for GitHub resources use pointer values for all non-repeated fields. This allows distinguishing between unset fields and those set to a zero-value. Helper functions have been provided to easily create these pointers for string, bool, and int values. For example:

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

Users who have worked with protocol buffers should find this pattern familiar.

Pagination

All requests for resource collections (repos, pull requests, issues, etc.) support pagination. Pagination options are described in the github.ListOptions struct and passed to the list methods directly or as an embedded type of a more specific list options struct (for example github.PullRequestListOptions). Pages information is available via the 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
}

Webhooks

go-github provides structs for almost all GitHub webhook events as well as functions to validate them and unmarshal JSON payloads from http.Request structs.

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

Furthermore, there are libraries like cbrgm/githubevents that build upon the example above and provide functions to subscribe callbacks to specific events.

For complete usage of go-github, see the full package docs.

Testing code that uses go-github

The repo migueleliasweb/go-github-mock provides a way to mock responses. Check the repo for more details.

Integration Tests

You can run integration tests from the test directory. See the integration tests README.

Contributing

I would like to cover the entire GitHub API and contributions are of course always welcome. The calling pattern is pretty well established, so adding new methods is relatively straightforward. See CONTRIBUTING.md for details.

Versioning

In general, go-github follows semver as closely as we can for tagging releases of the package. For self-contained libraries, the application of semantic versioning is relatively straightforward and generally understood. But because go-github is a client library for the GitHub API, which itself changes behavior, and because we are typically pretty aggressive about implementing preview features of the GitHub API, we've adopted the following versioning policy:

  • We increment the major version with any incompatible change to non-preview functionality, including changes to the exported Go API surface or behavior of the API.
  • We increment the minor version with any backwards-compatible changes to functionality, as well as any changes to preview functionality in the GitHub API. GitHub makes no guarantee about the stability of preview functionality, so neither do we consider it a stable part of the go-github API.
  • We increment the patch version with any backwards-compatible bug fixes.

Preview functionality may take the form of entire methods or simply additional data returned from an otherwise non-preview method. Refer to the GitHub API documentation for details on preview functionality.

Calendar Versioning

As of 2022-11-28, GitHub has announced that they are starting to version their v3 API based on "calendar-versioning".

In practice, our goal is to make per-method version overrides (at least in the core library) rare and temporary.

Our understanding of the GitHub docs is that they will be revving the entire API to each new date-based version, even if only a few methods have breaking changes. Other methods will accept the new version with their existing functionality. So when a new date-based version of the GitHub API is released, we (the repo maintainers) plan to:

  • update each method that had breaking changes, overriding their per-method API version header. This may happen in one or multiple commits and PRs, and is all done in the main branch.

  • once all of the methods with breaking changes have been updated, have a final commit that bumps the default API version, and remove all of the per-method overrides. That would now get a major version bump when the next go-github release is made.

Version Compatibility Table

The following table identifies which version of the GitHub API is supported by this (and past) versions of this repo (go-github). Versions prior to 48.2.0 are not listed.

go-github Version GitHub v3 API Version
60.0.0 2022-11-28
59.0.0 2022-11-28
58.0.0 2022-11-28
57.0.0 2022-11-28
56.0.0 2022-11-28
55.0.0 2022-11-28
54.0.0 2022-11-28
53.2.0 2022-11-28
53.1.0 2022-11-28
53.0.0 2022-11-28
52.0.0 2022-11-28
51.0.0 2022-11-28
50.2.0 2022-11-28
50.1.0 2022-11-28
50.0.0 2022-11-28
49.1.0 2022-11-28
49.0.0 2022-11-28
48.2.0 2022-11-28

License

This library is distributed under the BSD-style license found in the LICENSE file.

More Repositories

1

material-design-icons

Material Design icons by Google
49,605
star
2

guava

Google core libraries for Java
Java
48,313
star
3

zx

A tool for writing better scripts
JavaScript
37,928
star
4

styleguide

Style guides for Google-originated open-source projects
HTML
36,377
star
5

leveldb

LevelDB is a fast key-value storage library written at Google that provides an ordered mapping from string keys to string values.
C++
33,564
star
6

material-design-lite

Material Design Components in HTML/CSS/JS
HTML
32,276
star
7

googletest

GoogleTest - Google Testing and Mocking Framework
C++
32,215
star
8

jax

Composable transformations of Python+NumPy programs: differentiate, vectorize, JIT to GPU/TPU, and more
Python
27,471
star
9

python-fire

Python Fire is a library for automatically generating command line interfaces (CLIs) from absolutely any Python object.
Python
26,112
star
10

mediapipe

Cross-platform, customizable ML solutions for live and streaming media.
C++
25,107
star
11

comprehensive-rust

This is the Rust course used by the Android team at Google. It provides you the material to quickly teach Rust.
Rust
24,867
star
12

gson

A Java serialization/deserialization library to convert Java Objects into JSON and back
Java
22,856
star
13

flatbuffers

FlatBuffers: Memory Efficient Serialization Library
C++
21,883
star
14

iosched

The Google I/O Android App
Kotlin
21,801
star
15

ExoPlayer

An extensible media player for Android
Java
21,309
star
16

eng-practices

Google's Engineering Practices documentation
19,715
star
17

web-starter-kit

Web Starter Kit - a workflow for multi-device websites
HTML
18,426
star
18

flexbox-layout

Flexbox for Android
Kotlin
18,141
star
19

fonts

Font files available from Google Fonts, and a public issue tracker for all things Google Fonts
HTML
17,389
star
20

filament

Filament is a real-time physically based rendering engine for Android, iOS, Windows, Linux, macOS, and WebGL2
C++
16,946
star
21

cadvisor

Analyzes resource usage and performance characteristics of running containers.
Go
16,184
star
22

libphonenumber

Google's common Java, C++ and JavaScript library for parsing, formatting, and validating international phone numbers.
C++
15,728
star
23

gvisor

Application Kernel for Containers
Go
14,646
star
24

WebFundamentals

Former git repo for WebFundamentals on developers.google.com
JavaScript
13,848
star
25

yapf

A formatter for Python files
Python
13,560
star
26

tink

Tink is a multi-language, cross-platform, open source library that provides cryptographic APIs that are secure, easy to use correctly, and hard(er) to misuse.
Java
13,318
star
27

deepdream

13,212
star
28

brotli

Brotli compression format
TypeScript
12,921
star
29

guetzli

Perceptual JPEG encoder
C++
12,863
star
30

guice

Guice (pronounced 'juice') is a lightweight dependency injection framework for Java 8 and above, brought to you by Google.
Java
12,324
star
31

wire

Compile-time Dependency Injection for Go
Go
12,131
star
32

blockly

The web-based visual programming editor.
TypeScript
12,033
star
33

grumpy

Grumpy is a Python to Go source code transcompiler and runtime.
Go
10,464
star
34

sanitizers

AddressSanitizer, ThreadSanitizer, MemorySanitizer
C
10,437
star
35

dopamine

Dopamine is a research framework for fast prototyping of reinforcement learning algorithms.
Jupyter Notebook
10,319
star
36

or-tools

Google's Operations Research tools:
C++
10,299
star
37

auto

A collection of source code generators for Java.
Java
10,234
star
38

oss-fuzz

OSS-Fuzz - continuous fuzzing for open source software.
Shell
9,324
star
39

go-cloud

The Go Cloud Development Kit (Go CDK): A library and tools for open cloud development in Go.
Go
9,314
star
40

sentencepiece

Unsupervised text tokenizer for Neural Network-based text generation.
C++
8,657
star
41

re2

RE2 is a fast, safe, thread-friendly alternative to backtracking regular expression engines like those used in PCRE, Perl, and Python. It is a C++ library.
C++
8,190
star
42

traceur-compiler

Traceur is a JavaScript.next-to-JavaScript-of-today compiler
JavaScript
8,178
star
43

tsunami-security-scanner

Tsunami is a general purpose network security scanner with an extensible plugin system for detecting high severity vulnerabilities with high confidence.
Java
8,036
star
44

trax

Trax β€” Deep Learning with Clear Code and Speed
Python
7,917
star
45

skia

Skia is a complete 2D graphic library for drawing Text, Geometries, and Images.
C++
7,874
star
46

benchmark

A microbenchmark support library
C++
7,812
star
47

android-classyshark

Android and Java bytecode viewer
Java
7,440
star
48

pprof

pprof is a tool for visualization and analysis of profiling data
Go
7,235
star
49

agera

Reactive Programming for Android
Java
7,227
star
50

closure-compiler

A JavaScript checker and optimizer.
Java
7,195
star
51

magika

Detect file content types with deep learning
Python
7,171
star
52

accompanist

A collection of extension libraries for Jetpack Compose
Kotlin
7,157
star
53

flutter-desktop-embedding

Experimental plugins for Flutter for Desktop
C++
7,108
star
54

diff-match-patch

Diff Match Patch is a high-performance library in multiple languages that manipulates plain text.
Python
6,918
star
55

lovefield

Lovefield is a relational database for web apps. Written in JavaScript, works cross-browser. Provides SQL-like APIs that are fast, safe, and easy to use.
JavaScript
6,847
star
56

glog

C++ implementation of the Google logging module
C++
6,748
star
57

jsonnet

Jsonnet - The data templating language
Jsonnet
6,711
star
58

latexify_py

A library to generate LaTeX expression from Python code.
Python
6,708
star
59

error-prone

Catch common Java mistakes as compile-time errors
Java
6,690
star
60

model-viewer

Easily display interactive 3D models on the web and in AR!
TypeScript
6,390
star
61

gops

A tool to list and diagnose Go processes currently running on your system
Go
6,375
star
62

automl

Google Brain AutoML
Jupyter Notebook
6,113
star
63

gopacket

Provides packet processing capabilities for Go
Go
6,067
star
64

physical-web

The Physical Web: walk up and use anything
Java
6,017
star
65

j2objc

A Java to iOS Objective-C translation tool and runtime.
Java
5,975
star
66

grafika

Grafika test app
Java
5,964
star
67

draco

Draco is a library for compressing and decompressing 3D geometric meshes and point clouds. It is intended to improve the storage and transmission of 3D graphics.
C++
5,947
star
68

snappy

A fast compressor/decompressor
C++
5,940
star
69

ios-webkit-debug-proxy

A DevTools proxy (Chrome Remote Debugging Protocol) for iOS devices (Safari Remote Web Inspector).
C
5,848
star
70

osv-scanner

Vulnerability scanner written in Go which uses the data provided by https://osv.dev
Go
5,763
star
71

seesaw

Seesaw v2 is a Linux Virtual Server (LVS) based load balancing platform.
Go
5,586
star
72

seq2seq

A general-purpose encoder-decoder framework for Tensorflow
Python
5,577
star
73

EarlGrey

🍡 iOS UI Automation Test Framework
Objective-C
5,570
star
74

google-java-format

Reformats Java source code to comply with Google Java Style.
Java
5,366
star
75

flax

Flax is a neural network library for JAX that is designed for flexibility.
Python
5,358
star
76

wireit

Wireit upgrades your npm/pnpm/yarn scripts to make them smarter and more efficient.
TypeScript
5,280
star
77

battery-historian

Battery Historian is a tool to analyze battery consumers using Android "bugreport" files.
Go
5,249
star
78

clusterfuzz

Scalable fuzzing infrastructure.
Python
5,170
star
79

bbr

5,156
star
80

gumbo-parser

An HTML5 parsing library in pure C99
HTML
5,141
star
81

git-appraise

Distributed code review system for Git repos
Go
5,090
star
82

google-authenticator

Open source version of Google Authenticator (except the Android app)
Java
5,077
star
83

gemma.cpp

lightweight, standalone C++ inference engine for Google's Gemma models.
C++
5,076
star
84

syzkaller

syzkaller is an unsupervised coverage-guided kernel fuzzer
Go
5,063
star
85

uuid

Go package for UUIDs based on RFC 4122 and DCE 1.1: Authentication and Security Services.
Go
4,942
star
86

gts

β˜‚οΈ TypeScript style guide, formatter, and linter.
TypeScript
4,890
star
87

closure-library

Google's common JavaScript library
JavaScript
4,832
star
88

cameraview

[DEPRECATED] Easily integrate Camera features into your Android app
Java
4,734
star
89

grr

GRR Rapid Response: remote live forensics for incident response
Python
4,627
star
90

liquidfun

2D physics engine for games
C++
4,559
star
91

pytype

A static type analyzer for Python code
Python
4,454
star
92

gxui

An experimental Go cross platform UI library.
Go
4,450
star
93

bloaty

Bloaty: a size profiler for binaries
C++
4,386
star
94

clasp

πŸ”— Command Line Apps Script Projects
TypeScript
4,336
star
95

ko

Build and deploy Go applications on Kubernetes
Go
4,329
star
96

santa

A binary authorization and monitoring system for macOS
Objective-C
4,288
star
97

google-ctf

Google CTF
Go
4,237
star
98

tamperchrome

Tamper Dev is an extension that allows you to intercept and edit HTTP/HTTPS requests and responses as they happen without the need of a proxy. Works across all operating systems (including Chrome OS).
TypeScript
4,137
star
99

end-to-end

End-To-End is a crypto library to encrypt, decrypt, digital sign, and verify signed messages (implementing OpenPGP)
JavaScript
4,126
star
100

orbit

C/C++ Performance Profiler
C++
3,981
star