github

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 1, 2026 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrCompareBaseNotFound = errors.New("github: compare base SHA not reachable (force-push or branch deleted)")

ErrCompareBaseNotFound signals that the base SHA (stored cursor) is no longer reachable in the repo — most commonly because of a force-push that rewrote history on the default branch. Callers should fall back to a full tree snapshot for this tick.

Functions

func FormatContainerID 

func FormatContainerID(owner, repo string) string

FormatContainerID formats owner and repo into a container ID.

func ParseContainerID 

func ParseContainerID(containerID string) (owner, repo string, err error)

ParseContainerID parses a container ID into owner and repo. Format: "owner/repo"

Types

type BlobContent added in v0.2.1 

type BlobContent struct {
	SHA      string `json:"sha"`
	Content  string `json:"content"`
	Encoding string `json:"encoding"`
	Size     int64  `json:"size"`
	URL      string `json:"url"`
}

BlobContent represents a git blob from GitHub.

type Builder 

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

Builder creates GitHub connectors.

func NewBuilder 

func NewBuilder() *Builder

NewBuilder creates a new GitHub connector builder.

func NewBuilderWithConfig 

func NewBuilderWithConfig(config *Config) *Builder

NewBuilderWithConfig creates a builder with custom configuration.

func (*Builder) Build 

func (b *Builder) Build(ctx context.Context, tokenProvider driven.TokenProvider, containerID string) (driven.Connector, error)

Build creates a GitHub connector scoped to a specific repository. containerID format: "owner/repo"

func (*Builder) OAuthConfig 

func (b *Builder) OAuthConfig() *driven.OAuthConfig

OAuthConfig returns OAuth configuration for GitHub.

func (*Builder) SupportsContainerSelection 

func (b *Builder) SupportsContainerSelection() bool

SupportsContainerSelection returns true - GitHub supports repository selection.

func (*Builder) SupportsOAuth 

func (b *Builder) SupportsOAuth() bool

SupportsOAuth returns true - GitHub supports OAuth2.

func (*Builder) Type 

func (b *Builder) Type() domain.ProviderType

Type returns the provider type.

type Client 

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

Client provides GitHub API operations.

func NewClient 

func NewClient(tokenProvider driven.TokenProvider, baseURL string) *Client

NewClient creates a new GitHub API client.

func (*Client) CompareCommits added in v0.3.0 

func (c *Client) CompareCommits(ctx context.Context, owner, repo, base, head string) (*CompareResponse, error)

CompareCommits returns the aggregated file-level diff between two commit refs, used to drive incremental file sync. Callers get per-file add / modify / remove / rename status across the full commit range in a single API call. On 404 (base not reachable, typically from a force-push) returns ErrCompareBaseNotFound so callers can fall back to a tree snapshot.

func (*Client) Do added in v0.3.0 

func (c *Client) Do(ctx context.Context, method, path string, body, result any) error

Do implements driven.RESTClient. Wraps doRequest with JSON encode/decode so callers that hold this Client through the RESTClient port can invoke GitHub endpoints not covered by the typed methods above while reusing the same auth, rate-limit, and retry behaviour.

func (*Client) GetBlob added in v0.2.1 

func (c *Client) GetBlob(ctx context.Context, owner, repo, sha string) (*BlobContent, error)

GetBlob gets a git blob by SHA (raw file content).

func (*Client) GetCommitSHA added in v0.3.0 

func (c *Client) GetCommitSHA(ctx context.Context, owner, repo, ref string) (string, error)

GetCommitSHA resolves a ref (branch name, tag, or SHA) to the SHA of the commit it points at right now. Used to capture the current head of the default branch for storing in the connector's cursor.

func (*Client) GetFileContent 

func (c *Client) GetFileContent(ctx context.Context, owner, repo, path string) (*FileContent, error)

GetFileContent gets the content of a file.

func (*Client) GetIssue added in v0.2.1 

func (c *Client) GetIssue(ctx context.Context, owner, repo string, number int) (*Issue, error)

