Documentation
¶
Overview ¶
Package ghclient wraps go-github with token resolution, an 8-way concurrency cap, and in-flight de-duplication/caching for repeated lookups.
Index ¶
- type ActionsPolicy
- type Client
- func (c *Client) ActionsPolicy(owner, repo string) (ActionsPolicy, error)
- func (c *Client) CommitDate(owner, repo, ref string) (time.Time, error)
- func (c *Client) DefaultBranch(owner, repo string) (string, error)
- func (c *Client) ListRunJobs(owner, repo string, runID int64) ([]RunJob, error)
- func (c *Client) ListTags(owner, repo string) ([]string, error)
- func (c *Client) ListWorkflowRuns(owner, repo string, workflowID int64, branch string, since time.Time) ([]WorkflowRun, error)
- func (c *Client) ListWorkflows(owner, repo string) ([]WorkflowMeta, error)
- func (c *Client) RepoBillableMinutes(owner, repo string, year int, month int) (RepoBillableUsage, error)
- func (c *Client) ResolveSha(owner, repo, ref string) (string, error)
- func (c *Client) SetActionsPolicy(owner, repo string, selected SelectedActions, requirePin bool) error
- func (c *Client) WarnIfUnauthenticated()
- func (c *Client) WorkflowBillableMs(owner, repo string, workflowID int64) (map[string]int64, error)
- type RepoBillableUsage
- type RunJob
- type SelectedActions
- type WorkflowMeta
- type WorkflowRun
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ActionsPolicy ¶ added in v1.1.0
type ActionsPolicy struct {
Enabled bool // whether Actions can run at all
AllowedActions string // "all", "local_only", or "selected"
ShaPinningRequired bool // GitHub rejects workflows with non-SHA refs
Selected *SelectedActions
}
ActionsPolicy is a repo's Actions permissions policy.
type Client ¶
type Client struct {
Authenticated bool
// contains filtered or unexported fields
}
Client is a concurrency- and cache-aware GitHub API client.
func New ¶
New constructs a client for the given host, resolving a token if available. host "" or "github.com" uses the public API; any other host is treated as a GitHub Enterprise Server instance (API at https://<host>/api/v3/).
func (*Client) ActionsPolicy ¶ added in v1.1.0
func (c *Client) ActionsPolicy(owner, repo string) (ActionsPolicy, error)
ActionsPolicy fetches the repo's Actions permissions, including the selected-actions allowlist when one is in force. Uses raw requests because go-github v66 predates the sha_pinning_required field.
func (*Client) CommitDate ¶ added in v1.1.0
CommitDate returns the commit date of a tag/branch/sha (cached, deduped).
func (*Client) DefaultBranch ¶
DefaultBranch returns the repo's default branch (e.g. "main").
func (*Client) ListRunJobs ¶
ListRunJobs returns the jobs for one workflow run.
func (*Client) ListWorkflowRuns ¶
func (c *Client) ListWorkflowRuns(owner, repo string, workflowID int64, branch string, since time.Time) ([]WorkflowRun, error)
ListWorkflowRuns returns a workflow's runs created on or after `since`, newest first (server-side filtered via the API's `created` query).
func (*Client) ListWorkflows ¶
func (c *Client) ListWorkflows(owner, repo string) ([]WorkflowMeta, error)
ListWorkflows lists the repo's workflows.
func (*Client) RepoBillableMinutes ¶ added in v1.1.0
func (c *Client) RepoBillableMinutes(owner, repo string, year int, month int) (RepoBillableUsage, error)
RepoBillableMinutes returns the repo's billed GitHub-hosted runner minutes for the given month via the enhanced billing platform's usage report (GET /organizations/{org}/settings/billing/usage). This is the successor to the per-workflow timing endpoint, which always reports empty billable data for owners migrated to the new platform; the report is repo-granular only. Falls back to the user-owner variant when the owner is not an organization.
func (*Client) ResolveSha ¶
ResolveSha resolves a tag/branch/sha to a full commit SHA (cached, deduped).
func (*Client) SetActionsPolicy ¶ added in v1.1.0
func (c *Client) SetActionsPolicy(owner, repo string, selected SelectedActions, requirePin bool) error
SetActionsPolicy applies a selected-actions policy: allowed_actions is set to "selected" and the allowlist written. requirePin additionally turns on SHA pinning enforcement; false leaves the repo's current setting untouched (this never downgrades an already-enabled requirement). A 409 from GitHub usually means an org-level policy pins the repo's settings.
func (*Client) WarnIfUnauthenticated ¶
func (c *Client) WarnIfUnauthenticated()
WarnIfUnauthenticated prints a rate-limit warning to stderr when no token.
func (*Client) WorkflowBillableMs ¶ added in v1.1.0
WorkflowBillableMs returns a workflow's billable GitHub-hosted runner milliseconds for the current billing cycle, keyed by OS ("UBUNTU", "MACOS", "WINDOWS"). The map is empty for public repos, where Actions minutes are free and GitHub reports no billable usage.
type RepoBillableUsage ¶ added in v1.1.0
type RepoBillableUsage struct {
MinutesBySKU map[string]float64 // e.g. "Actions Linux", "Actions Linux 4-core"
NetUSD float64 // amount actually charged after discounts/included minutes
}
RepoBillableUsage is a repo's billed Actions minutes for one calendar month, aggregated from the enhanced billing platform's usage report.
type RunJob ¶
type RunJob struct {
Name string
StartedAt time.Time
HasStarted bool
CompletedAt time.Time
HasCompleted bool
}
RunJob is the subset of a job we need.
type SelectedActions ¶ added in v1.1.0
type SelectedActions struct {
GithubOwnedAllowed bool `json:"github_owned_allowed"`
VerifiedAllowed bool `json:"verified_allowed"`
PatternsAllowed []string `json:"patterns_allowed"`
}
SelectedActions is the allowlist in force when a policy's AllowedActions is "selected".
type WorkflowMeta ¶
WorkflowMeta is the subset of a workflow we need.