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 ¶
- Variables
- type Connector
- func (c *Connector) Extract(ctx context.Context, repo connector.Repo, window connector.Window, ...) connector.Provenance
- func (c *Connector) Name() string
- func (c *Connector) Ping(ctx context.Context) error
- func (c *Connector) Prefetch(ctx context.Context, slug string, window connector.Window) error
- func (c *Connector) ProbeEndpoints(ctx context.Context, repos []string) ([]preflight.InaccessibleEndpoint, error)
- func (c *Connector) RepoStats(ctx context.Context, repos []string, since, until time.Time) ([]preflight.RepoStat, error)
- func (c *Connector) Scopes(ctx context.Context) (ScopeInfo, error)
- func (c *Connector) SetCaptureHarnessContent(v bool)
- type ScopeInfo
Constants ¶
This section is empty.
Variables ¶
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 ¶
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) 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):
- Sync prelude — mailmap + repo row + team mapping. Fast and feeds downstream state.
- 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). Writes to provB.
- 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) Ping ¶
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 ¶
Prefetch starts a paginated PR walk for the supplied slug and stashes the result for Extract to consume later. Safe to call concurrently for distinct slugs. Returns immediately after the walk completes (the result is held on the connector). The function signature satisfies the connector.Prefetcher interface so run.go can invoke it during the clone phase without a github-specific import.
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 ¶
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 ¶
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.
Source Files