GetIssue gets a single issue by number.

func (*Client) GetPullRequest added in v0.2.1 

func (c *Client) GetPullRequest(ctx context.Context, owner, repo string, number int) (*PullRequest, error)

GetPullRequest gets a single pull request by number.

func (*Client) GetRepository 

func (c *Client) GetRepository(ctx context.Context, owner, repo string) (*Repository, error)

GetRepository gets repository information.

func (*Client) GetTree 

func (c *Client) GetTree(ctx context.Context, owner, repo, sha string) ([]*TreeEntry, error)

GetTree gets the repository tree (file listing).

func (*Client) GetUser 

func (c *Client) GetUser(ctx context.Context) (*User, error)

GetUser gets the authenticated user's information.

func (*Client) ListAccessibleRepos 

func (c *Client) ListAccessibleRepos(ctx context.Context, cursor string) (*ListReposResponse, error)

ListAccessibleRepos lists all repositories accessible to the authenticated user.

func (*Client) ListIssueComments added in v0.3.0 

func (c *Client) ListIssueComments(ctx context.Context, owner, repo string, number int) ([]*IssueComment, error)

ListIssueComments fetches all conversation comments for an issue or PR. Walks pagination until exhausted — comments per issue are typically small (<100), so this usually completes in one call. Any page error aborts the walk so callers never see a partial slice.

func (*Client) ListIssues 

func (c *Client) ListIssues(ctx context.Context, owner, repo string, since *time.Time, cursor string) ([]*Issue, string, error)

ListIssues lists issues for a repository.

func (*Client) ListPRReviewComments added in v0.3.0 

func (c *Client) ListPRReviewComments(ctx context.Context, owner, repo string, number int) ([]*PRReviewComment, error)

ListPRReviewComments fetches all review comments (line-level on the diff) for a pull request.

func (*Client) ListPRReviews added in v0.3.0 

func (c *Client) ListPRReviews(ctx context.Context, owner, repo string, number int) ([]*PRReview, error)

ListPRReviews fetches all reviews (approve/request-changes envelopes) for a pull request.

func (*Client) ListPullRequests 

func (c *Client) ListPullRequests(ctx context.Context, owner, repo string, cursor string) ([]*PullRequest, string, error)

ListPullRequests lists pull requests for a repository.

func (*Client) ValidateRepoAccess 

func (c *Client) ValidateRepoAccess(ctx context.Context, owner, repo string) error

ValidateRepoAccess checks if the authenticated user has access to a repository.

type Commit 

type Commit struct {
	SHA     string        `json:"sha"`
	Message string        `json:"message"`
	Author  *CommitAuthor `json:"author"`
	Date    time.Time     `json:"date"`
}

Commit represents a GitHub commit.

type CommitAuthor 

type CommitAuthor struct {
	Name  string    `json:"name"`
	Email string    `json:"email"`
	Date  time.Time `json:"date"`
}

CommitAuthor represents commit author info.

type CompareFile added in v0.3.0 

type CompareFile struct {
	SHA              string `json:"sha"`
	Filename         string `json:"filename"`
	Status           string `json:"status"`
	PreviousFilename string `json:"previous_filename"`
	Size             int64  `json:"size,omitempty"`
}

CompareFile is one entry in a Compare response's files array. status is "added", "removed", "modified", "renamed", "copied", "changed", or "unchanged". PreviousFilename is populated only when status is "renamed".

type CompareResponse added in v0.3.0 

type CompareResponse struct {
	Status string         `json:"status"`
	Files  []*CompareFile `json:"files"`
}

CompareResponse is the subset of GET /repos/:owner/:repo/compare we use. Status is "ahead", "behind", "identical", or "diverged". Files lists the aggregated file-level changes across the commit range — this is the key field for detecting adds/modifies/deletes/renames in phase 2.

type Config 

