health

package
v0.18.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 7, 2026 License: MIT Imports: 9 Imported by: 0

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

View Source
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.

View Source
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.

View Source
const DefaultConcurrency = 4

DefaultConcurrency is the number of repositories collected at once by CollectAll when Options.Concurrency is zero.

View Source
const DefaultRunsPerPage = 100

DefaultRunsPerPage is the number of recent runs fetched per repository. It is GitHub's maximum page size.

View Source
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.

func Collect

func Collect(ctx context.Context, client clientv1.Client, owner, name string, opts *Options) (*RepoHealth, error)

Collect gathers the health 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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL