ghkit

gh, err := ghkit.NewE(ghkit.Adapt(github.NewClient, github.WithHTTPClient),
    ghkit.WithToken(os.Getenv("GITHUB_TOKEN")),
    ghkit.WithETagCache(),
    ghkit.WithRetry(),
    ghkit.WithUserAgent("my-app/1.0"),
    ghkit.WithTimeout(30*time.Second),
)

Defaults are tuned for steady-state operators: rate-limit on, retry 3 attempts with decorrelated jitter on idempotent 5xx + transient net errors, etag at 4096 entries / 256 MiB. Tune downward via the per-layer options if your workload differs. There is no RecommendedDefaults() API on purpose: the constructor defaults are the single source of truth.

gh, err := ghkit.NewE(ghkit.Adapt(github.NewClient, github.WithHTTPClient),
    ghkit.WithToken(os.Getenv("GITHUB_TOKEN")),
    ghkit.WithETagCache(),
)

The default cache is a 4096-entry in-process LRU with a 256 MiB byte budget; safe to run in a long-lived process without watching it grow.

import (
    "github.com/shurcooL/githubv4"
    ghkit "github.com/pcanilho/go-github-kit"
)

v4, err := ghkit.New(githubv4.NewClient,
    ghkit.WithToken(os.Getenv("GITHUB_TOKEN")),
    ghkit.WithRetry(),
)

ghkit.New is generic; githubv4.NewClient satisfies func(*http.Client) *githubv4.Client and gets oauth2 + retry + ratelimit + throttle + UA from the transport stack. ETag caching is REST-only by design (the etag layer no-ops on anything but GET), so WithETagCache is a no-op for v4 traffic; leave it off unless you also issue REST GETs through the same client.

A runnable version lives at examples/graphql-v4/.

GitHub REST endpoints paginate via RFC 8288 Link headers. The pages sub-package walks them with a Go 1.23 range-over-func iterator, reusing the configured *http.Client so RateLimit, Throttle, Retry, oauth2, and ETag all apply per page automatically.

import (
    "context"
    "fmt"
    "net/http"
    "os"

    "github.com/google/go-github/v90/github"
    ghkit "github.com/pcanilho/go-github-kit"
    "github.com/pcanilho/go-github-kit/pages"
)

hc, err := ghkit.HTTPClient(
    ghkit.WithToken(os.Getenv("GITHUB_TOKEN")),
    ghkit.WithETagCache(),
)
if err != nil { panic(err) }

headers := http.Header{
    "Accept":               []string{"application/vnd.github+json"},
    "X-GitHub-Api-Version": []string{"2022-11-28"},
}

var n int
for repo, err := range pages.As[*github.Repository](
    context.Background(), hc, "GET",
    "https://api.github.com/user/repos?per_page=100", headers,
) {
    if err != nil { panic(err) }
    fmt.Println(repo.GetFullName())
    n++
}
fmt.Printf("total: %d\n", n)

pages.As[T] decodes each page into []T and yields one element at a time; the iterator owns the response body. pages.Pages is the lower-level form that yields *http.Response per page when the caller wants to handle decoding directly.

For tests, ghtest.LinkHeader(baseURL, page, perPage, lastPage) builds RFC 8288 Link header values. See examples/list-all-repos/ for a runnable end-to-end demo.

The polling sub-package iterates an HTTP endpoint on a caller-tunable interval, reusing the configured *http.Client so retry, etag, ratelimit, throttle, and oauth2 apply per attempt. polling.As[T] decodes each response into T; WithDoneT stops on the decoded value; WithMaxWallClock caps total time and wraps context.DeadlineExceeded.

import (
    "context"
    "errors"
    "log"
    "net/http"
    "os"
    "time"

    "github.com/google/go-github/v90/github"
    ghkit "github.com/pcanilho/go-github-kit"
    "github.com/pcanilho/go-github-kit/polling"
    "github.com/pcanilho/go-github-kit/retry"
)

hc, err := ghkit.HTTPClient(
    ghkit.WithToken(os.Getenv("GITHUB_TOKEN")),
    ghkit.WithRetry(retry.WithMaxAttempts(1)), // polling owns the loop
    ghkit.WithETagCache(),
)
if err != nil { panic(err) }

ctx, cancel := context.WithTimeout(context.Background(), 35*time.Minute)
defer cancel()

url := "https://api.github.com/repos/owner/repo/actions/runs/12345"
seq := polling.As[*github.WorkflowRun](
    ctx, hc, http.MethodGet, url,
    http.Header{"Accept": []string{"application/vnd.github+json"}},
    nil, 15*time.Second,
    polling.WithDoneT(func(r *github.WorkflowRun) bool { return r.GetStatus() == "completed" }),
    polling.WithMaxWallClock(30*time.Minute),
    polling.WithFullJitter(0.2),
)