type Config struct {
	// APIBaseURL is the base URL for GitHub API.
	// Defaults to https://api.github.com for github.com.
	// For GitHub Enterprise, use https://<hostname>/api/v3
	APIBaseURL string

	// PerPage is the number of items to fetch per page.
	// Maximum is 100.
	PerPage int

	// MaxRetries is the maximum number of retry attempts for rate-limited requests.
	MaxRetries int

	// IncludeFiles enables indexing of repository files.
	IncludeFiles bool

	// IncludeIssues enables indexing of issues.
	IncludeIssues bool

	// IncludePRs enables indexing of pull requests.
	IncludePRs bool

	// IncludeDiscussions enables indexing of discussions.
	IncludeDiscussions bool

	// IncludeWiki enables indexing of wiki pages.
	IncludeWiki bool

	// FileExtensions is a list of file extensions to index.
	// Empty means all text-based files.
	FileExtensions []string

	// ExcludePaths is a list of path patterns to exclude.
	ExcludePaths []string

	// MaxFileSize is the maximum file size in bytes to fetch.
	// Default is 1MB.
	MaxFileSize int64

	// Concurrency is the number of concurrent file content fetches.
	// Default is 10.
	Concurrency int
}

Config contains configuration for the GitHub connector.

func DefaultConfig 

func DefaultConfig() *Config

DefaultConfig returns the default GitHub connector configuration.

type Connector 

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

Connector fetches documents from a single GitHub repository.

func NewConnector 

func NewConnector(tokenProvider driven.TokenProvider, owner, repo string, config *Config) *Connector

NewConnector creates a GitHub connector scoped to a specific repository.

func (*Connector) FetchChanges 

func (c *Connector) FetchChanges(ctx context.Context, source *domain.Source, cursor string) ([]*domain.Change, string, error)

FetchChanges fetches document changes from the repository. For initial sync (empty cursor), it fetches all content. For incremental sync, it fetches issue/PR changes since the cursor timestamp and file changes via the Compare API anchored on the stored head SHA.

func (*Connector) FetchDocument 

func (c *Connector) FetchDocument(ctx context.Context, source *domain.Source, externalID string) (*domain.Document, string, error)

FetchDocument fetches a single document by external ID.

func (*Connector) Inventory added in v0.3.0 

func (c *Connector) Inventory(ctx context.Context, source *domain.Source, scope string) ([]string, error)

Inventory enumerates every canonical ID currently present upstream within the given scope. Pagination is "complete-or-error": any page failure aborts the whole walk so the orchestrator never sees a partial inventory and falsely deletes documents.

func (*Connector) RESTClient added in v0.3.0 

func (c *Connector) RESTClient() driven.RESTClient

RESTClient implements driven.Connector. Returns the embedded GitHub Client, which satisfies driven.RESTClient natively.

func (*Connector) ReconciliationScopes added in v0.3.0 

func (c *Connector) ReconciliationScopes() []string

ReconciliationScopes declares which canonical-ID prefixes this connector snapshot-enumerates for delete detection.

Issues and PRs go through phase-1 reconciliation because GitHub's REST API has no deletion signal — a deleted issue or transferred PR simply stops appearing in subsequent list responses. Files do NOT need reconciliation: the Compare API used in fetchFileChanges already emits per-file removed/renamed statuses natively, so deletes are caught in-band during phase 2.

func (*Connector) TestConnection 

func (c *Connector) TestConnection(ctx context.Context, source *domain.Source) error

TestConnection tests the connection to the repository.

func (*Connector) Type 

func (c *Connector) Type() domain.ProviderType

Type returns the provider type.

func (*Connector) ValidateConfig 

func (c *Connector) ValidateConfig(config domain.SourceConfig) error

ValidateConfig validates source configuration.

type ContainerLister 

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

ContainerLister lists GitHub repositories accessible with an installation's credentials.

func NewContainerLister 

func NewContainerLister(tokenProvider driven.TokenProvider, baseURL string) *ContainerLister

NewContainerLister creates a ContainerLister with the given token provider.

func (*ContainerLister) ListContainers 

func (l *ContainerLister) ListContainers(ctx context.Context, cursor string, _ string) ([]*driven.Container, string, error)

