Master go-github in 5 Minutes: A Rapid GitHub API Guide for Go Developers

Many developers still manually concatenate GitHub API requests, struggle with token management, pagination, and rate‑limit handling. This article walks you through getting started with the go-github library in just a few minutes.

Installation and environment configuration

go-github follows Go modules; install it with a single command (requires Go 1.16+): go get github.com/google/go-github/v76 The library’s source resides in the github/ directory, with API services such as github/repos.go and github/users.go.

Quick start – first API call

Create a GitHub client; the simplest anonymous client is initialized as follows:

package main

import (
    "context"
    "fmt"
    "github.com/google/go-github/v76/github"
)

func main() {
    client := github.NewClient(nil)
    meta, _, err := client.Meta.Status(context.Background())
    if err != nil {
        fmt.Printf("Failed to get status: %v
", err)
        return
    }
    fmt.Printf("GitHub status: %s
", meta.Status)
}

This code (from example/simple/main.go) demonstrates creating a basic client and calling the Meta API. Initialise the module with go mod init before running.

Authentication configuration – unlocking full API capabilities

Anonymous access is limited to 60 requests per hour. Use a personal access token (PAT) for higher limits (5 000 requests/h):

client := github.NewClient(nil).WithAuthToken("your_pat_token_here")

The snippet comes from example/tokenauth/main.go. For GitHub Apps, JWT authentication is demonstrated in example/newfilewithappauth/main.go.

Core functionality demonstration – repository management

Creating a new repository requires building a github.Repository struct and calling Create:

repo := &github.Repository{
    Name:        github.Ptr("my-new-repo"),
    Private:     github.Ptr(true),
    Description: github.Ptr("Repository created by go-github demo"),
}
createdRepo, _, err := client.Repositories.Create(context.Background(), "", repo)

All non‑zero fields must be wrapped with github.Ptr to distinguish between omitted and zero values. See example/newrepo/main.go for the full example.

Handling pagination

The GitHub API returns 30 items by default. The following example fetches all repositories with a page size of 50:

opt := &github.RepositoryListOptions{ListOptions: github.ListOptions{PerPage: 50}}
var allRepos []*github.Repository
for {
    repos, resp, err := client.Repositories.List(context.Background(), "", opt)
    if err != nil {
        break // error handling omitted for brevity
    }
    allRepos = append(allRepos, repos...)
    if resp.NextPage == 0 {
        break // no more pages
    }
    opt.Page = resp.NextPage
}

Rate‑limit handling

API calls may trigger a rate‑limit error. The code below detects *github.RateLimitError, waits until the reset time plus a safety buffer, then retries:

repos, _, err := client.Repositories.List(ctx, "", nil)
var rateErr *github.RateLimitError
if errors.As(err, &rateErr) {
    resetTime := rateErr.Rate.Reset.Time
    waitDuration := resetTime.Sub(time.Now()) + 10*time.Second
    time.Sleep(waitDuration)
    // retry request
}

A more advanced solution uses the gofri/go-github-ratelimit middleware for automatic handling.

Common issue solutions

Handling 202 Accepted responses – some endpoints (e.g., statistics) return 202 while processing in the background:

stats, _, err := client.Repositories.ListContributorsStats(ctx, "owner", "repo")
if errors.As(err, &github.AcceptedError{}) {
    // implement retry logic
}

Conditional request optimization – use ETag to avoid unnecessary data transfer:

req, err := http.NewRequest("GET", "https://api.github.com/repos/google/go-github", nil)
req.Header.Set("If-None-Match", previousETag)

Full implementation details are in the repository’s README.

Summary and next steps

After following this guide you should be able to:

Configure the Go environment and install go-github.

Initialize both anonymous and authenticated clients.

Perform repository CRUD operations.

Handle pagination and rate‑limit scenarios correctly.

Apply conditional requests and manage 202‑Accepted responses.

Further resources include the example/ directory for complete samples, the source‑code comments in github/ for API details, and the test/integration/ folder for integration tests.