Actions Resource Toolkit

Build a Go utility layer that inspects GitHub Actions resources for a repository and performs limited administration tasks around runners, caches, artifacts, and OIDC subject templates.

Capabilities

Runner snapshot

• Given an owner and repository, fetches all self-hosted runners (handling pagination) and returns counts of online/offline/busy plus a map of label frequencies. An optional label filter restricts runners counted to those containing the label and counts are derived from the runner status fields. @test
• If no runners match the filter, returns zero counts and an empty label map without error. @test

Cache cleanup

• Returns cache usage entries sorted by descending size and flags caches with keys starting with a prefix that were last accessed before a cutoff time; when not in dry-run mode, deletes flagged caches and marks them as deleted while leaving other entries untouched. @test

Artifact download

• Finds the latest successful workflow run for a given workflow file name, locates an artifact by name from that run, and streams the archive contents to a provided writer, following any redirect URL; if no run or artifact is found, returns a descriptive error without writing. @test

OIDC subject template

• Reads the repository OIDC subject-claim template, ensures a required claim key (for example an environment identifier) is included, persists the change, and reports whether an update happened. No update occurs if the template already contains the key. @test

Implementation

@generates

API

type ActionsToolkit struct {
    // holds authenticated GitHub client and base URLs
}

func NewActionsToolkit(httpClient *http.Client, apiBaseURL, uploadBaseURL, token string) (*ActionsToolkit, error)

type RunnerSummary struct {
    Online int
    Offline int
    Busy int
    LabelCounts map[string]int
}

func (t *ActionsToolkit) RunnerSnapshot(ctx context.Context, owner, repo, label string) (*RunnerSummary, error)

type CacheEntry struct {
    Key string
    Ref string
    SizeBytes int64
    LastAccessed time.Time
    Deleted bool
}

type CacheReport struct {
    TotalBytes int64
    Entries []CacheEntry
}

func (t *ActionsToolkit) CleanupCaches(ctx context.Context, owner, repo, keyPrefix string, cutoff time.Time, dryRun bool) (*CacheReport, error)

func (t *ActionsToolkit) DownloadArtifactByName(ctx context.Context, owner, repo, workflowFile, artifactName string, dest io.Writer) error

func (t *ActionsToolkit) EnsureOIDCTemplateClaim(ctx context.Context, owner, repo, requiredClaim string) (claims []string, changed bool, err error)

Dependencies { .dependencies }

github.com/google/go-github/v80/github { .dependency }

Typed GitHub REST v3 client for Actions runners, caches, OIDC templates, and artifact redirects.