ListContainers lists all repositories accessible to the authenticated user. Returns repositories as containers in the format "owner/repo".

type ContainerListerFactory 

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

ContainerListerFactory creates ContainerListers for GitHub installations.

func NewContainerListerFactory 

func NewContainerListerFactory(
	installationStore driven.ConnectionStore,
	tokenFactory driven.TokenProviderFactory,
	baseURL string,
) *ContainerListerFactory

NewContainerListerFactory creates a factory for GitHub container listers.

func (*ContainerListerFactory) Create 

func (f *ContainerListerFactory) Create(ctx context.Context, installationID string) (driven.ContainerLister, error)

Create creates a ContainerLister for a GitHub installation.

type FileContent 

type FileContent struct {
	Name     string `json:"name"`
	Path     string `json:"path"`
	SHA      string `json:"sha"`
	Size     int64  `json:"size"`
	Content  string `json:"content"`
	Encoding string `json:"encoding"`
	HTMLURL  string `json:"html_url"`
}

FileContent represents file content from GitHub.

type Issue 

type Issue struct {
	ID          int64            `json:"id"`
	Number      int              `json:"number"`
	Title       string           `json:"title"`
	Body        string           `json:"body"`
	State       string           `json:"state"`
	HTMLURL     string           `json:"html_url"`
	User        *User            `json:"user"`
	Labels      []Label          `json:"labels"`
	CreatedAt   time.Time        `json:"created_at"`
	UpdatedAt   time.Time        `json:"updated_at"`
	ClosedAt    *time.Time       `json:"closed_at"`
	Comments    int              `json:"comments"`
	PullRequest *json.RawMessage `json:"pull_request,omitempty"`
}

Issue represents a GitHub issue.

The GitHub REST "list issues" endpoint returns pull requests mixed into the same collection as issues; PRs are distinguished only by the presence of a pull_request object on the payload. PullRequest is captured purely so callers can filter PRs out via the IsPR accessor — we do not need its contents.

func (*Issue) IsPR 

func (i *Issue) IsPR() bool

IsPR reports whether this "issue" is actually a pull request. GitHub's /issues endpoint returns both; without this check PRs get indexed twice (once here, once via ListPullRequests).

type IssueComment added in v0.3.0 

