github

package
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Oct 29, 2026 License: AGPL-3.0 Imports: 27 Imported by: 0

Documentation

Overview

Package github is the provider adapter for GitHub and GHE (design/workstreams/provider-github/LLD/github-provider.md): App auth and scoped git credentials (GH-S1-T01), webhook ingress and normalisation (GH-S1-T02), observe and projection (GH-S1-T03) and effects (GH-S1-T04).

It acts as the Provider's App identities ("author", "reviewer"), whose installation tokens internal/provider/tokens mints, one repo per token.

Index

Constants

View Source
const (

	// ReviewerIdentity is the only identity the review ops act as.
	ReviewerIdentity = "reviewer"
	// OutcomeLabelledForMerge is pr.merge's outcome when review requirements blocked the merge
	// and the merge label was added instead (Q5).
	OutcomeLabelledForMerge = "labelled-for-merge"
)
View Source
const (
	// MaxWebhookBytes bounds a webhook body, like the API server's body limit (1 MB).
	MaxWebhookBytes = 1 << 20
	// DeliveryPrefix starts every delivery ID: "gh-<X-GitHub-Delivery>".
	DeliveryPrefix = "gh-"
)

Webhook ingress (github-provider.md §Ingress and normalisation).

View Source
const (

	// MarkerPhrase is the marker's visible text, for the people reading the object.
	MarkerPhrase = "Tracked by CCF Factory"
	// MaxMarkerBytes caps a marker comment (GitHub's limit is 65 536 characters). A projection
	// whose marker would be larger is written without its state, which then lives only in the
	// dispatcher, and a warning is logged.
	MaxMarkerBytes = 60 << 10
)

The projection marker (github-provider.md §Observe and projection): one hidden comment per (work item, object), authored by the author App:

