Struct GitHub 

pub struct GitHub { /* private fields */ }

The GitHub implementation of RemoteHost, driven through gh.

Every method is one gh invocation, and the program that answers as gh is the seam a journey substitutes: GitHub’s decisioning is what a test replaces, never the git underneath it.

Implementations

impl GitHub

pub fn new(repo: impl Into<String>) -> Result<Self>

Address this host at one repository, named owner/name.

Checked here rather than at each call: the slug is interpolated into every gh --repo invocation, and a value that is not one repository is a value that addresses something nobody asked for.

Trait Implementations

impl Clone for GitHub

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for GitHub

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for GitHub

impl PartialEq for GitHub

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl RemoteHost for GitHub

fn check_log(&self, cr: &ChangeRequest, check: &Check) -> Result<ArtifactId>

Store one check’s log as an artifact, or refuse.

A fetch that did not produce the log is an error and no artifact: an artifact reads as what the check printed, so one holding the reason there is none is a lie in the only record a consumer has. A caller that must not fail over a missing log declines to fail over this error, as crate::publish does.

fn describe_change( &self, cr: &ChangeRequest, title: Option<&str>, body: &str, ) -> Result<()>

One gh pr edit, handing the body over as a file.

A file rather than --body, because a body is prose of unbounded size and an argument vector is not where multi-line Markdown belongs: the same reason onevcs publish takes --body-file. The file is written under a scratch directory that goes when this returns, and gh reads it before then.

fn change_description(&self, cr: &ChangeRequest) -> Result<Description>

One gh pr view, reading exactly the two fields a description is.

A response missing either is refused rather than read as empty: “the change request has no body” and “the host would not say what the body is” are different facts, and a caller finishing a description off what it reads here would otherwise start from a blank the host never answered.

fn visibility(&self) -> Result<Visibility>

One gh api repos/{owner}/{name}, reading the two fields GitHub states a repository’s visibility in. visibility is public, private or internal, and an internal repository is private to everybody outside its organisation; an answer carrying neither field is refused rather than read as either.

fn is_draft(&self, cr: &ChangeRequest) -> Result<bool>

One gh pr view, reading the one field the host decides a draft by.

A response that does not carry it is refused rather than read as “not a draft”: what this decides is whether a change may be asked to merge, and “could not look” reported as “nothing is holding it” is the one answer that lands work somebody held back.

fn merged_at(&self, cr: &ChangeRequest) -> Result<Option<Sha>>

One gh pr view, reading exactly the two fields a merge is decided from — the same read merge makes, through the same parser, so watching a change request and merging one cannot come to disagree about what merged means.

fn merged_head(&self, cr: &ChangeRequest) -> Result<Option<MergedChange>>

One gh pr view, reading the two fields a merge is decided from and the head it was of — the read merged_at makes, through the same parser, with headRefOid beside it rather than in a second request.

fn merge_time(&self, cr: &ChangeRequest) -> Result<Option<String>>

One gh pr view, reading exactly the field GitHub records a merge’s time in.

mergedAt is null — or GitHub’s zero time — on a change request that has not merged, and both read as None.

fn mergeability(&self, cr: &ChangeRequest) -> Result<Mergeability>

One gh pr view, reading exactly the two fields GitHub decides a merge’s mergeability by.

mergeable is the answer — MERGEABLE, CONFLICTING, or UNKNOWN while GitHub has not computed it — and mergeStateStatus is quoted beside it, since DIRTY is how GitHub spells the same conflict there. A response that carries no mergeable, or a value GitHub has never answered, is refused rather than read as either: a conflict nobody reported ends a publication, and a mergeable change nobody reported hides one.

fn head_activity(&self, cr: &ChangeRequest) -> Result<HeadActivity>

Two REST reads about the commit the caller names: the workflow runs on it, and its check suites.

A run counts while its status is anything but completed; a suite counts while it is not completed and has at least one check run, because GitHub leaves an installed app’s empty queued suite on every commit for ever. A credential refused the suites answers from the runs alone, saying so with complete: false; one refused both reads is the runs’ refusal.

The commit asked about is the caller’s — a watch names the one it pushed — and the commit answered about is read off the records GitHub returned, so a host whose records name another commit says so rather than having this build’s question stamped onto its answer. Reading the change request’s head first would cost a third request on every read and decide nothing these two do not.

fn review_comments( &self, change: &ChangeId, since: Option<&ReadMarker>, ) -> Result<ReviewRead>

One GraphQL query document, paged — see review::github.

fn reply_to_comment( &self, change: &ChangeId, comment: &CommentId, body: &str, _key: &str, ) -> Result<PostedReply>

One REST request — see review::github.

fn change_standings( &self, root: &str, changes: &[ChangeId], ) -> Result<ChangeStandings>

One aliased GraphQL query per 50 change requests — see standings::github.

fn review_standings( &self, root: &str, changes: &[(ChangeId, Option<ReadMarker>)], ) -> Result<ReviewStandings>

One aliased GraphQL query per 150 change requests — see standings::github.

fn retarget_change( &self, change: &ChangeId, base: &str, body: Option<&str>, ) -> Result<ReadCost>

One REST request — see standings::github.

fn reopen_change(&self, change: &ChangeId) -> Result<ReadCost>

One REST request — see standings::github.

fn allows_auto_merge(&self) -> Result<bool>

One gh repo view, reading the one field GitHub decides it by.

fn authenticated_user(&self) -> Result<String>

Who the host believes is calling.

fn open_change(&self, req: ChangeSpec) -> Result<ChangeRequest>

Open a change request.

fn find_changes(&self, head: &str, base: &str) -> Result<Vec<ChangeRequest>>

Every open change request from head into base.

fn change_checks(&self, cr: &ChangeRequest) -> Result<ChangeChecks>

The checks the host is reporting on a change request, and which of its sources that answer was read from.

fn merge(&self, cr: &ChangeRequest, policy: MergePolicy) -> Result<MergeOutcome>

Merge a change request under a policy.

fn ready_for_review(&self, cr: &ChangeRequest) -> Result<()>

Take a change request out of its draft state, so the host will let it land.

fn required_checks_on(&self, base: &str) -> Result<RequiredChecks>

The checks the repository requires before anything merges into base, asked of the branch itself rather than of a change request targeting it.

fn requires_up_to_date(&self, base: &str) -> Result<bool>

Whether the host requires a branch to be up to date with base before it merges a change request into it — GitHub branch protection’s strict.

impl StructuralPartialEq for GitHub