type IssueComment struct {
	ID        int64     `json:"id"`
	Body      string    `json:"body"`
	User      *User     `json:"user"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

IssueComment is a single conversation comment on an issue or PR. The /issues/{n}/comments endpoint serves both — PRs share the conversation timeline with issues. Distinct from PR review comments (line-level on the diff) and reviews (approve/request-changes envelopes).

type Label 

type Label struct {
	Name  string `json:"name"`
	Color string `json:"color"`
}

Label represents a GitHub label.

type ListReposResponse 

type ListReposResponse struct {
	Repos      []*Repository
	NextCursor string
}

ListReposResponse is the response from listing repositories.

type OAuthConfig 

type OAuthConfig struct {
	ClientID     string
	ClientSecret string
}

OAuthConfig contains OAuth configuration for GitHub.

type OAuthHandler 

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

OAuthHandler handles OAuth operations for GitHub.

func NewOAuthHandler 

func NewOAuthHandler() *OAuthHandler

NewOAuthHandler creates a new GitHub OAuth handler.

func (*OAuthHandler) BuildAuthURL 

func (h *OAuthHandler) BuildAuthURL(clientID, redirectURI, state, codeChallenge string, scopes []string) string

BuildAuthURL constructs the GitHub OAuth authorization URL.

func (*OAuthHandler) DefaultConfig 

func (h *OAuthHandler) DefaultConfig() connectors.OAuthDefaults

DefaultConfig returns GitHub's default OAuth configuration.

func (*OAuthHandler) ExchangeCode 

func (h *OAuthHandler) ExchangeCode(ctx context.Context, clientID, clientSecret, code, redirectURI, codeVerifier string) (*driven.OAuthToken, error)

ExchangeCode exchanges an authorization code for tokens.

func (*OAuthHandler) GetUserInfo 

func (h *OAuthHandler) GetUserInfo(ctx context.Context, accessToken string) (*driven.OAuthUserInfo, error)

GetUserInfo fetches the authenticated user's information.

func (*OAuthHandler) RefreshToken 

func (h *OAuthHandler) RefreshToken(ctx context.Context, clientID, clientSecret, refreshToken string) (*driven.OAuthToken, error)

RefreshToken refreshes an expired access token. Note: GitHub OAuth tokens don't expire by default, but GitHub Apps use refresh tokens.

type PRBranch 

type PRBranch struct {
	Ref string `json:"ref"`
	SHA string `json:"sha"`
}

PRBranch represents a PR branch reference.

type PRReview added in v0.3.0 

type PRReview struct {
	ID          int64     `json:"id"`
	Body        string    `json:"body"`
	State       string    `json:"state"`
	User        *User     `json:"user"`
	SubmittedAt time.Time `json:"submitted_at"`
}

PRReview is one approve/request-changes/comment envelope from a reviewer. State is "APPROVED", "CHANGES_REQUESTED", "COMMENTED", or "DISMISSED".

type PRReviewComment added in v0.3.0 

type PRReviewComment struct {
	ID        int64     `json:"id"`
	Body      string    `json:"body"`
	User      *User     `json:"user"`
	Path      string    `json:"path"`
	Line      int       `json:"line"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

PRReviewComment is a line-level comment attached to a PR's diff. Has a path/line for context that's useful in retrieval.

type PullRequest 

type PullRequest struct {
	ID        int64      `json:"id"`
	Number    int        `json:"number"`
	Title     string     `json:"title"`
	Body      string     `json:"body"`
	State     string     `json:"state"`
	HTMLURL   string     `json:"html_url"`
	User      *User      `json:"user"`
	Head      *PRBranch  `json:"head"`
	Base      *PRBranch  `json:"base"`
	CreatedAt time.Time  `json:"created_at"`
	UpdatedAt time.Time  `json:"updated_at"`
	MergedAt  *time.Time `json:"merged_at"`
	ClosedAt  *time.Time `json:"closed_at"`
}

PullRequest represents a GitHub pull request.

type Repository 

type Repository struct {
	ID            int64            `json:"id"`
	Owner         string           `json:"-"` // Populated from FullName, not JSON
	OwnerInfo     *RepositoryOwner `json:"owner"`
	Name          string           `json:"name"`
	FullName      string           `json:"full_name"`
	Description   string           `json:"description"`
	Private       bool             `json:"private"`
	Archived      bool             `json:"archived"`
	Fork          bool             `json:"fork"`
	Parent        *Repository      `json:"parent"`
	HTMLURL       string           `json:"html_url"`
	DefaultBranch string           `json:"default_branch"`
}

Repository represents a GitHub repository.

type RepositoryOwner 

type RepositoryOwner struct {
	Login string `json:"login"`
	ID    int64  `json:"id"`
}

RepositoryOwner represents the owner object in GitHub API responses.

type TokenRefresher 

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

TokenRefresher implements driven.TokenRefresher for GitHub.

func NewTokenRefresher 

func NewTokenRefresher(clientID, clientSecret string) *TokenRefresher

NewTokenRefresher creates a GitHub token refresher.

type TreeEntry 

type TreeEntry struct {
	Path string `json:"path"`
	Mode string `json:"mode"`
	Type string `json:"type"` // "blob" or "tree"
	Size int64  `json:"size"`
	SHA  string `json:"sha"`
	URL  string `json:"url"`
}

TreeEntry represents a file in a repository tree.

type User 

type User struct {
	ID        int64  `json:"id"`
	Login     string `json:"login"`
	Name      string `json:"name"`
	Email     string `json:"email"`
	HTMLURL   string `json:"html_url"`
	AvatarURL string `json:"avatar_url"`
}

User represents a GitHub user.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.