github

GitHub Client Package

A generic, reusable GitHub client for interacting with the GitHub API. This package abstracts the underlying google/go-github SDK and exposes only domain types to prevent SDK leakage.

Features

• No SDK Leakage: All public APIs return domain types, never SDK types
• Context-Aware: All operations support context cancellation and timeout
• Structured Logging: Integrated with pkg/logger for consistent logging
• HTTP Client Integration: Uses pkg/httpclient for retry, backoff, and authentication
• Webhook Support: Parse and validate GitHub webhooks with signature verification
• Mock Support: Includes mock client for testing without real API calls
• Table-Driven Tests: Comprehensive test coverage with clear examples

Installation

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

Usage

Creating a Client

import (
    "github.com/grhili/cd-operator/pkg/github"
    "github.com/grhili/cd-operator/pkg/httpclient"
    "github.com/grhili/cd-operator/pkg/logger"
)

// Create HTTP client with authentication
token := "ghp_xxxxxxxxxxxx"
httpClient := httpclient.NewClient().
    WithAuthToken(httpclient.Token(token))

// Create logger
log, _ := logger.New(logger.Config{
    Level:  "info",
    Format: "json",
})

// Create GitHub client
cfg := github.ClientConfig{
    BaseURL:    "https://api.github.com",
    HTTPClient: httpClient,
    Logger:     log,
}
client := github.NewClient(cfg)

Listing Pull Requests

ctx := context.Background()
repo := github.Repository{
    Owner: "grhili",
    Name:  "cd-operator",
}

prs, err := client.ListPRs(ctx, repo)
if err != nil {
    log.Error("failed to list PRs", zap.Error(err))
    return
}

for _, pr := range prs {
    log.Info("found PR",
        zap.Int("number", pr.Number),
        zap.String("title", pr.Title),
        zap.String("state", string(pr.State)))
}

Getting a Specific Pull Request

pr, err := client.GetPR(ctx, repo, 42)
if err != nil {
    log.Error("failed to get PR", zap.Error(err))
    return
}

log.Info("PR details",
    zap.Int("number", pr.Number),
    zap.String("title", pr.Title),
    zap.String("head_sha", pr.HeadSHA),
    zap.String("base_branch", pr.BaseBranch))

Getting PR Files

files, err := client.GetPRFiles(ctx, repo, 42)
if err != nil {
    log.Error("failed to get PR files", zap.Error(err))
    return
}

for _, file := range files {
    log.Info("file changed", zap.String("path", file.Path))
}

Merging a Pull Request

err := client.MergePR(ctx, repo, 42, "Merge pull request #42")
if err != nil {
    log.Error("failed to merge PR", zap.Error(err))
    return
}

log.Info("PR merged successfully")

Managing Labels

// Add a label
err := client.AddLabel(ctx, repo, 42, "bug")
if err != nil {
    log.Error("failed to add label", zap.Error(err))
    return
}

// Remove a label
err = client.RemoveLabel(ctx, repo, 42, "wontfix")
if err != nil {
    log.Error("failed to remove label", zap.Error(err))
    return
}

Parsing Webhooks

import (
    "net/http"
)

func webhookHandler(w http.ResponseWriter, req *http.Request) {
    // Parse and validate webhook
    event, err := github.ParseWebhook(req, "webhook-secret")
    if err != nil {
        http.Error(w, "Invalid webhook", http.StatusBadRequest)
        return
    }

    // Handle different event types
    switch payload := event.Payload.(type) {
    case *github.PullRequestWebhookPayload:
        log.Info("PR event received",
            zap.String("action", payload.Action),
            zap.Int("pr_number", payload.PullRequest.Number),
            zap.String("title", payload.PullRequest.Title))

        // Process pull request event
        handlePullRequest(payload)

    default:
        log.Info("unhandled event type", zap.String("type", event.Type))
    }

    w.WriteHeader(http.StatusOK)
}

Testing

Using the Mock Client

import (
    "testing"
    "github.com/grhili/cd-operator/pkg/github"
    "github.com/grhili/cd-operator/pkg/logger"
)

func TestMyFunction(t *testing.T) {
    log := logger.NewFakeLogger()
    mock := github.NewMockClient(log)

    // Override specific methods
    mock.GetPRFunc = func(ctx context.Context, repo github.Repository, number int) (*github.PullRequest, error) {
        return &github.PullRequest{
            Number: number,
            Title:  "Test PR",
            State:  github.PullRequestStateOpen,
        }, nil
    }

    // Use mock in tests
    ctx := context.Background()
    pr, err := mock.GetPR(ctx, github.Repository{Owner: "test", Name: "repo"}, 42)
    if err != nil {
        t.Fatalf("unexpected error: %v", err)
    }

    if pr.Number != 42 {
        t.Errorf("expected PR #42, got #%d", pr.Number)
    }
}

Running Tests

# Run all tests
go test ./pkg/github/...

# Run tests with coverage
go test ./pkg/github/... -cover

# Run specific test
go test ./pkg/github/... -run TestToPR

Architecture

Package Structure

pkg/github/
├── types.go         # Domain types (PR, Repository, File, Label)
├── adapter.go       # SDK → domain conversion
├── client.go        # Client implementation
├── webhook.go       # Webhook parsing and validation
├── mock.go          # Mock client for testing
├── adapter_test.go  # Adapter tests
├── webhook_test.go  # Webhook tests
├── mock_test.go     # Mock client tests
└── example_test.go  # Usage examples

Domain Types

• PullRequest: Represents a GitHub pull request with all essential fields
• Repository: Repository identifier (owner + name)
• File: File in a repository with path and content
• Label: GitHub label with name and color
• PullRequestState: Enum for PR states (open, closed, merged)

Key Design Decisions

1. No SDK Leakage: All public methods return domain types, never *github.PullRequest or other SDK types
2. Value vs Pointer Types:
   • Repository and Label are value types (small, immutable)
   • PullRequest and File are pointer types (can be large, often mutated)
3. Context First: All methods take context.Context as first parameter
4. Structured Logging: Uses injected Logger interface for consistent logging
5. HTTP Client Abstraction: Uses pkg/httpclient for retry and authentication

Configuration

Custom Base URL (GitHub Enterprise)

cfg := github.ClientConfig{
    BaseURL:    "https://github.company.com/api/v3",
    HTTPClient: httpClient,
    Logger:     log,
}
client := github.NewClient(cfg)

Custom HTTP Client Options

httpClient := httpclient.NewClient().
    WithAuthToken(httpclient.Token(token)).
    WithRetry(httpclient.RetryConfig{
        MaxRetries: httpclient.RetryCount(5),
        WaitMin:    2 * time.Second,
        WaitMax:    30 * time.Second,
    }).
    WithTimeout(httpclient.TimeoutConfig{
        HTTPTimeout: 60 * time.Second,
    })

Error Handling

All methods return descriptive errors with context:

pr, err := client.GetPR(ctx, repo, 42)
if err != nil {
    // Error includes context about what failed
    // Example: "failed to get pull request #42: 404 Not Found"
    log.Error("operation failed", zap.Error(err))
    return err
}

Best Practices

1. Always pass context: Use context.Background() or request context
2. Configure timeouts: Set reasonable HTTP timeouts via httpclient
3. Handle rate limits: GitHub API has rate limits; implement backoff
4. Use structured logging: Pass meaningful fields to logger
5. Test with mocks: Use MockClient for unit tests
6. Validate webhooks: Always verify webhook signatures in production

License

This package is part of the cd-operator project.