var run *github.WorkflowRun
for r, err := range seq {
    if err != nil {
        if errors.Is(err, polling.ErrMaxWallClockExceeded) { log.Fatal("budget exceeded") }
        log.Fatal(err)
    }
    run = r
}
log.Printf("conclusion=%s", run.GetConclusion())

WithFullJitter samples uniformly around the interval so concurrent pollers de-correlate; WithJitter applies a fixed offset instead and leaves pollers started together in step. The last of the two applied wins.

Sharp edges: each c.Do may itself loop through retry.Transport (pass retry.WithMaxAttempts(1) when polling owns the outer loop); throttle.WithRequestsPerSecond below 1/interval dominates cadence; with WithETagCache an unchanged resource yields identical decoded bytes per tick (pair with polling.WithChangeOnly to skip those silently). Pages-shape body ownership: Poll yields *http.Response and the caller closes; As[T] owns and closes via defer.

See examples/poll-workflow-run/ for a runnable demo.

GitHub's /search/* endpoints return an envelope ({total_count, incomplete_results, items[]}), so pages.As[T] cannot serve them directly. The search sub-package wraps the four common endpoints (Issues, Code, Repos, Users) and surfaces both IncompleteResults (timed-out queries) and the post-page-10 1000-result hard cap as ErrResultCapHit.

import (
    "context"
    "errors"
    "fmt"

    "github.com/google/go-github/v90/github"
    "github.com/pcanilho/go-github-kit/search"
)

for r, err := range search.Issues[*github.Issue](
    context.Background(), hc, "is:open is:pr author:torvalds",
    search.WithPerPage(100),
    search.WithSort("updated"),
    search.WithOrder("desc"),
) {
    if err != nil {
        if errors.Is(err, search.ErrResultCapHit) {
            // Refine the query with a `created:<...` date filter.
            break
        }
        panic(err)
    }
    if r.IncompleteResults {
        // GitHub timed out server-side on this page; results may be partial.
    }
    fmt.Printf("[%d] %s\n", r.TotalCount, r.Item.GetHTMLURL())
}

Implementation reuses pages.Pages for Link-header walking, so per-page retry/etag/ratelimit/throttle composition is automatic. Search has its own X-RateLimit-Resource budget; gofri routes requests transparently. See examples/search-issues/.

The etag layer transparently converts 304 responses into synthesised 200s with the cached body. The cond sub-package surfaces the change-vs-unchanged signal that is otherwise erased, letting consumers skip JSON parse, structural diff, DB writes, and webhook fan-out when nothing changed.

import (
    "context"
    "encoding/json"
    "io"
    "net/http"

    "github.com/google/go-github/v90/github"
    "github.com/pcanilho/go-github-kit/cond"
)

req, _ := http.NewRequest(http.MethodGet, "https://api.github.com/repos/google/go-github", nil)
req.Header.Set("Accept", "application/vnd.github+json")

repo, status, err := cond.Fetch(context.Background(), hc, req,
    func(r io.Reader) (*github.Repository, error) {
        var v github.Repository
        return &v, json.NewDecoder(r).Decode(&v)
    },
)
if err != nil { panic(err) }
switch status {
case cond.Updated:    // wire 200 (or no etag layer in chain)
case cond.Unchanged:  // synth 200 from cache hit; resource hasn't changed
}

Mechanics: the etag layer sets cond.HeaderCacheStatus ("X-Ghkit-Cache") on synth-200 ("hit") and wire-200-store ("miss") paths. cond.StatusOf(resp) reads the header. Absent header → Updated (no etag layer in chain → caller behaves as if every response is fresh). Pair with polling.WithChangeOnly to silently skip yields when polling an unchanged resource. See examples/conditional-fetch/.

import (
    ghkit "github.com/pcanilho/go-github-kit"
    "github.com/pcanilho/go-github-kit/etag"
)

// In production, build this with ghinstallation (plain local-key JWT
// signing) or ghait (KMS-backed signing via AWS/GCP/Azure/Vault, selected
// via build tags so you only pull in the SDK you actually use). Both vend
// a fresh installation token on each Token() call; the transport picks up
// the new value per request.
var source oauth2.TokenSource // = ghinstallation.New(...) or wrap ghait.NewToken

// One cache shared across all installations in this process.
cache := etag.NewLRUCache(8192)

