github

package
v0.4.14 Latest Latest
Warning

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

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

Documentation

Overview

Package github is the xray GitHub connector. It populates the bulk of the canonical model: repo metadata, branches, branch protection (where accessible), codeowners, commits, commit_files, commit_coauthors, prs, pr_commits, reviews, pr_comments, pr_review_requests, pr_labels, releases, repo_languages, and deploys derived from releases.

All HTTP traffic flows through an oauth2 client wrapped with the shared ratelimit transport. The connector is strictly read-only and never issues PATCH/POST/DELETE requests. No source-content, PR or commit body text is persisted: bodies are parsed for structured signals at extract time and discarded.

File-metric and harness-artifact extraction live in file_metrics.go and harness.go (owned by the M4 agent in the same package). Extract calls those helpers via in-package forward references.

Index

Constants

This section is empty.

Variables

View Source 
var RequiredScopes = []string{"repo", "read:org"}

RequiredScopes is the minimal set of OAuth scopes xray exercises against GitHub. Any scope on a token that isn't in this set is reported as surplus so the customer can right-size the token, but xray issues only read calls regardless of what's granted.

Functions

This section is empty.

Types

type Connector 

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

Connector is the github connector. It owns its own HTTP client (wrapped with the ratelimit transport), a REST client, and a GraphQL client.

func New 

func New(cfg config.GitHubConn, log *slog.Logger) (*Connector, error)

New constructs a Connector with the supplied config and logger.

The logger may be nil; a discarding logger is substituted. The returned http.Client carries the ratelimit transport so every REST and GraphQL call benefits from retry/backoff without per-call wrapping.

func (*Connector) BudgetSnapshot added in v0.4.4 

func (c *Connector) BudgetSnapshot() map[string]ratelimit.BudgetState

BudgetSnapshot returns the current rate-limit budget for this connector.

func (*Connector) Extract 

func (c *Connector) Extract(ctx context.Context, repo connector.Repo, window connector.Window, sink connector.Sink) connector.Provenance

Extract is the entry point for a (repo, window) extraction. It builds a Provenance value, drives every sub-extractor, and returns the result.

Errors at any single stage are logged and recorded under prov.Errors[<table>] but do not abort the rest of the run. Context cancellation does abort: PaginationComplete is flipped false on the way out so the manifest records the truncation.

Stages are organised into three phases (see #71):

  1. Sync prelude — mailmap + repo row + team mapping. Fast and feeds downstream state.
  2. Parallel block — two goroutines: A) clone-bound: languages, branches, codeowners, releases, commits, file_metrics, harness_artifacts. Writes to provA. B) API-bound: PRs (prefers prefetch cache when populated by run.go's clone-phase prefetch goroutine) then issues (incidents/defects). Writes to provB.
  3. Sync postlude — merge provA + provB into prov.

The store (sink) is already mutex-guarded for concurrent inserts, so the two goroutines write rows safely. Provenance fragments are disjoint by design (the goroutines own non-overlapping error/row contexts) so the merge is loss-less under the first-wins-per-context policy in (*Provenance).Merge.

func (*Connector) Name 

func (c *Connector) Name() string

Name returns the connector name as recorded in extraction provenance.

func (*Connector) Ping 

func (c *Connector) Ping(ctx context.Context) error

Ping performs a read-only authentication check against the GitHub REST API. Used by `xray check` to verify the token works without writing anything.

func (*Connector) Prefetch 

func (c *Connector) Prefetch(ctx context.Context, slug string, window connector.Window) error

Prefetch fans out the connector's slug-scoped prefetch work and waits for every stage to settle. The two stages — PRs (GraphQL) and releases (REST) — hit different rate-limit buckets, so they progress in parallel without same-bucket contention. The function signature satisfies the connector.Prefetcher interface so run.go can invoke it during the clone phase without a github-specific import. Errors from the sub-stages are folded into a single returned error: prefetch failures degrade to a live fetch in Extract regardless, so the caller only needs to know whether anything went wrong, not which stage. Safe to call concurrently for distinct slugs.

func (*Connector) ProbeEndpoints 

func (c *Connector) ProbeEndpoints(ctx context.Context, repos []string) ([]preflight.InaccessibleEndpoint, error)

ProbeEndpoints reports any permission-gated GitHub endpoints xray touches during a run that aren't accessible to the current token. Today this probes branch_protection only — the other admin-gated endpoints (org audit log, repo admin) are not yet exercised by xray. Add probes here as new endpoints are pulled in.

func (*Connector) RepoStats 

func (c *Connector) RepoStats(ctx context.Context, repos []string, since, until time.Time) ([]preflight.RepoStat, error)

RepoStats issues one cheap-aggregate GraphQL query per repo (diskUsage + totalCount + windowed commit count) and returns the per-repo stats the preflight package needs to build a Plan. All endpoints are read-only.

A probe failure on a single repo is recorded as an empty stat and the walk continues — `xray check` is a hint, not a gate.

func (*Connector) Scopes 

func (c *Connector) Scopes(ctx context.Context) (ScopeInfo, error)

Scopes performs a single GET /user call and returns the token's granted OAuth scopes as reported by the X-OAuth-Scopes response header. The call goes through the connector's existing rate-limited transport — no new client is built.

Read-only: GET only. The token never leaves the http client; only the returned header values are surfaced.

func (*Connector) SetCaptureHarnessContent 

func (c *Connector) SetCaptureHarnessContent(v bool)

SetCaptureHarnessContent toggles the harness-artifact content-capture flag. The constructor accepts only the GitHub connector config; the run wiring sets this from the top-level config.CaptureHarnessContent before the connector is invoked.

func (*Connector) SetExtractShards added in v0.4.6 

func (c *Connector) SetExtractShards(n int)

SetExtractShards sets the number of concurrent git subprocesses to use for the complexity_history and working-tree phases. 0 or 1 means serial (default). Resolved by the run wiring via resolveExtractShards.

type ScopeInfo 

type ScopeInfo struct {
	Granted []string
	Extra   []string
}

ScopeInfo is the result of a single scope-discovery probe. Granted is the parsed X-OAuth-Scopes header from a GET /user response; Extra is the granted set minus RequiredScopes. Both are sorted.

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.