Skip to content

GoGitHub

GoGitHub is a high-level Go module for interacting with the GitHub API. It wraps google/go-github with convenience functions organized by operation type.

The clientv1 package provides a stable, version-isolated wrapper around go-github. Use it to avoid breaking changes when go-github updates its major version (v88 → v89 → v90...).

package main

import (
    "context"
    "fmt"

    "github.com/grokify/gogithub"
    "github.com/grokify/gogithub/clientv1"
)

func main() {
    ctx := context.Background()
    client, err := clientv1.NewClient(ctx, "your-github-token")
    if err != nil {
        panic(err)
    }

    // All methods return stable gogithub.* types
    user, _ := client.GetAuthenticatedUser(ctx)  // *gogithub.User
    repos, _ := client.ListUserRepos(ctx, user.Login)  // []*gogithub.Repository

    fmt.Printf("Found %d repos for %s\n", len(repos), user.Login)
}

Benefits:

  • Types like gogithub.User and gogithub.Repository won't change
  • When go-github updates, only gogithub needs updating—your code stays the same
  • Single import pattern: gogithub for types, clientv1 for the client

Features

  • Version-Isolated Client - Stable types that don't break when go-github updates
  • Search API - Query issues, pull requests, code, and commits with a fluent query builder
  • Repository Operations - Fork, branch, commit, and batch file operations
  • Repository Health - Open issues, open pull requests, and workflow status across a set of repositories in four requests each
  • Repository Access - List grants in organizations you don't belong to; detect organizations that forbid your token type
  • Conditional Requests - ETag transport so unchanged responses cost no rate limit
  • Pull Requests - Create, list, merge, and manage PRs
  • Releases - List releases and download assets
  • GraphQL API - User contribution statistics and detailed commit stats
  • Error Handling - Typed errors with helper functions for common cases
  • Authentication - Tokens, GitHub Apps, and OAuth apps from a goauth credentials set file
  • GitHub Enterprise - Full support for GitHub Enterprise Server
  • Command Line - gogithub CLI for profiles, search, repository access, and health

Search Example

search and the other operation packages (repo, pr, release, checks, tag, sarif) take a clientv1.Client, so they're insulated from go-github version changes too:

package main

import (
    "context"
    "fmt"

    "github.com/grokify/gogithub/clientv1"
    "github.com/grokify/gogithub/search"
)

func main() {
    ctx := context.Background()
    client, err := clientv1.NewClient(ctx, "your-github-token")
    if err != nil {
        panic(err)
    }

    c := search.NewClient(client)
    issues, err := c.SearchIssuesAll(ctx, search.Query{
        search.ParamUser:  "grokify",
        search.ParamState: search.ParamStateValueOpen,
        search.ParamIs:    search.ParamIsValuePR,
    }, nil)
    if err != nil {
        panic(err)
    }

    fmt.Printf("Found %d open PRs\n", len(issues))
}

Package Overview

Package Description Stability
clientv1 Version-isolated client Stable
gogithub (root) Stable types (User, Repository, etc.) Stable
search Search API with query builder Stable (clientv1.Client)
repo Repository operations (fork, branch, commit, batch, access) Stable (clientv1.Client)
health Open issues, pull requests, and workflow status for repository sets Stable (clientv1.Client)
etagcache HTTP transport for conditional requests (ETag / 304) Stable
pr Pull request operations Stable (clientv1.Client)
release Release and asset operations Stable (clientv1.Client)
checks Check run polling and status Stable (clientv1.Client)
tag Git tag operations Stable (clientv1.Client)
sarif SARIF upload for code scanning Stable (clientv1.Client)
auth Client creation and authentication utilities Legacy functions return go-github types
auth/credentialsset OAuth app clients from a goauth credentials set file Stable
config Configuration from environment variables NewClientV1() is stable; NewClient() is deprecated
graphql GraphQL API for contribution statistics Exposes githubv4 types
errors Error types and translation Stable

Packages marked "Legacy" or "Exposes ..." return or accept types from an external library (go-github or githubv4) and may require consumer updates when that library changes major versions. Prefer clientv1.Client wherever a package accepts it.

Next Steps