hc, err := ghkit.HTTPClient(
    ghkit.WithTokenSource(source),
    ghkit.WithETagCache(
        etag.WithCache(cache),
        etag.WithKeyScope(fmt.Sprintf("installation-%d", installationID)),
    ),
    ghkit.WithTimeout(5 * time.Second),
)
if err != nil { return err }
gh, err := github.NewClient(github.WithHTTPClient(hc))

WithKeyScope is required whenever you supply a Cache yourself. It namespaces entries so two installations hitting the same URL never read each other's bodies.

Signer options for the oauth2.TokenSource:

• bradleyfalzon/ghinstallation for local-key JWT signing (the common default).
• isometry/ghait for KMS-backed signing (AWS, GCP, Azure, Vault, or a local file). Each KMS provider is behind a build tag so you only pull the SDK you use.

type ghaitSource struct {
    ctx     context.Context
    factory ghait.TokenFactory
}

func (s *ghaitSource) Token() (*oauth2.Token, error) {
    t, err := s.factory.NewToken(s.ctx)
    if err != nil {
        return nil, err
    }
    return &oauth2.Token{AccessToken: t.GetToken(), Expiry: t.GetExpiresAt().Time}, nil
}

// Build with -tags=aws|gcp|azure|vault|file to pull only the SDK you use.
factory, _ := ghait.NewGHAIT(ctx, ghait.NewConfig(appID, installationID, "aws", keyRef))
source := oauth2.ReuseTokenSource(nil, &ghaitSource{ctx: ctx, factory: factory})

import (
    "github.com/pcanilho/go-github-kit/etag"
)

type tenantKey struct{}

cache := etag.NewLRUCache(8192)

hc, err := ghkit.HTTPClient(
    ghkit.WithTokenSource(perTenantTokenSource), // resolves token per req.Context()
    ghkit.WithETagCache(
        etag.WithCache(cache),
        etag.WithAutoKeyScope(func(req *http.Request) (string, error) {
            id, ok := req.Context().Value(tenantKey{}).(string)
            if !ok || id == "" {
                return "", fmt.Errorf("tenant id missing from request context")
            }
            return id, nil
        }),
    ),
)

Use WithAutoKeyScope instead of WithKeyScope when one *http.Client serves N tenants (typical for warm Lambda pools fronting many GitHub App installations). The fn is invoked per request and must return either a non-empty scope or a non-nil error; an empty string with a nil error surfaces as etag.ErrEmptyScope. WithKeyScope and WithAutoKeyScope are mutually exclusive.

gh, err := ghkit.NewE(ghkit.Adapt(github.NewClient, github.WithHTTPClient),
    ghkit.WithToken(os.Getenv("GITHUB_TOKEN")),
    ghkit.WithETagCache(etag.WithCache(etag.NewLRUCache(8192))),
    ghkit.WithRequestsPerSecond(1.3, 1),
)

WithRequestsPerSecond is a standard x/time/rate token bucket. It adds a client-side cap on top of the reactive limiter, which is useful for batch jobs that want predictable pacing under sustained load.

gh, err := ghkit.NewE(func(hc *http.Client) (*github.Client, error) {
    return github.NewClient(
        github.WithHTTPClient(hc),
        github.WithEnterpriseURLs(
            "https://github.example.com/api/v3/",
            "https://github.example.com/api/uploads/",
        ),
        github.WithUserAgent("my-app/1.0"),
    )
}, ghkit.WithToken(os.Getenv("GITHUB_ENTERPRISE_TOKEN")))

This one keeps the closure rather than ghkit.Adapt, because Adapt passes only the HTTP client and this client needs go-github options of its own.

NewE propagates the constructor's error, so a bad enterprise URL fails here rather than silently yielding a github.com client. Sending an Enterprise token to public github.com is a credential-leak path, so do not fall back.

go-github normalises the trailing slash on both URLs for you; it rejects an empty string. UserAgent can also be set at the transport level via ghkit.WithUserAgent("my-app/1.0"), which applies to every outbound request regardless of which SDK you wrap around HTTPClient().

gh, err := ghkit.NewE(ghkit.Adapt(github.NewClient, github.WithHTTPClient),
    ghkit.WithToken(os.Getenv("GITHUB_TOKEN")),
    ghkit.WithRetry(), // 3 attempts, 200ms..2s decorrelated jitter, idempotent methods only
)

Tuned policy with POST opt-in via Idempotency-Key:

import "github.com/pcanilho/go-github-kit/retry"

