google/go-github: a typed Go client for the GitHub REST API

What go-github actually solves, and for whom

The GitHub REST API is large. It has pagination, optional query parameters, rate limits and a response shape that changes per endpoint. Calling it with net/http means writing that plumbing yourself and keeping it in sync as endpoints move. go-github replaces that with a Go client whose services mirror the structure of the GitHub API documentation: client.Organizations, client.Repositories, and so on. Each call returns typed structs rather than raw JSON.

The audience is Go developers writing automation. A CLI that opens pull requests, a service that reconciles repository settings, a script that pulls audit logs: anything where you would otherwise hand-roll requests. The README's own example lists organizations for a user and then lists public repositories for an org, which is the shape of most first tasks. If you are writing a one-off shell script, curl plus jq is less machinery. If you are writing something that will be compiled and maintained, the typed layer pays for itself.

How the client is structured and how a call flows

A github.Client holds a service per API area. Calling client.Repositories.ListByOrg sends an HTTP request, decodes the JSON body into Go structs, and returns the slice plus a response object plus an error. The middle return value is where pagination and rate-limit metadata live; the README's examples discard it with an underscore, but production code generally should not.

Optional parameters are passed as an options struct, not as positional arguments. The README shows github.RepositoryListByOrgOptions{Type: "public"} for filtering. This is the pattern across the library: a struct with pointer fields, so the client can tell the difference between an unset value and a zero value. It is verbose, and it is the reason the library can add parameters without breaking callers.

Every call takes a context.Context as its first argument. The README notes that this lets you pass cancellation signals and deadlines, and that context.Background() works when no context is available. That design choice means a hung request is your problem to solve, not the library's.

The module depends on github.com/google/go-querystring for query encoding and github.com/google/go-cmp for tests. The repository also contains an otel/ directory and an example/otel/, so OpenTelemetry instrumentation exists in some form, though the README does not document it.

Installing go-github and making a first authenticated call

The README gives the module path with the major version baked in. In an existing module, run this to resolve and add the package and its dependencies:

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

Alternatively, add the import and run go get with no arguments. The import path is the same string:

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

For unauthenticated calls you can construct a client with no options. For anything that touches private data or hits rate limits, the README recommends github.WithAuthToken with a personal access token:

client, err := github.NewClient(github.WithAuthToken("... your access token ..."))
if err != nil {
	// Handle error.
}

Once the client exists, services hang off it. This is the README's first example, listing organizations for a user:

orgs, _, err := client.Organizations.List(context.Background(), "willnorris", nil)

What you should see on success is a slice of organization structs and a nil error. If the token is missing or wrong, the error is where the failure surfaces. Note the README's warning that an authenticated client attaches its token to every call, so authenticated clients should almost never be shared between users. For GitHub App authentication the README points at bradleyfalzon/ghinstallation, which provides a Transport implementing http.RoundTripper, passed in through github.WithTransport. A second option is jferrl/go-githubauth. The README also notes that most endpoints need access token authentication while a few, such as GET /app/hook/deliveries, need JWT authentication.

The Go version requirement is the sharpest edge

go.mod declares go 1.26.0. The README explains that as of Go 1.26 the go directive declares a hard required minimum version, and that it must be greater than or equal to the go line of all dependencies, so go-github will require the N-1 major release of Go by default. In practice this means the library can raise your project's effective Go floor when you upgrade it.

The README also says the project tracks Go's version support policy, supporting any minor version of the latest two major releases, and that older versions are not explicitly tested even if they are not deliberately broken. That is a narrower window than many Go libraries offer. If your build image pins an older toolchain, a go-github upgrade can fail before you write a line of code.

The second edge is the import path. It contains v92. Every major release changes that string, so an upgrade is not a version bump in go.mod alone; it is an edit to every import in your codebase. The project does not hide this, and the versioning is honest, but it is real work each time. The README offers one mitigation for review: clone the repo and run go run tools/gen-release-notes/main.go --tag v92.0.0 to see what changed since a prior release.

When go-github is the wrong tool

The README is direct about the biggest gap: if you are interested in the GraphQL API v4, the recommended library is shurcooL/githubv4. That is not a side note. go-github targets the v3 REST API, and GraphQL queries do not map onto its service-and-struct model. If your task is fetching a nested graph of issues, labels and reviewers in one round trip, REST plus go-github will take several calls and you will assemble the result yourself.

The second case is authentication scope. The README's note is unambiguous: most endpoints require access token authentication, while a few require JWT. If your workload mixes both, you are managing two authentication paths, and go-github only supplies the client side of that. The GitHub App transports come from separate packages.

The third case is size. If you need two endpoints in a short-lived script, the dependency and the versioned import path may cost more than the requests you save. The library is a client, not a framework, and it does not manage retries or backoff for you beyond what the underlying HTTP client does.

go-github against githubv4 and hand-written HTTP

The comparison the README itself makes is with shurcooL/githubv4. The difference is not quality, it is the protocol. go-github speaks REST: one endpoint per operation, typed Go structs for responses, services grouped to match the API documentation. githubv4 speaks GraphQL: you write a query, and you get back only the fields you asked for. For a tool that reads a handful of fields from many objects, GraphQL can collapse several REST calls into one. For a tool that performs one well-defined mutation, REST is simpler to reason about and easier to log.

The other alternative is no library at all. net/http plus encoding/json gives you full control and no versioned import path. You pay for it in pagination handling, query-string construction and struct definitions for every response you touch. go-github's value is that those definitions already exist and are tested; the cost is that you inherit its release cadence and its Go version floor.

Maintenance, upgrades and the BSD-3-Clause licence

The repository is not archived, and the last push was on 2026-09-21. Releases are frequent: v92.0.0 on 2026-09-14, v91.0.0 on 2026-09-03, v90.0.0 on 2026-08-04. That cadence is a maintenance cost as much as a signal. Major versions arrive roughly monthly, and each one changes the import path. A team that wants to stay current should expect to touch imports and go.mod regularly, and to check the release notes for behaviour changes. A team that pins a version can stay put, but then it is not receiving endpoint additions that GitHub ships.

The licence is BSD-3-Clause, a permissive licence that allows use, modification and redistribution provided the copyright notice and disclaimer are retained. That is the standard shape for a client library and imposes no copyleft obligation on your code. This is a description of the licence text, not legal advice; if your organisation has specific redistribution or patent requirements, have counsel read the LICENSE file.

The repository carries a CONTRIBUTING.md, an AUTHORS file, REVIEWERS, and an AGENTS.md, so the contribution path is documented. The README points discussion at the [email protected] mailing list, and the project holds a CII Best Practices badge.

Editorial conclusion

Adopt go-github if you want typed Go access to the REST API without writing HTTP plumbing, and if you can track the module's major version and its Go minimum. Do not adopt it for GraphQL work: the README points at shurcooL/githubv4 instead. Before you commit, check that your toolchain satisfies the go directive in go.mod, and read the release notes for the major version you import, because the import path carries v92 and every bump touches your import lines and go.mod.

Frequently asked questions

Official sources

1. google/go-github on GitHub
2. License: BSD-3-Clause
3. Project website
4. README
5. Releases