actionpins

package
v0.68.4 Latest Latest
Warning

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

 Go to latest Published: Apr 16, 2026 License: MIT Imports: 11 Imported by: 0

README

actionpins Package

GitHub Action pin resolution utilities backed by embedded pin data and optional dynamic SHA resolution.

Overview

The actionpins package resolves uses: references like actions/checkout@v5 to pinned commit SHAs. It loads embedded pin metadata from data/action_pins.json, indexes pins by repository, and exposes helpers for formatting and resolving references.

Resolution supports two modes:

  • Embedded-only lookup from bundled pin data
  • Dynamic lookup via a caller-provided SHAResolver, with fallback behavior controlled by PinContext.StrictMode

Public API

Types
Type Kind Description
ActionYAMLInput struct Input metadata parsed from an Action's action.yml
ActionPin struct Pinned action entry (repo, version, SHA, optional inputs)
ActionPinsData struct JSON container used to load embedded pin entries
SHAResolver interface Resolves a SHA for repo@version dynamically
PinContext struct Runtime context for resolution (resolver, strict mode, warning dedupe map)
Functions
Function Signature Description
GetActionPins func() []ActionPin Returns all loaded pins
GetActionPinsByRepo func(repo string) []ActionPin Returns all pins for a repository (version-descending)
GetActionPinByRepo func(repo string) (ActionPin, bool) Returns the latest pin for a repository
FormatReference func(repo, sha, version string) string Formats a pinned reference (repo@sha # version)
FormatCacheKey func(repo, version string) string Formats a cache key (repo@version)
ExtractRepo func(uses string) string Extracts the repository from a uses reference
ExtractVersion func(uses string) string Extracts the version from a uses reference
GetActionPinWithData func(actionRepo, version string, ctx *PinContext) (string, error) Resolves a pinned reference with optional dynamic SHA lookup and fallback behavior
GetCachedActionPin func(repo string, ctx *PinContext) string Returns a pinned reference preferring cache/dynamic resolution when available

Dependencies

Internal:

  • pkg/console — warning message formatting
  • pkg/logger — debug logging
  • pkg/semverutil — semantic version compatibility checks

Thread Safety

Embedded pin loading and index creation use sync.Once, and read access to loaded pin slices/maps is safe after initialization.

PinContext.Warnings is mutated in place for warning deduplication; callers should not share one PinContext across goroutines without external synchronization.

This specification is automatically maintained by the spec-extractor workflow.

Documentation

Overview

Package actionpins provides action pin resolution for GitHub Actions, mapping repository references to their pinned commit SHAs. It is intentionally free of dependencies on pkg/workflow so it can be imported by any package without introducing import cycles.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ExtractRepo 

func ExtractRepo(uses string) string

ExtractRepo extracts the action repository from a uses string. Examples: "actions/checkout@v5" -> "actions/checkout"

func ExtractVersion 

func ExtractVersion(uses string) string

ExtractVersion extracts the version from a uses string. Examples: "actions/checkout@v5" -> "v5", "actions/checkout" -> ""

func FormatCacheKey 

func FormatCacheKey(repo, version string) string

FormatCacheKey generates a cache key for action resolution. Example: "actions/checkout@v4"

func FormatReference 

func FormatReference(repo, sha, version string) string

FormatReference formats an action reference with repo, SHA, and version comment. Example: "actions/checkout@abc123 # v4.1.0"

func GetActionPinWithData 

func GetActionPinWithData(actionRepo, version string, ctx *PinContext) (string, error)

GetActionPinWithData returns the pinned action reference for a given action@version. It consults ctx.Resolver first, then falls back to embedded pins. If ctx is nil, only embedded pins are consulted.

func GetCachedActionPin 

func GetCachedActionPin(repo string, ctx *PinContext) string

GetCachedActionPin returns the pinned action reference for a given repository, preferring the user's cache (via ctx.Resolver) over the embedded action_pins.json. If ctx is nil, only embedded pins are consulted.

Types

type ActionPin 

type ActionPin struct {
	Repo    string                      `json:"repo"`
	Version string                      `json:"version"`
	SHA     string                      `json:"sha"`
	Inputs  map[string]*ActionYAMLInput `json:"inputs,omitempty"`
}

ActionPin represents a pinned GitHub Action with its commit SHA.

func GetActionPinByRepo 

func GetActionPinByRepo(repo string) (ActionPin, bool)

GetActionPinByRepo returns the latest ActionPin for a given repository, if any.

func GetActionPins 

func GetActionPins() []ActionPin

GetActionPins returns all loaded action pins sorted by version descending.

func GetActionPinsByRepo 

func GetActionPinsByRepo(repo string) []ActionPin

GetActionPinsByRepo returns the sorted (version-descending) list of action pins for the given repository. Returns nil if the repo has no pins.

type ActionPinsData 

type ActionPinsData struct {
	Entries map[string]ActionPin `json:"entries"`
}

ActionPinsData represents the structure of the embedded JSON file.

type ActionYAMLInput 

type ActionYAMLInput struct {
	Description string `yaml:"description,omitempty" json:"description,omitempty"`
	Required    bool   `yaml:"required,omitempty"    json:"required,omitempty"`
	Default     string `yaml:"default,omitempty"     json:"default,omitempty"`
}

ActionYAMLInput holds an input definition parsed from a GitHub Action's action.yml.

type PinContext 

type PinContext struct {
	// Resolver resolves SHAs dynamically via GitHub CLI. May be nil.
	Resolver SHAResolver
	// StrictMode controls how resolution failures are handled.
	StrictMode bool
	// Warnings is a shared map for deduplicating warning messages.
	// Keys are cache keys in the form "repo@version".
	Warnings map[string]bool
}

PinContext provides the runtime context needed for action pin resolution. Callers construct one from their own state (e.g. WorkflowData fields). The Warnings map is mutated in place to deduplicate warning output.

type SHAResolver 

type SHAResolver interface {
	ResolveSHA(repo, version string) (string, error)
}

SHAResolver resolves a GitHub Action's commit SHA for a given version tag.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.