gh, err := ghkit.NewE(ghkit.Adapt(github.NewClient, github.WithHTTPClient),
    ghkit.WithToken(token),
    ghkit.WithRetry(
        retry.WithMaxAttempts(5),
        retry.WithBackoff(500*time.Millisecond, 10*time.Second),
        retry.WithRetryOn(func(req *http.Request, resp *http.Response, err error) bool {
            // Retry POST/PATCH when the caller asserted idempotency.
            if req.Header.Get("Idempotency-Key") != "" {
                if err != nil { return retry.IsTransientNetErr(err) }
                return resp != nil && retry.IsRetryable5xx(resp.StatusCode)
            }
            // Otherwise the default behaviour.
            if !retry.IsIdempotent(req.Method) { return false }
            if err != nil { return retry.IsTransientNetErr(err) }
            return resp != nil && retry.IsRetryable5xx(resp.StatusCode)
        }),
    ),
)

POST/PATCH retries with a body require req.GetBody; http.NewRequest only sets it for *bytes.Buffer, *bytes.Reader, and *strings.Reader. For other readers, set it manually so the retry layer can rewind on attempt 2+.

429 is hard-excluded regardless of the predicate so ratelimit (the layer above) owns it. Retry-After is honored when present; if it exceeds maxDelay the call returns (nil, retry.ErrRetryAfterExceedsMax) and the transport has already drained and closed the prior response.

ghkit imports no metrics library; counters attach to etag.WithEventCallback and the named ratelimit callbacks.

import (
    "context"
    "fmt"
    "net/http"
    "time"

    "github.com/prometheus/client_golang/prometheus"
    ghkit "github.com/pcanilho/go-github-kit"
    "github.com/pcanilho/go-github-kit/etag"
    "github.com/pcanilho/go-github-kit/ratelimit"
)

var (
    cacheEvents = prometheus.NewCounterVec(prometheus.CounterOpts{Name: "ghkit_etag_events_total"},     []string{"kind"})
    reqs        = prometheus.NewCounterVec(prometheus.CounterOpts{Name: "ghkit_requests_total"},        []string{"status_class", "from_cache"})
    mismatches  = prometheus.NewCounterVec(prometheus.CounterOpts{Name: "ghkit_etag_mismatches_total"}, []string{"path_template"})
    rl          = prometheus.NewCounterVec(prometheus.CounterOpts{Name: "ghkit_ratelimit_total"},       []string{"kind", "category"})
)

func client(scope, token string) (*http.Client, error) {
    return ghkit.HTTPClient(
        ghkit.WithToken(token),
        ghkit.WithETagCache(
            etag.WithKeyScope(scope),
            etag.WithEventCallback(func(_ context.Context, ev etag.Event) {
                cacheEvents.WithLabelValues(string(ev.Kind)).Inc()
                if ev.Status > 0 {
                    fromCache := ev.Kind == etag.KindHit || ev.Kind == etag.KindValidatedOK
                    reqs.WithLabelValues(fmt.Sprintf("%dxx", ev.Status/100), fmt.Sprint(fromCache)).Inc()
                }
                if ev.Kind == etag.KindMismatch {
                    mismatches.WithLabelValues(ev.PathTemplate).Inc()
                }
            }),
        ),
        ghkit.WithRateLimit(
            ratelimit.WithTotalSleepLimit(time.Hour),
            ratelimit.WithPrimaryLimitDetected(func(ev *ratelimit.PrimaryEvent) {
                rl.WithLabelValues("primary", string(ev.Category)).Inc()
            }),
            ratelimit.WithSecondaryLimitDetected(func(*ratelimit.SecondaryEvent) {
                rl.WithLabelValues("secondary", "").Inc()
            }),
        ),
        ghkit.WithRetry(),
    )
}

Metric names are illustrative; substitute your registry conventions.

Build this through ghkit.HTTPClient rather than stacking etag.NewTransport and ratelimit.NewTransport by hand: the hand-built version silently omits retry, throttle and oauth2, and has to repeat the layer ordering correctly. WithETagCache and WithRateLimit forward their sub-options verbatim, so nothing is lost.

For pull-based gauges, ghkit.WithETagTransport hands you the *etag.Transport so you can poll Stats():

var etagRT *etag.Transport
hc, err := ghkit.HTTPClient(
    ghkit.WithToken(token),
    ghkit.WithETagTransport(func(t *etag.Transport) { etagRT = t }),
)
// etagRT.Stats() -> {Degraded, TotalHits, TotalMisses, TotalStores, ...}

import (
    "net/http"

    "github.com/google/go-github/v90/github"
    "github.com/pcanilho/go-github-kit/etag"
)

rt, err := etag.NewTransport(nil, // nil = default base with DisableCompression=true
    etag.WithCache(etag.NewLRUCache(1024)),
    etag.WithKeyScope("tenant-42"),
)
if err != nil { return err }
hc := &http.Client{Transport: rt}
gh, err := github.NewClient(github.WithHTTPClient(hc))