github

README

github

GitHub App tools — code search, issue search, file content, commit history, and blame — for the gollem LLM agent framework.

github.com/gollem-dev/tools/github

Tools

Name	Description
github_code_search	Search code across GitHub repositories.
github_issue_search	Search issues and pull requests.
github_get_content	Get file content from a repository.
github_list_commits	List commits for a repository.
github_get_blame	Get git blame information for a file.

Usage

ts, err := github.New(123456, 7890123, pemString)
if err != nil {
	return err
}
if err := ts.Ping(ctx); err != nil { // optional preflight
	return err
}

Authentication is via a GitHub App installation: the tool mints installation access tokens from the App ID, installation ID, and the App's PEM private key.

Options

Option	Required	Default
WithLogger(*slog.Logger)	no	slog.Default()

Testing

Mock tests run unconditionally. The live-service test runs only when the TEST_GITHUB_* variables are set:

TEST_GITHUB_APP_ID=... TEST_GITHUB_APP_INSTALLATION_ID=... \
	TEST_GITHUB_APP_PRIVATE_KEY="$(cat key.pem)" \
	TEST_GITHUB_REPO=owner/repo go test ./...

Documentation

Overview

Package github provides a gollem.ToolSet for GitHub code/issue search, file content retrieval, commit history listing, and git blame.

Package github provides a gollem.ToolSet for GitHub code/issue search, file content retrieval, commit history listing, and git blame.

Index

• type BlameRange
• type CodeSearchResult
• type CommitResult
• type ContentResult
• type IssueSearchResult
• type Option
  • func WithLogger(logger *slog.Logger) Option
• type ToolSet
  • func New(appID int64, installationID int64, privateKey string, opts ...Option) (*ToolSet, error)
  • func (t *ToolSet) Ping(ctx context.Context) error
  • func (t *ToolSet) Run(ctx context.Context, name string, args map[string]any) (map[string]any, error)
  • func (t *ToolSet) Specs(_ context.Context) ([]gollem.ToolSpec, error)

Types

type BlameRange

type BlameRange struct {
	StartLine     int       `json:"start_line"`
	EndLine       int       `json:"end_line"`
	CommitSHA     string    `json:"commit_sha"`
	CommitMessage string    `json:"commit_message"`
	Author        string    `json:"author"`
	Date          time.Time `json:"date"`
}

BlameRange represents a contiguous set of lines attributed to a single commit.

type CodeSearchResult

type CodeSearchResult struct {
	Repository string   `json:"repository"`
	Path       string   `json:"path"`
	HTMLURL    string   `json:"html_url"`
	Matches    []string `json:"matches"`
}

CodeSearchResult represents a single code search result.

type CommitResult

type CommitResult struct {
	SHA     string    `json:"sha"`
	Message string    `json:"message"`
	Author  string    `json:"author"`
	Date    time.Time `json:"date"`
	HTMLURL string    `json:"html_url"`
}

CommitResult represents a single commit in the list-commits response.

type ContentResult

type ContentResult struct {
	Repository string `json:"repository"`
	Path       string `json:"path"`
	Content    string `json:"content"`
	SHA        string `json:"sha"`
	HTMLURL    string `json:"html_url"`
	Size       int    `json:"size"`
}

ContentResult represents file content retrieved from a repository.

type IssueSearchResult

type IssueSearchResult struct {
	Repository string    `json:"repository"`
	Number     int       `json:"number"`
	Title      string    `json:"title"`
	State      string    `json:"state"`
	HTMLURL    string    `json:"html_url"`
	User       string    `json:"user"`
	CreatedAt  time.Time `json:"created_at"`
	UpdatedAt  time.Time `json:"updated_at"`
	IsPR       bool      `json:"is_pr"`
	Body       string    `json:"body,omitempty"`
	Labels     []string  `json:"labels,omitempty"`
}

IssueSearchResult represents a single issue or pull-request search result.

type Option

type Option func(*ToolSet)

Option configures a ToolSet.

func WithLogger

func WithLogger(logger *slog.Logger) Option

WithLogger sets the logger. A nil logger keeps the default (slog.Default()).

type ToolSet

type ToolSet struct {
	// contains filtered or unexported fields
}

ToolSet implements gollem.ToolSet for GitHub. Fields are unexported; configure via Option.

func New

func New(appID int64, installationID int64, privateKey string, opts ...Option) (*ToolSet, error)

New constructs the ToolSet with the three required credentials as positional arguments. appID and installationID must be non-zero; privateKey must be a non-empty PEM string. Optional settings (e.g. WithLogger) are passed as opts. New performs only in-memory validation and transport construction; use Ping to verify connectivity.

func (*ToolSet) Ping

func (t *ToolSet) Ping(ctx context.Context) error

Ping verifies connectivity and credentials by fetching a short-lived installation token from the GitHub API.

func (*ToolSet) Run

func (t *ToolSet) Run(ctx context.Context, name string, args map[string]any) (map[string]any, error)

Run executes the named GitHub tool.

func (*ToolSet) Specs

func (t *ToolSet) Specs(_ context.Context) ([]gollem.ToolSpec, error)

Specs returns the tool specifications for the five GitHub tools.