actionpins

package
v0.69.1 Latest Latest
Warning

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

 Go to latest Published: Apr 21, 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
ResolveActionPin func(actionRepo, version string, ctx *PinContext) (string, error) Resolves a pinned reference with optional dynamic SHA lookup and fallback behavior
ResolveLatestActionPin func(repo string, ctx *PinContext) string Resolves a pinned reference for the latest known version, preferring cache/dynamic resolution when available

Usage Example

ctx := &actionpins.PinContext{StrictMode: true}

reference, err := actionpins.ResolveActionPin("actions/checkout", "v5", ctx)
if err != nil {
	panic(err)
}

fmt.Println(reference) // actions/checkout@<sha> # v5

Dependencies

Internal:

  • pkg/console — warning message formatting
  • pkg/gitutil — dynamic SHA resolution via GitHub API/CLI helpers
  • 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 ResolveActionPin added in v0.68.5 

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

ResolveActionPin 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 ResolveLatestActionPin added in v0.69.0 

func ResolveLatestActionPin(repo string, ctx *PinContext) string

ResolveLatestActionPin 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 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
	// EnforcePinned requires unresolved refs to fail unless AllowActionRefs is true.
	EnforcePinned bool
	// AllowActionRefs lowers unresolved pinning failures to warnings.
	// When false, unresolved action refs return an error.
	AllowActionRefs bool
	// Warnings is a shared map for deduplicating warning messages.
	// Keys are cache keys in the form "repo@version".
	Warnings map[string]bool
	// RecordResolutionFailure receives unresolved pinning failures for auditing.
	RecordResolutionFailure func(f ResolutionFailure)
}

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 ResolutionErrorType added in v0.69.1 

type ResolutionErrorType string

ResolutionErrorType classifies unresolved action-ref pinning outcomes for auditing. 

const (
	// ResolutionErrorTypeDynamicResolutionFailed indicates dynamic tag/ref -> SHA resolution failed.
	ResolutionErrorTypeDynamicResolutionFailed ResolutionErrorType = "dynamic_resolution_failed"
	// ResolutionErrorTypePinNotFound indicates no usable hardcoded pin was found for the ref.
	ResolutionErrorTypePinNotFound ResolutionErrorType = "pin_not_found"
)

type ResolutionFailure added in v0.69.1 

type ResolutionFailure struct {
	Repo      string
	Ref       string
	ErrorType ResolutionErrorType
}

ResolutionFailure captures an unresolved action-ref pinning event.

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.