Documentation
¶
Index ¶
- Constants
- func BuildLabels(name string, labels []string) []scaleset.Label
- func NewLogger(level, format string) *slog.Logger
- func NewScaleSetLogger(level, format string, name string, index int) *slog.Logger
- func NewScalesetClient(registrationURL, token string, logger *slog.Logger) (*scaleset.Client, error)
- func NewSystemInfo(scaleSetID int, version string) scaleset.SystemInfo
- type Config
- type DockerConfig
- type ScaleSetConfig
- type TartConfig
Constants ¶
const ( DefaultBackend = "docker" DefaultMaxRunners = 10 DefaultRunnerImage = "ghcr.io/actions/actions-runner:latest" DefaultRunnerGroup = "default" DefaultDockerSocket = "/var/run/docker.sock" DefaultDinD = true DefaultTartRunnerDir = "/Users/admin/actions-runner" DefaultLogLevel = "info" DefaultLogFormat = "text" DefaultHealthPort = 8080 DefaultSystemName = "dockerscaleset" // TTL sweeps when SharedVolumeTTL > 0 and no explicit interval is set. DefaultSharedVolumeCleanupInterval = 6 * time.Hour // DefaultTartCacheCleanup enables Tart OCI/IPSW cache cleanup by default. // It acts as a safety net: every `tart pull` accumulates layers under // $TART_HOME/cache/, and rolling tags (e.g. :latest) combined with 50–80GB // macOS images can fill the disk within a few updates. The sweep only // touches caches, never local VMs, so it is safe to leave on. DefaultTartCacheCleanup = true // DefaultTartCacheMaxAge removes cache entries not accessed within this // window. Old layers left behind by an image update stop being accessed and // age out naturally. Generous so an image still in active use is never // evicted. `tart prune` granularity is whole days; sub-day values floor // to 1 day. DefaultTartCacheMaxAge = 7 * 24 * time.Hour // DefaultTartCacheCleanupInterval is the period between `tart prune` sweeps // when cache cleanup is enabled and no explicit interval is set. DefaultTartCacheCleanupInterval = 24 * time.Hour // DefaultBuildxCleanup enables orphaned buildx builder cleanup by default. // It acts as a safety net: `docker buildx create` builders (e.g. from // docker/setup-buildx-action) leak on persistent hosts sharing one daemon, // each keeping a multi-GB state volume, and most users never notice. DefaultBuildxCleanup = true // DefaultBuildxCleanupTTL removes buildx builders older than this. It is // deliberately generous — well beyond any realistic build — so a sweep // never disrupts an in-progress build. DefaultBuildxCleanupTTL = 24 * time.Hour // DefaultBuildxCleanupInterval is the period between buildx cleanup sweeps. DefaultBuildxCleanupInterval = 6 * time.Hour )
Default values for configuration fields. All flag definitions, config templates, and fallback logic should reference these constants instead of hardcoding values.
Variables ¶
This section is empty.
Functions ¶
func BuildLabels ¶ added in v0.2.3
BuildLabels converts string labels to scaleset.Label slice. If no labels are provided, uses the scale set name as default.
func NewLogger ¶ added in v0.2.3
NewLogger creates a structured logger with the given level and format, and sets it as the process-wide default.
func NewScaleSetLogger ¶ added in v0.2.4
NewScaleSetLogger creates a logger with a colored prefix for the given scale set. The color is determined by the index, cycling through the palette.
func NewScalesetClient ¶ added in v0.2.3
func NewScalesetClient(registrationURL, token string, logger *slog.Logger) (*scaleset.Client, error)
NewScalesetClient creates a scaleset.Client using PAT authentication.
func NewSystemInfo ¶ added in v0.2.3
func NewSystemInfo(scaleSetID int, version string) scaleset.SystemInfo
NewSystemInfo returns metadata for the scaleset client user agent.
Types ¶
type Config ¶
type Config struct {
// Global settings (not inherited by scale sets)
LogLevel string `mapstructure:"log-level"`
LogFormat string `mapstructure:"log-format"`
HealthPort int `mapstructure:"health-port"`
DryRun bool `mapstructure:"dry-run"`
// Default values for scale sets + single-mode fields.
// Squashed so TOML keys (url, name, backend, etc.) stay at the top level.
Defaults ScaleSetConfig `mapstructure:",squash"`
// Multi-scaleset mode: each entry inherits from Defaults.
ScaleSets []ScaleSetConfig `mapstructure:"scaleset"`
}
Config holds the complete runner configuration.
Global-only fields (LogLevel, LogFormat, HealthPort, DryRun) are never inherited by scale sets. The Defaults field is squashed so its keys appear at the TOML top level; it doubles as the single-mode config when no [scaleset] entries exist.
func (*Config) ResolveScaleSets ¶
func (c *Config) ResolveScaleSets() []ScaleSetConfig
ResolveScaleSets returns the resolved list of scale set configs. If [scaleset] entries exist, each inherits unset fields from Defaults. Otherwise, Defaults itself is returned as a single-element slice.
type DockerConfig ¶ added in v0.2.3
type DockerConfig struct {
Socket string `mapstructure:"socket"`
DinD *bool `mapstructure:"dind"` // pointer: nil = inherit default (true)
Memory int `mapstructure:"memory"` // Memory limit in MB (0 = unlimited)
CPU int `mapstructure:"cpu"` // CPU cores (0 = unlimited)
Platform string `mapstructure:"platform"` // e.g. "linux/amd64" to force architecture
// 0 (default) disables TTL cleanup. Accepts Go duration strings, e.g. "168h".
SharedVolumeTTL time.Duration `mapstructure:"shared-volume-ttl"`
// runner is up. Ignored when SharedVolumeTTL is 0. Defaults to
// DefaultSharedVolumeCleanupInterval when unset.
SharedVolumeCleanupInterval time.Duration `mapstructure:"shared-volume-cleanup-interval"`
// BuildxCleanup enables automatic removal of orphaned buildx BuildKit
// builder containers and their state volumes. Pointer: nil = inherit
// default (true). Disable (false) only if you run a persistent builder
// via `keep-state` + a fixed builder name, which this sweep would reclaim.
BuildxCleanup *bool `mapstructure:"buildx-cleanup"`
// BuildxCleanupTTL removes buildx builders older than this duration.
// Defaults to DefaultBuildxCleanupTTL when unset. Set generously above
// your longest build so in-progress builds are never disrupted.
BuildxCleanupTTL time.Duration `mapstructure:"buildx-cleanup-ttl"`
// BuildxCleanupInterval is how often the buildx cleanup sweep runs while
// runner is up. Defaults to DefaultBuildxCleanupInterval when unset.
BuildxCleanupInterval time.Duration `mapstructure:"buildx-cleanup-interval"`
}
DockerConfig holds Docker-specific backend settings.
type ScaleSetConfig ¶
type ScaleSetConfig struct {
RegistrationURL string `mapstructure:"url"`
ScaleSetName string `mapstructure:"name"`
Token string `mapstructure:"token"`
MaxRunners int `mapstructure:"max-runners"`
MinRunners int `mapstructure:"min-runners"`
Labels []string `mapstructure:"labels"`
RunnerGroup string `mapstructure:"runner-group"`
RunnerImage string `mapstructure:"runner-image"`
Backend string `mapstructure:"backend"`
// Docker backend settings
Docker DockerConfig `mapstructure:"docker"`
// Tart VM backend settings
Tart TartConfig `mapstructure:"tart"`
}
ScaleSetConfig holds per-scale-set configuration. In multi-mode, fields left at their zero value inherit from Config.Defaults.
func (*ScaleSetConfig) IsBuildxCleanupEnabled ¶ added in v0.2.23
func (ss *ScaleSetConfig) IsBuildxCleanupEnabled() bool
IsBuildxCleanupEnabled reports whether orphaned buildx builder cleanup is enabled (default true unless explicitly disabled).
func (*ScaleSetConfig) IsDinD ¶
func (ss *ScaleSetConfig) IsDinD() bool
IsDinD returns whether Docker-in-Docker is enabled for this scale set.
func (*ScaleSetConfig) IsTart ¶
func (ss *ScaleSetConfig) IsTart() bool
IsTart returns whether this scale set uses the Tart VM backend.
func (*ScaleSetConfig) IsTartCacheCleanupEnabled ¶ added in v0.2.24
func (ss *ScaleSetConfig) IsTartCacheCleanupEnabled() bool
IsTartCacheCleanupEnabled reports whether Tart OCI/IPSW cache cleanup is enabled (default true unless explicitly disabled).
func (*ScaleSetConfig) Validate ¶
func (ss *ScaleSetConfig) Validate() error
Validate checks required fields and logical constraints for a scale set.
type TartConfig ¶ added in v0.2.3
type TartConfig struct {
Home string `mapstructure:"home"` // TART_HOME for tart CLI ("" = default ~/.tart)
RunnerDir string `mapstructure:"runner-dir"` // Runner binary path in VM
CPU int `mapstructure:"cpu"` // Number of CPU cores (0 = use image default)
Memory int `mapstructure:"memory"` // Memory in MB (0 = use image default)
PoolSize int `mapstructure:"pool-size"` // Pre-warmed VM count (0 = disabled)
// CacheCleanup enables periodic `tart prune` of the OCI/IPSW caches under
// TART_HOME. Pointer: nil = inherit default (true). Local VMs are never
// touched. Disable (false) only if you manage the cache yourself.
CacheCleanup *bool `mapstructure:"cache-cleanup"`
// CacheMaxAge removes cache entries not accessed within this window via
// `tart prune --older-than`. Defaults to DefaultTartCacheMaxAge when unset.
// Granularity is whole days; sub-day values floor to 1 day.
CacheMaxAge time.Duration `mapstructure:"cache-max-age"`
// CacheSpaceBudgetGB is an optional hard cap on the OCI/IPSW cache size
// (in GB), enforced via `tart prune --space-budget` on top of the age-based
// sweep — least-recently-used entries are removed until the total fits.
// 0 (default) means no size cap (age-based cleanup still runs).
CacheSpaceBudgetGB int `mapstructure:"cache-space-budget"`
// CacheCleanupInterval is how often the prune sweep runs while runner
// is up. Ignored when cache cleanup is disabled. Defaults to
// DefaultTartCacheCleanupInterval when unset.
CacheCleanupInterval time.Duration `mapstructure:"cache-cleanup-interval"`
}
TartConfig holds Tart VM-specific backend settings.