Authentication¶

GoGitHub provides flexible authentication options for both GitHub.com and GitHub Enterprise.

REST API Client¶

Token Authentication¶

The simplest way to authenticate is with a personal access token:

import "github.com/grokify/gogithub/auth"

ctx := context.Background()
gh := auth.NewGitHubClient(ctx, "your-github-token")

HTTP Client¶

If you need the underlying HTTP client (e.g., for custom transports):

httpClient := auth.NewTokenClient(ctx, "your-github-token")

Get Authenticated User¶

Verify authentication and get the current user:

username, err := auth.GetAuthenticatedUser(ctx, gh)
if err != nil {
    // Handle authentication error
}
fmt.Printf("Authenticated as: %s\n", username)

Get User Information¶

Retrieve information about any user:

user, err := auth.GetUser(ctx, gh, "octocat")
if err != nil {
    // Handle error
}
fmt.Printf("Name: %s\n", user.GetName())

Configuration¶

The config package provides a structured way to manage GitHub configuration:

From Environment Variables¶

import "github.com/grokify/gogithub/config"

cfg, err := config.FromEnv()
if err != nil {
    panic(err)
}

gh, err := cfg.NewClient(ctx)
if err != nil {
    panic(err)
}

Environment Variables¶

Variable	Description	Default
`GITHUB_TOKEN`	Personal access token	(required)
`GITHUB_OWNER`	Default repository owner	-
`GITHUB_REPO`	Default repository name	-
`GITHUB_BRANCH`	Default branch	`main`
`GITHUB_BASE_URL`	API base URL	`https://api.github.com/`
`GITHUB_UPLOAD_URL`	Upload URL	`https://uploads.github.com/`

Manual Configuration¶

cfg := &config.Config{
    Token:  "your-token",
    Owner:  "grokify",
    Repo:   "gogithub",
    Branch: "main",
}

if err := cfg.Validate(); err != nil {
    panic(err)
}

gh, err := cfg.NewClient(ctx)

GitHub Enterprise¶

For GitHub Enterprise Server, specify custom URLs:

cfg := &config.Config{
    Token:     "your-token",
    BaseURL:   "https://github.mycompany.com/api/v3",
    UploadURL: "https://github.mycompany.com/api/uploads",
}

gh, err := cfg.NewClient(ctx)

Check if a configuration is for GitHub Enterprise:

if cfg.IsEnterprise() {
    fmt.Println("Using GitHub Enterprise")
}

GraphQL API Client¶

For the GraphQL API (used for contribution statistics), use a separate client:

import "github.com/grokify/gogithub/graphql"

client := graphql.NewClient(ctx, "your-github-token")

For GitHub Enterprise:

client := graphql.NewEnterpriseClient(ctx, "your-token", "https://github.mycompany.com/api/graphql")

GraphQL Requires Authentication

Unlike the REST API which allows limited unauthenticated access, the GraphQL API always requires a token. Even for public data, you need a token (with no special scopes).

Token Scopes¶

Basic Scopes¶

Scope	Required For
(none)	Read public data, GraphQL queries on public repos
`public_repo`	Write to public repositories
`repo`	Full access to private repositories
`read:user`	Read user profile data, contribution statistics
`read:org`	Read organization membership

Token Requirements by Use Case¶

Public Data Only (Recommended Starting Point)¶

For reading public user statistics, contribution data, and public repository information, you need minimal permissions:

Token Type	Configuration
Fine-grained PAT	Repository access: "Public Repositories (read-only)", no other permissions
Classic PAT	No scopes required (just a valid token)
GitHub CLI	Default `gh auth login` works

This is sufficient for:

User contribution statistics (profile, graphql packages)
Public repository data (commits, releases, contributors)
Search across public repositories

Private Repository Access¶

For accessing private repositories, you need additional permissions:

Token Type	Configuration
Fine-grained PAT	Repository access: select specific repos, Contents: Read
Classic PAT	`repo` scope

Write Operations¶

For creating commits, PRs, releases, etc.:

Token Type	Configuration
Fine-grained PAT	Repository access: select repos, Contents: Read and write
Classic PAT	`repo` (private) or `public_repo` (public only)

Creating a Token¶

Fine-Grained Token (Recommended)GitHub CLIClassic PAT

Fine-grained tokens provide the most secure, minimal-permission approach.

For public data only:

Go to GitHub Settings > Fine-grained tokens
Click "Generate new token"
Set Repository access to "Public Repositories (read-only)"
Leave all Permissions sections empty (no permissions needed)
Click "Generate token" and copy it

For private repository access:

Go to GitHub Settings > Fine-grained tokens
Click "Generate new token"
Set Repository access to "Only select repositories" and choose your repos
Under Repository permissions, set "Contents" to "Read-only"
Click "Generate token" and copy it

# Login with default scopes (sufficient for most read operations)
gh auth login

# Get current token for use in your code
gh auth token

Go to GitHub Settings > Personal access tokens (classic)
Click "Generate new token (classic)"
For public data: no scopes needed
For private repos: select repo scope
Copy the token

Start Minimal

Start with a fine-grained token with "Public Repositories (read-only)" access and no permissions. This is sufficient for most read operations on public data. Add permissions only when needed.

Bot User Detection¶

GoGitHub provides constants for known bot users:

import "github.com/grokify/gogithub/auth"

if issue.User.GetLogin() == auth.UsernameDependabot {
    fmt.Println("This is a Dependabot PR")
}

// Or check by ID
if issue.User.GetID() == auth.UserIDDependabot {
    fmt.Println("This is a Dependabot PR")
}

API Reference¶

See pkg.go.dev/github.com/grokify/gogithub/auth for complete API documentation.