<!-- factory:wi v=1 id=wi_01JA… state=release:drafting,train:compliance-framework%2Fworkflows%23123 runs=release-docs:1 links=github-public:compliance-framework%2Fdocs%2357:pr:primary labels=factory%3Atracked -->
🏭 Tracked by CCF Factory — [view](https://<public-url>/workitems/wi_01JA…)

Fields are space-separated key=value pairs after the version; every key and value is percent-encoded (only A-Z a-z 0-9 . _ ~ - stay as they are), so a value can hold no space, comma, colon, ">" or "-->". state is k:v pairs, a string value encoded as is and any other value (number, bool, map, list) as "b64:" + base64url(JSON); runs are the counters, k:n; links are provider:ref[:kind[:primary]]; labels are the factory-owned labels this work item put on the object. Unknown keys are ignored, so v=1 can grow optional fields; a marker of another version is not read.

View Source
const (
	KindRelease    = "release"
	KindDeployment = "deployment"
)

Object kinds the normaliser emits besides provider.KindIssue and provider.KindPR.

View Source
const (
	// DefaultTier is the tier of an actor no trust rule matches.
	DefaultTier = "anyone"
	// DefaultGroupTTL is how long a Group member source resolved for trust is reused, when
	// the Group sets no cache.ttl.
	DefaultGroupTTL = 10 * time.Minute
)
View Source
const DefaultDeployEnvironment = "github-pages"

DefaultDeployEnvironment is the environment whose latest deployment Observe reports (item.deploy): the docs' GitHub Pages.

View Source
const DeployLinkPRs = 20

DeployLinkPRs is how many of the newest merged PRs a deployment is checked against.

View Source
const DuplicateLabel = "duplicate"

DuplicateLabel is the label link-duplicate adds.

View Source
const EventIdentity = "author"

EventIdentity is the identity whose App is the event source (the only App with a webhook) and holds the read permissions normalisation needs (members, contents, pull requests). When a Provider has no such identity, its first identity by name is used.

View Source
const KindRepo = "repo"

KindRepo is the kind of a work item's link to a whole repo (an event without an object).

Type is the Provider spec.type this adapter connects.

Variables

View Source
var (
	// ErrMergeBlocked is a merge GitHub refused (405): not mergeable, required checks, or
	// review requirements without a merge label to fall back to.
	ErrMergeBlocked = errors.New("github: merge blocked")
	// ErrReviewRequired is a merge blocked by review requirements (also ErrMergeBlocked).
	ErrReviewRequired = errors.New("github: merge blocked: review required")
	// ErrHeadChanged is a merge refused because the PR's head moved past the expected SHA
	// (409).
	ErrHeadChanged = errors.New("github: merge refused: head changed")
)

Errors of pr.merge, matched with errors.Is. Each is also provider.ErrInvalid: the provider refused the merge, and retrying the same request won't change that.

View Source
var DefaultTrainRepos = []string{"compliance-framework/workflows"}

DefaultTrainRepos is where CCF's release train keeps its tracking issues.

Functions

This section is empty.

Types

type Adapter

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

Adapter connects Provider objects of type github.

func NewAdapter

func NewAdapter(opts Options) *Adapter

NewAdapter returns the GitHub adapter.

func (*Adapter) Connect

Connect implements provider.Adapter. It resolves the webhook secret and every identity's private key through secrets and parses the keys, so a missing secret or a bad key fails here; it makes no GitHub call (CheckHealth does).

func (*Adapter) Type

func (a *Adapter) Type() string

Type implements provider.Adapter.

type Conn

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

Conn is a connection to one GitHub Provider instance. It is safe for concurrent use.

func (*Conn) Apply

Apply implements provider.Conn: every API-side op of contracts.md §Effect ops, as the request's identity (default: the author identity), idempotent by the request's key (see above). Git-side ops are ErrUnsupported (the agent executes them), as are targets GitHub has no notion of (channels, groups). Errors: a missing object is ErrNotFound, a request GitHub or the adapter refuses ErrInvalid (a refused merge a *MergeError), and a rate limit or GitHub being unavailable, after the retries, a *provider.RetryableError.

func (*Conn) CheckHealth

func (c *Conn) CheckHealth(ctx context.Context) provider.HealthStatus

CheckHealth authenticates as every identity's App (GET /app), records the outcomes and returns the resulting Health. `factory serve` calls it when it connects the Provider and again whenever the catalog changes.

func (*Conn) Handler

func (c *Conn) Handler(sink provider.IngressSink) http.Handler

Handler implements provider.Conn: POST /hooks/<provider>. It verifies X-Hub-Signature-256 (HMAC-SHA256 of the body with the webhook secret, compared in constant time), then calls sink.Accept with the delivery and answers only once Accept has returned: 202 when it stored the delivery, 200 for a duplicate, 503 for any other error (GitHub then redelivers). A bad or missing signature is 401; a request that isn't a POST 405, a body over MaxWebhookBytes 413, a delivery without a delivery ID or event name 400. Every refusal is an application/problem+json body, as the API's errors are (provider.WriteProblem). Bodies are never logged.

func (*Conn) Health

func (c *Conn) Health() provider.HealthStatus

Health implements provider.Conn: ok when every identity's last check or mint succeeded, down when every one failed, degraded in between, unknown before anything was checked. It doesn't block.

func (*Conn) MintGitCredential

func (c *Conn) MintGitCredential(ctx context.Context, req provider.GitCredentialRequest) (provider.Credential, error)

MintGitCredential implements provider.Conn: one installation token on req.Repo with req.Permissions, via tokens.Minter.Token (which refuses unscoped or over-broad requests with provider.ErrInvalid). Outcomes that say whether the identity can authenticate update Health. An App that isn't installed on the repo is a *provider.NotInstalledError.

func (*Conn) MissingInstallations

func (c *Conn) MissingInstallations(ctx context.Context, identity string, repos []string) (string, []string, error)

MissingInstallations implements provider.InstallationChecker: per owner, the repos the identity's App installation lists (tokens.Minter.InstallationRepos); an owner the App isn't installed on at all misses every one of its repos. Repos compare case-insensitively.

func (*Conn) Normalise

func (c *Conn) Normalise(ctx context.Context, ev provider.RawEvent) ([]v1alpha1.Event, error)

Normalise implements provider.Conn: the mapping table of github-provider.md §Ingress and normalisation. A delivery becomes one Event per object it is about (a check suite one per PR, a deployment one per merged PR it contains), numbered in object-ref order: ID provider.EventID(ev.ID, n), Source and Data.Provider the Provider's name, Subject the object ref, Time the delivery's ReceivedAt. The actor is "<provider>:<login>", its tier the first Provider trust rule it matches (DefaultTier when none does), and the factory's own Apps (by their bot login) set IsFactory and Identity. Data.Raw holds the payload, which rules never see; Data.Facts is what they read (event.*).

A delivery whose event or action isn't in the table maps to no Events and no error. A body that isn't a payload, or a delivery for another Provider, is provider.ErrInvalid. GitHub calls the mapping needs (the factory Apps' logins, group members for trust, a release's previous tag, the PRs a deployment contains) return their errors, so the delivery is retried.

func (*Conn) Observe

func (c *Conn) Observe(ctx context.Context, ref v1alpha1.ObjectRef) (provider.Observation, error)

Observe implements provider.Conn: one GraphQL query per object (github-provider.md §Observe), as the read identity with observePerms on the object's repo, and follow-up pages for a PR's review threads beyond the first 100 (up to maxFollowPages).

  • Issues: state, labels, author, sub-issues, the PRs that close it (linked PRs), the comment count.
  • PRs: draft, head SHA, base branch, labels, author, checks (the head commit's check suites rolled up, see checksOf), approvals (the latest approving, changes-requesting or dismissing review of each reviewer: the factory's Apps map to their identity, "reviewer" or "author", anyone else to their login), unresolved threads, merged-at and the merge commit; a merged PR also gets Deploy.
  • A "repo" ref: open, or closed once archived. Releases and deployments are immutable records: closed, with no call.

A ref of the other kind (an issue ref naming a PR) is ErrNotFound, as a missing object is. No untrusted text is read or returned: of the comments, only their count is read. The factory's projection markers are not read back (Project reads them, to update its own).

func (*Conn) Project

func (c *Conn) Project(ctx context.Context, ref v1alpha1.ObjectRef, p provider.Projection) error

Project implements provider.Conn (github-provider.md §Observe and projection): as the author identity, reading with observePerms and writing with projectPerms on the object's repo, it

  1. ensures the projection's labels and removes the labels the work item's previous marker owned that the projection no longer has (unless another work item's marker on the object owns them too); labels nobody projected, a human's kill switch included, are never touched;
  2. upserts the work item's marker comment: the oldest marker the App wrote for the work item is edited when its body differs, else one is created.

Labels go first, so a failed marker write is retried with the old ownership still on record. Projecting the same Projection again makes no write. Releases, deployments and repos carry no marker: projecting onto them does nothing. A missing object, or a ref of the other kind, is ErrNotFound.

func (*Conn) ReadContent

func (c *Conn) ReadContent(ctx context.Context, ref v1alpha1.ObjectRef) (server.Content, error)

ReadContent implements server.ContentReader: the untrusted text a context item names, as Markdown, read with the read identity's token (Observe's permissions). An object ref gives the issue's or PR's title, body and conversation comments, each comment headed by its author, with the factory's own projection comments left out; a content ref gives that body, comment or review. The factory's hidden markers are stripped from every text, so an agent never sees (or copies) one. Author is the login that wrote the object, comment or review. A missing object, or one of another kind than the ref says, is ErrNotFound; a ref that names no GitHub object or content gives no content (the item stays reference-only).

func (*Conn) Recover

func (c *Conn) Recover(ctx context.Context, since time.Time, sink provider.IngressSink) error

Recover implements provider.Conn (the restart gap): it lists each App's webhook deliveries (GET /app/hook/deliveries, newest first, which GitHub keeps for a few days) back to since, fetches each one's request (GET /app/hook/deliveries/{id}) and sends it to sink.Accept, oldest first, once per GUID (redeliveries share it; the first delivery is used). A delivery the sink already has comes back as ErrDuplicateDelivery and is skipped; any other Accept error stops Recover. An App without a webhook (404) has nothing to recover.

A recovered delivery has the headers and payload GitHub recorded and ReceivedAt set to when GitHub delivered it. Its body is GitHub's re-encoding of the payload, so it carries no signature to verify; the App JWT authenticated the listing instead.

func (*Conn) ResolveGroup

func (c *Conn) ResolveGroup(ctx context.Context, src v1alpha1.GroupSource) ([]string, error)

ResolveGroup implements provider.Conn: the GitHub logins in one member source, sorted and without duplicates.

  • orgRole {org, role}: the org's members with that role: "admin" the owners, "member" every member (GET /orgs/{org}/members?role=admin|all);
  • team "org/slug": the team's members, child teams included (GET /orgs/{org}/teams/{slug}/members);
  • users: the logins listed.

The org calls use the read identity's org token (members: read). An unknown org or team is provider.ErrNotFound; a source for another Provider, with no or several sources, a malformed team or an unknown role is provider.ErrInvalid; a userGroup (Slack) is provider.ErrUnsupported.

func (*Conn) Tier

func (c *Conn) Tier(ctx context.Context, login, association string) (string, error)

Tier resolves a GitHub login's tier through the Provider's trust rules, in order: the first rule whose matchers all match wins (a rule with none matches anyone), else DefaultTier. Matchers: group (the login is in one of the catalog Group's member sources on this Provider, resolved through ResolveGroup and cached for the Group's cache.ttl, default DefaultGroupTTL), authorAssociation (association, as GitHub reports it), bots (the login). workspaceMember is Slack's and never matches. Logins compare case-insensitively.

type MergeError

type MergeError struct {
	// Status is GitHub's status (405, 409), or zero when the adapter refused before merging.
	Status int
	// ReviewRequired is set when review requirements block the merge.
	ReviewRequired bool
	Reason         string
	Err            error
}

MergeError is a refused merge: errors.Is matches ErrMergeBlocked, ErrReviewRequired or ErrHeadChanged, and provider.ErrInvalid. It unwraps to GitHub's *tokens.APIError, if any.

func (*MergeError) Error

func (e *MergeError) Error() string

func (*MergeError) Is

func (e *MergeError) Is(target error) bool

Is maps the refusal to the package's and the provider's errors.

func (*MergeError) Unwrap

func (e *MergeError) Unwrap() error

type Options

type Options struct {
	// HTTPClient makes the GitHub calls (default: tokens' default client).
	HTTPClient *http.Client
	// Clock times token caches, credential expiry and health (default clock.Real).
	Clock clock.Clock
	// Logger gets the adapter's logs (default: discarded). Tokens are never logged.
	Logger *slog.Logger
	// Groups resolves the catalog Groups named by trust rules; nil means group rules never
	// match.
	Groups provider.GroupLookup
	// TrainRepos are the repos ("owner/name") whose closed issues carry a release train's
	// state, read by the ccf-train extractor (default DefaultTrainRepos).
	TrainRepos []string
	// UIBaseURL is the factory's public URL, which the projection marker's visible line links
	// to (<UIBaseURL>/workitems/<id>); without it the line has no link.
	UIBaseURL string
	// DeployEnvironment is the environment whose latest deployment of the default branch
	// Observe reports for merged PRs (default DefaultDeployEnvironment).
	DeployEnvironment string
}

Options are the adapter-wide dependencies, shared by every Conn.

Directories

Path Synopsis
Package githubtest is an httptest GitHub for the GitHub adapter's tests.
Package githubtest is an httptest GitHub for the GitHub adapter's tests.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL