Documentation
¶
Overview ¶
Package actionlookup provides GitHub Action version resolution to SHA hashes.
The package handles: - Resolving tags/branches to full commit SHAs via GitHub API - Caching results with TTL - Handling GitHub authentication - Supporting both public and private repositories - Annotated tag resolution
Key Components:
- Client: Main resolver with configurable HTTP client and caching
- Options: Functional configuration (token, base URL, cache TTL)
Usage Example:
client := actionlookup.NewClient(
actionlookup.WithToken("ghp_..."),
actionlookup.WithCacheTTL(10*time.Minute),
)
sha, err := client.Lookup(context.Background(), "actions/checkout", "v3")
Dependencies: - GitHub API v3 - Standard library net/http for HTTP communication
Index ¶
- func IsSHA(s string) bool
- func SetDefaultClient(opts ...Option)
- type Client
- type FileContentCache
- type Option
- func WithBaseURL(baseURL string) Option
- func WithCacheTTL(ttl time.Duration) Option
- func WithFileCache(cache FileContentCache) Option
- func WithHTTPClient(client *http.Client) Option
- func WithRateLimiter(rateLimiter *RateLimiter) Option
- func WithRetryOptions(count int, delay time.Duration) Option
- func WithToken(token string) Option
- type RateLimiter
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsSHA ¶
IsSHA checks if a string is a valid 40-character Git SHA. Validates length and hexadecimal characters (case-insensitive). Returns true only for exact 40-character SHA-1 hashes.
func SetDefaultClient ¶
func SetDefaultClient(opts ...Option)
SetDefaultClient configures the shared client instance
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client handles resolution of GitHub Action versions to commit SHAs. Provides caching, authentication, and GitHub API communication. Safe for concurrent use by multiple goroutines.
func GetDefaultClient ¶
func GetDefaultClient() *Client
GetDefaultClient returns the singleton instance
func NewClient ¶
NewClient creates a new GitHub Action resolver with optional configuration. Defaults to public GitHub API with 5-minute cache TTL and no authentication. Configure using Option arguments:
NewClient(WithToken("ghp_..."), WithCacheTTL(10*time.Minute))
func (*Client) GetFileContent ¶
GetFileContent fetches the content of a file from a GitHub repository. If ref is empty, the default branch is used.
func (*Client) Lookup ¶
Lookup resolves an action reference to a full SHA hash.
Parameters:
- ctx: Context for cancellation/timeouts
- action: GitHub Action in "owner/repo" format
- version: Tag, branch, or partial SHA (40 chars gets verified)
Returns:
- Full 40-character SHA if found
- Error for invalid formats, missing refs, or API errors
Resolution order: 1. Check cache 2. Try as tag 3. Try as branch 4. Verify SHA exists (if 40 chars)
type FileContentCache ¶
type FileContentCache interface {
// GetFileContent retrieves file content from the cache
// Returns the content, status code, and whether it was found in cache
GetFileContent(owner, repo, path, sha string) (string, int, bool)
// SetFileContent stores file content in the cache
// The statusCode parameter allows caching of 404 responses
SetFileContent(owner, repo, path, sha string, content string, statusCode int)
}
FileContentCache defines the interface for caching file content
type Option ¶
type Option func(*Client)
Option defines configuration functions for the Client.
func WithBaseURL ¶
WithBaseURL configures an alternative GitHub API endpoint. Useful for GitHub Enterprise deployments or testing. Example: "https://github.example.com/api/v3"
func WithCacheTTL ¶
WithCacheTTL sets the duration for cached SHA resolutions. Default: 5 minutes. Set to 0 to disable caching.
func WithFileCache ¶
func WithFileCache(cache FileContentCache) Option
WithFileCache sets the persistent cache for file content.
func WithHTTPClient ¶
WithHTTPClient provides a custom HTTP client implementation. Use this to configure timeouts, proxies, or custom transport:
&http.Client{Timeout: 30 * time.Second}
func WithRateLimiter ¶
func WithRateLimiter(rateLimiter *RateLimiter) Option
WithRateLimiter configures a custom rate limiter.
func WithRetryOptions ¶
WithRetryOptions configures retry behavior for transient errors.
type RateLimiter ¶
type RateLimiter struct {
// contains filtered or unexported fields
}
RateLimiter implements rate limiting for GitHub API requests.
func NewRateLimiter ¶
func NewRateLimiter(requestsPerHour int, client *http.Client) *RateLimiter
NewRateLimiter creates a new rate limiter with the specified requests per hour limit.
func (*RateLimiter) GetRemainingRequests ¶
func (r *RateLimiter) GetRemainingRequests() int
GetRemainingRequests returns the number of remaining requests.
func (*RateLimiter) GetResetTime ¶
func (r *RateLimiter) GetResetTime() time.Time
GetResetTime returns the time when the rate limit will reset.
Source Files