Documentation
¶
Overview ¶
Package delivery checks, against local git, the delivery claims a harness session makes to the control plane.
The plane is a pipe: it holds the backlog and takes a clanker at its word. When a session records a branch or declares a commit merged, nothing verifies either claim — and one task (CLA-134) read `done` for four days while ~900 lines of its work sat unpushed on one laptop, its own PR merging a stale snapshot.
The driver is the right place to close that: it is already local, already in the git tree, and already watches the session stream for `claim_task` and `update_task` (CLA-242). This adds a check to an observation that already happens. It needs no new configured credentials - GitHub access rides the operator's own `gh` auth, resolved per remote below - and no plane change.
Fail open, not closed ¶
Every check has four outcomes, not two: Pass, Fail, Unknown, and Warn. Unknown is load-bearing. If the check cannot run — no git on PATH, no remote, a workdir that is not a repository, a remote tip we do not have locally — the answer is "could not verify", never "verified". A driver that reported a false pass would be worse than the gap it replaces, and one that blocked a legitimate closure because it could not find the tree would be worse still. Not knowing is not the same as knowing it is fine, and neither is grounds for overriding the session. Warn is CLA-310's: a check that ran and found only the loose side of an operator's explicit opt-out — never emitted by default.
Which working tree ¶
The driver spawns sessions in a workdir, but the work happens in a per-task worktree the driver did not create and does not track — and the workdir is routinely a multi-repo parent (`~/dev`) that is not a repository at all.
The resolution is narrower than it first looks: linked worktrees SHARE the repository's ref database, so the specific directory a session worked in is irrelevant. Every check here reads refs (`refs/heads/<branch>`, `ls-remote`, `merge-base`), so any working tree of the right repository answers identically. What must be found is the REPOSITORY whose refs carry the branch, which is a bounded search of the workdir and its first two directory levels — enough to reach both `~/dev/<repo>` and `~/dev/<repo>-wt/<task>`. A repository is never descended into, so a tree of worktrees costs one probe, not one per worktree.
Index ¶
- func GithubOwner(remoteURL string) string
- func Remote(ctx context.Context, repo, preferred string) string
- func Repos(ctx context.Context, workdir string) []string
- func ScopeEnv(token string) []string
- func ScopeRemoteEnv(ctx context.Context, dir, ghBin, remoteURL string) []string
- func TokenForOwner(ctx context.Context, dir, ghBin, owner string) string
- type Check
- type Claim
- type Kind
- type Report
- type Status
- type Verifier
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GithubOwner ¶ added in v0.13.3
GithubOwner reports the account that owns a github.com HTTPS remote URL, or "" when no scoping is derivable. See githubOwner.
func Remote ¶ added in v0.3.4
Remote picks the remote to act on in repo: the preferred one when the repository has it, otherwise its only remote. Shared with salvage for the same reason as Repos - a rescue has to push to the remote these checks will then judge it against. The workdir plays no part in this one, hence the empty one.
func Repos ¶ added in v0.3.4
Repos lists one working tree per distinct git repository at or below workdir - the search described in this package's doc, exposed for the driver's salvage path (CLA-314).
It is shared rather than reimplemented because salvage has to find the SAME repository these checks do. Two implementations of "which tree did the session work in" would agree until the day they did not, and on that day one of them would be committing.
func ScopeEnv ¶ added in v0.13.3
ScopeEnv returns the environment additions that scope ONE git invocation to token: every https://github.com/ URL that invocation resolves is rewritten, through GIT_CONFIG_* insteadOf config, into a token-bearing x-access-token URL. The token travels in the child's environment, never its argv - see the package comment on this section for why ps(1) rules argv out. The result is meant as extra env on a single exec; nothing is persisted.
func ScopeRemoteEnv ¶ added in v0.13.3
ScopeRemoteEnv is the whole CLA-458 resolution for one already-read remote URL: the env additions that let git read THAT remote as the github account owning it, or nil when no scoping applies - non-github host, or an owner whose token gh cannot serve. nil means "run unscoped", byte-identical to pre-CLA-458 behavior; every fallback stays fail-open.
func TokenForOwner ¶ added in v0.13.3
TokenForOwner resolves owner's GitHub token with `gh auth token --user`, spawning ghBin in dir under runGH's interaction-hostile discipline. Any failure - gh missing, no such account, a wedged call - is an empty token, which callers treat as "run unscoped". A token is also refused if it cannot ride a single config value intact (embedded whitespace would corrupt the insteadOf key into something silently wrong).
Types ¶
type Check ¶
type Check struct {
Kind Kind
Status Status
// Detail is written to be read in a log at 3am by someone who was asleep when
// it happened: it names what is unpushed or unmerged, not just that something
// is wrong.
Detail string
}
Check is one verified (or unverifiable) assertion.
type Claim ¶
type Claim struct {
// Label identifies the task in logs ("CLA-253"); cosmetic.
Label string
// Branch is the work-in-progress branch recorded as the handover record.
Branch string
// Commit and IntegrationBranch are the declared delivery: the commit that
// carried the work, and the branch it is claimed to have landed on.
Commit string
IntegrationBranch string
// PR is the pull request the session named as carrying the delivery
// (CLA-310). Verified through the `gh` CLI — mergeable, with a check
// rollup that actually ran and passed; see prcheck.go for the two
// conditions, the bounded wait, and the no-CI decision.
PR string
// Repo is the repository the claim lives in ("owner/name"). When set, it resolves ambiguity when the same branch exists in multiple repos (CLA-351).
Repo string
}
Claim is what a session told the plane it delivered.
type Kind ¶
type Kind string
Kind names which claim a check was about.
const ( // BranchPushed: a branch recorded via `update_task(branch: ...)` is really on // the remote, and the local tip is an ancestor of the remote tip. BranchPushed Kind = "branch" // CommitMerged: a declared `delivery.commit` is an ancestor of the declared // `delivery.integrationBranch`. CommitMerged Kind = "merge" )
const PRVerified Kind = "pr"
PRVerified is the check on the pull request a session named in a delivery: mergeable, and carrying a check rollup that actually ran and passed.
type Report ¶
type Report struct {
Claim Claim
// Repo is the working tree the checks ran in. Empty when none was resolved.
Repo string
Checks []Check
}
Report is everything the driver learned about one session's delivery claim.
func (Report) Failed ¶
Failed reports whether any check ran and came back false. Unknown is not a failure — it is an absence of knowledge.
func (Report) MergeVerified ¶
MergeVerified reports what the merge check concluded: (verified, ran). When ran is false the driver must not attest anything — an honest `mergeVerified` is only written for a check that actually happened.
type Status ¶
type Status string
Status is the outcome of one check. The three-way split is the whole point: see the package doc on failing open.
const ( // Pass: the check ran and the claim holds. Pass Status = "pass" // Fail: the check ran and the claim does not hold. This is the CLA-134 case. Fail Status = "fail" // Unknown: the check could not run. NOT a pass. Unknown Status = "unknown" // Warn: the check ran and found the loose side of an explicit operator // opt-out (CLA-310's allow_unchecked_pr). It is neither a pass — the detail // says what to confirm — nor a failure, because the operator chose it. Warn Status = "warn" )
type Verifier ¶
type Verifier struct {
// contains filtered or unexported fields
}
Verifier checks delivery claims against the git repositories under a workdir. The zero value is not usable; build one with New.
func New ¶
New builds a Verifier rooted at a session's workdir. remote is the git remote the claims are judged against; empty means "origin, or the only remote there is".
func (*Verifier) AllowUncheckedPR ¶ added in v0.10.2
AllowUncheckedPR applies the no-CI opt-out (CLA-310): an empty check rollup on a delivery's PR becomes a WARN instead of a refusal. It never relaxes the mergeability condition, and it changes nothing for repos whose PRs do carry checks. Returns the verifier, for chaining off New.
Source Files