Documentation
¶
Overview ¶
Package health summarizes the state of repositories: open issue and pull request counts, and the latest run of every GitHub Actions workflow.
It is designed for collecting the same information across a set of repositories with one token, so it minimizes API calls. Collecting one repository takes four requests regardless of how many pull requests or workflows it has: the repository, a pull request count, the workflow list, and one page of recent runs across all workflows. A further request is made only for an active workflow whose latest run is not on that page.
Index ¶
Constants ¶
const ( RunStatusCompleted = "completed" ConclusionSuccess = "success" ConclusionFailure = "failure" ConclusionTimedOut = "timed_out" ConclusionStartupFailure = "startup_failure" ConclusionActionRequired = "action_required" ConclusionStale = "stale" ConclusionCancelled = "cancelled" ConclusionSkipped = "skipped" ConclusionNeutral = "neutral" )
GitHub Actions run status and conclusion values used to derive a State.
const ( WorkflowPathPrefix = ".github/workflows/" DynamicWorkflowPathPrefix = "dynamic/" )
Workflow path prefixes. Workflows defined in the repository live under WorkflowPathPrefix; GitHub's own (Dependabot, Pages) are reported under DynamicWorkflowPathPrefix.
const DefaultConcurrency = 4
DefaultConcurrency is the number of repositories collected at once by CollectAll when Options.Concurrency is zero.
const DefaultRunsPerPage = 100
DefaultRunsPerPage is the number of recent runs fetched per repository. It is GitHub's maximum page size.
const WorkflowStateActive = "active"
WorkflowStateActive is the Workflow.State of a workflow that can run. Other values ("disabled_manually", "disabled_inactivity") mark workflows that are listed but excluded from a repository's overall State.
Variables ¶
This section is empty.
Functions ¶
func RunsURL ¶
func RunsURL(repository *gogithub.Repository, workflow *gogithub.Workflow) string
RunsURL returns the GitHub page listing all runs of a workflow, which the API does not provide. It is derived from the repository's HTMLURL and the workflow path, e.g. https://github.com/owner/name/actions/workflows/ci.yml for ".github/workflows/ci.yml" and https://github.com/owner/name/actions/workflows/pages/pages-build-deployment for "dynamic/pages/pages-build-deployment". It returns "" when either input is missing.
Types ¶
type Options ¶
type Options struct {
// Branch selects the branch whose workflow runs are evaluated. Empty
// means the repository's default branch.
Branch string
// AnyBranch evaluates the latest run of each workflow regardless of
// branch, ignoring Branch. Use it to see workflows triggered by tags or
// releases, whose runs are not associated with a branch.
AnyBranch bool
// Concurrency is the number of repositories CollectAll processes at
// once. Default: DefaultConcurrency.
Concurrency int
// RunsPerPage is how many recent runs to fetch per repository. Default:
// DefaultRunsPerPage. A workflow whose latest run is older than the page
// costs one extra request.
RunsPerPage int
}
Options configures collection.
type RepoHealth ¶
type RepoHealth struct {
Repository *gogithub.Repository
// OpenIssues is the number of open issues, excluding pull requests.
OpenIssues int
// OpenPullRequests is the number of open pull requests.
OpenPullRequests int
// Branch is the branch whose runs were evaluated; empty when
// Options.AnyBranch was set.
Branch string
// Workflows lists every workflow defined in the repository, active or
// not, in the order GitHub returns them.
Workflows []WorkflowHealth
// State summarizes the active workflows: failing if any fails, else
// running if any is running, else passing if any passed, else
// inconclusive if any completed, else none.
State State
}
RepoHealth is the collected state of one repository.
type Result ¶
type Result struct {
// FullName is the "owner/name" given to CollectAll.
FullName string
// Health is nil when Err is set.
Health *RepoHealth
Err error
}
Result pairs a repository name with its collected health or the error that prevented collection.
func CollectAll ¶
func CollectAll(ctx context.Context, client clientv1.Client, fullNames []string, opts *Options) ([]Result, error)
CollectAll gathers the health of several repositories, given as "owner/name", collecting opts.Concurrency repositories at a time. Results are in input order. A repository that cannot be collected has Result.Err set and does not stop the others; the returned error joins every per-repository error, so callers that want partial results should use the results even when err is non-nil.
type State ¶
type State string
State summarizes a workflow's latest run, or a repository's workflows as a whole.
const ( // StatePassing means the latest run completed successfully. StatePassing State = "passing" // StateFailing means the latest run completed unsuccessfully, including // timeouts, startup failures, and runs that need action. StateFailing State = "failing" // StateRunning means the latest run has not completed. StateRunning State = "running" // StateInconclusive means the latest run completed without a pass or // fail outcome: cancelled, skipped, neutral, or an unrecognized // conclusion. StateInconclusive State = "inconclusive" // StateNone means there is no run to evaluate. StateNone State = "none" )
func OverallState ¶
func OverallState(workflows []WorkflowHealth) State
OverallState combines workflow states by severity: failing, running, passing, inconclusive, none. Workflows that are not active are ignored.
func RunState ¶
func RunState(run *gogithub.WorkflowRun) State
RunState derives the State of a single run. A nil run is StateNone.
type WorkflowHealth ¶
type WorkflowHealth struct {
Workflow *gogithub.Workflow
// LatestRun is nil when the workflow has no run on the evaluated branch.
LatestRun *gogithub.WorkflowRun
State State
}
WorkflowHealth is the latest run of one workflow.