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, list 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
- Variables
- type Adapter
- type Conn
- func (c *Conn) Apply(ctx context.Context, req provider.EffectRequest) (provider.EffectResult, error)
- func (c *Conn) CheckHealth(ctx context.Context) provider.HealthStatus
- func (c *Conn) Handler(sink provider.IngressSink) http.Handler
- func (c *Conn) Health() provider.HealthStatus
- func (c *Conn) List(ctx context.Context, scope v1alpha1.Scope) ([]v1alpha1.ObjectRef, error)
- func (c *Conn) MintGitCredential(ctx context.Context, req provider.GitCredentialRequest) (provider.Credential, error)
- func (c *Conn) MissingInstallations(ctx context.Context, identity string, repos []string) (string, []string, error)
- func (c *Conn) Normalise(ctx context.Context, ev provider.RawEvent) ([]v1alpha1.Event, error)
- func (c *Conn) Observe(ctx context.Context, ref v1alpha1.ObjectRef) (provider.Observation, error)
- func (c *Conn) Project(ctx context.Context, ref v1alpha1.ObjectRef, p provider.Projection) error
- func (c *Conn) ReadContent(ctx context.Context, ref v1alpha1.ObjectRef) (server.Content, error)
- func (c *Conn) Recover(ctx context.Context, since time.Time, sink provider.IngressSink) error
- func (c *Conn) ResolveGroup(ctx context.Context, src v1alpha1.GroupSource) ([]string, error)
- func (c *Conn) Tier(ctx context.Context, login, association string) (string, error)
- type MergeError
- type Options
Constants ¶
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" )
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).
const ( // MarkerPhrase is the marker's visible text, which List searches comments for. 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, list 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.
const ( KindRelease = "release" KindDeployment = "deployment" )
Object kinds the normaliser emits besides provider.KindIssue and provider.KindPR.
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 )
const DefaultDeployEnvironment = "github-pages"
DefaultDeployEnvironment is the environment whose latest deployment Observe reports (item.deploy): the docs' GitHub Pages.
const DeployLinkPRs = 20
DeployLinkPRs is how many of the newest merged PRs a deployment is checked against.
const DuplicateLabel = "duplicate"
DuplicateLabel is the label link-duplicate adds.
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.
const KindRepo = "repo"
KindRepo is the kind of a work item's link to a whole repo (an event without an object).
const ListWindow = 90 * 24 * time.Hour
ListWindow is how far back List looks: objects updated in the last 90 days.
const Type = string(v1alpha1.ProviderTypeGitHub)
Type is the Provider spec.type this adapter connects.
Variables ¶
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.
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 (*Adapter) Connect ¶
func (a *Adapter) Connect(ctx context.Context, p v1alpha1.Provider, secrets provider.SecretResolver) (provider.Conn, error)
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).
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 ¶
func (c *Conn) Apply(ctx context.Context, req provider.EffectRequest) (provider.EffectResult, error)
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. 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) List ¶
List implements provider.Conn (github-provider.md §Observe, list and projection): for each repo in scope, the open issues and PRs updated in the last ListWindow, plus those (open or closed) updated in that window whose comments carry the projection marker's text: two searches per repo (search API, paginated), as the read identity with observePerms on that repo. Refs are sorted and unique.
scope.repos are patterns (internal/patterns): an exact "owner/name" is used as is; a glob or regex is matched against the repos the read identity's App is installed on, in the pattern's owner when that part is exact, else in the Provider's scope.orgs. An empty scope.repos means every repo in scope.orgs. scope.exclude removes repos, and a Provider scope.orgs bounds everything. Channels and branches don't apply to GitHub objects.
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 ¶
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 ¶
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 comments and review threads beyond the first 100 (up to maxFollowPages each).
- 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.
- Projections: the markers in comments written by the projecting App (comments by anyone else that look like markers are ignored), one per work item (the oldest wins), sorted.
- 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 returned: comment bodies are read only to find the markers.
func (*Conn) Project ¶
Project implements provider.Conn (github-provider.md §Observe, list and projection): as the author identity, reading with observePerms and writing with projectPerms on the object's repo, it
- 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;
- 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 ¶
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 ¶
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 ¶
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 ¶
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.
Source Files
¶
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. |