Documentation
¶
Overview ¶
Package forge holds the pull request model shared by every tool that reads a code host. Today that host is GitHub, read through the gh CLI.
Index ¶
Constants ¶
const ( PRStatusClosed = "CLOSED" PRStatusMerged = "MERGED" PRStatusOpen = "OPEN" ReviewApproved = "approved" ReviewChangesRequested = "changes requested" StatusCompleted = "completed" StatusFailing = "failing" StatusPassing = "passing" )
Display values shared by PullRequest/ChecksStatus/WorkflowSummary and the views that render them, so both sides compare against the same constant.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CIWorkflowRun ¶
type CIWorkflowRun struct {
StartedAt time.Time `json:"started_at"`
UpdatedAt time.Time `json:"updated_at"`
Workflow string `json:"workflow"`
Status string `json:"status"`
Conclusion string `json:"conclusion"`
URL string `json:"url"`
FailingJobs []string `json:"failing_jobs,omitempty"`
ID int64 `json:"id"`
}
CIWorkflowRun is one workflow's latest run on a commit.
type CheckDetail ¶
type CheckDetail struct {
StartedAt time.Time
CompletedAt time.Time
Name string
Workflow string
Status string
Conclusion string
}
CheckDetail is a single CI check on a pull request.
type ChecksStatus ¶
type ChecksStatus struct {
Total int `json:"total"`
Passing int `json:"passing"`
Failing int `json:"failing"`
Pending int `json:"pending"`
Skipped int `json:"skipped"`
}
ChecksStatus tallies a pull request's CI check outcomes.
type DefaultBranchCI ¶
type DefaultBranchCI struct {
Branch string `json:"branch"`
SHA string `json:"sha"`
Workflows []CIWorkflowRun `json:"workflows"`
}
DefaultBranchCI is the CI state of a repo's default branch head: the latest run of each workflow on that commit.
type Job ¶ added in v0.5.0
type Job struct {
StartedAt time.Time `json:"started_at"`
// CompletedAt is the zero time while the job is still running.
CompletedAt time.Time `json:"completed_at"`
Name string `json:"name"`
Status string `json:"status"`
Conclusion string `json:"conclusion"`
Steps []Step `json:"steps"`
ID int64 `json:"id"`
}
Job is one job of a workflow run, with the steps it ran.
type PRActivity ¶
PRActivity is the most recent comment or review on a pull request: the signal for who a pull request is waiting on.
type PRDetail ¶
type PRDetail struct {
CreatedAt time.Time
UpdatedAt time.Time
LatestComment *PRComment
ReviewsURL string
Body string
Author string
Assignees []string
CheckDetails []CheckDetail
Reviewers []string
PullRequest
Deletions int
Comments int
Additions int
}
PRDetail holds the full detail view state for a single pull request.
type PRPreview ¶
type PRPreview struct {
Body string
ReviewDecision string
Reviewers []string
Additions int
Deletions int
}
PRPreview is the little a PRs-tab row needs to show under the table: enough to judge whether the pull request is worth opening, and nothing that costs GitHub a second query to answer.
type PullRequest ¶
type PullRequest struct {
UpdatedAt time.Time `json:"updated_at,omitzero"`
Activity *PRActivity `json:"activity,omitempty"`
HeadRef string `json:"head_ref"`
URL string `json:"url"`
State string `json:"state"`
Mergeable string `json:"mergeable,omitempty"`
Title string `json:"title"`
HeadSHA string `json:"head_sha,omitempty"`
HeadRepoOwner string `json:"head_repo_owner,omitempty"`
BaseRef string `json:"base_ref"`
Author string `json:"author,omitempty"`
ReviewDecision string `json:"review_decision,omitempty"`
Repo string `json:"repo,omitempty"`
ApprovedBy []string `json:"approved_by,omitempty"`
Reviewers []string `json:"reviewers,omitempty"`
Checks ChecksStatus `json:"checks"`
ChangesRequests int `json:"changes_requests,omitempty"`
Number int `json:"number"`
IsDraft bool `json:"is_draft"`
}
PullRequest summarizes a pull request for the repo list and detail views.
func (PullRequest) FromFork ¶
func (p PullRequest) FromFork(owner string) bool
FromFork reports whether the pull request's head branch lives in someone else's fork rather than in owner's own repository. A fork's head ref shares a namespace with local branches ("master" is common), so a name match alone is not evidence the branch is here.
func (PullRequest) HeadLabel ¶
func (p PullRequest) HeadLabel(owner string) string
HeadLabel names where the head branch lives, qualifying it with the owner when the pull request comes from a fork.
func (PullRequest) MatchesUpstream ¶
func (p PullRequest) MatchesUpstream(owner, upstream string) bool
MatchesUpstream reports whether upstream (a branch's "remote/name" tracking ref) points at this pull request's head branch, so a local branch never has to share its name with the head ref to prove it holds the same pull request. A fork's head ref lives in a different remote, so it never matches on upstream alone.
func (PullRequest) NeedsReviewer ¶
func (p PullRequest) NeedsReviewer() bool
NeedsReviewer reports whether an open, non-draft pull request has nobody currently requested to review it, the case GitHub's own reviewDecision leaves unflagged since it only tracks reviews already submitted.
type Step ¶ added in v0.5.0
type Step struct {
StartedAt time.Time `json:"started_at"`
// CompletedAt is the zero time while the step is still running, and
// StartedAt is zero for a step that has not begun.
CompletedAt time.Time `json:"completed_at"`
Name string `json:"name"`
Status string `json:"status"`
Conclusion string `json:"conclusion"`
Number int `json:"number"`
}
Step is one step of a job. Laying steps on a time axis is what the timings are for, so both are reported even while the step is still running.
type WorkflowRun ¶
type WorkflowRun struct {
CreatedAt time.Time
UpdatedAt time.Time
Name string
Status string
Conclusion string
URL string
// HeadBranch is the ref the run was started against, and Event is what
// started it ("workflow_dispatch", "pull_request", "schedule").
HeadBranch string
Event string
// Path is the workflow's file ("ci.yml"), which is what the Actions API
// filters on. A run listed without it leaves this empty.
Path string
ID int64
}
WorkflowRun summarizes a single CI workflow run.
func (WorkflowRun) IsActive ¶ added in v0.5.0
func (r WorkflowRun) IsActive() bool
IsActive reports whether the run has not reached a conclusion yet.
func (WorkflowRun) IsSuccess ¶ added in v0.6.0
func (r WorkflowRun) IsSuccess() bool
IsSuccess reports whether the run finished and passed. A run still going has no conclusion, so a conclusion check alone would read a queued run as failed.
type WorkflowSummary ¶
type WorkflowSummary struct {
Runs []WorkflowRun
Total int
Passing int
Skipped int
Canceled int
Failing int
InProgress int
}
WorkflowSummary aggregates the CI workflow runs for a commit. Every run lands in exactly one of Passing, Skipped, Canceled, Failing, or InProgress, so the five sum to Total.
Source Files
Directories