Documentation
¶
Index ¶
- Constants
- func BuildLabels(name string, labels []string) []scaleset.Label
- func DrainTimeoutOrDefault(configured *time.Duration) time.Duration
- func NewLogger(level, format string) *slog.Logger
- func NewLoggerWithWriter(level, format string, console *os.File, file io.Writer) *slog.Logger
- func NewScaleSetLoggerWithWriter(level, format string, name string, index int, console *os.File, file io.Writer) *slog.Logger
- func NewSystemInfo(scaleSetID int, version string) scaleset.SystemInfo
- type ActionsCacheConfig
- func (c ActionsCacheConfig) EffectiveJWKSURL() string
- func (c ActionsCacheConfig) EffectiveMaxIdleDays() int
- func (c ActionsCacheConfig) EffectiveTokenIssuer() string
- func (c ActionsCacheConfig) EffectiveUpstreamResultsURL() string
- func (c ActionsCacheConfig) Validate(healthPort int) error
- func (c ActionsCacheConfig) ValidationErrors(healthPort int) []error
- type CacheVolumeMount
- type CacheVolumeSpec
- type Config
- func (c *Config) EffectiveConcurrent(scaleSets []ScaleSetConfig) int
- func (c *Config) EffectiveDrainTimeout() time.Duration
- func (c *Config) GlobalValidationErrors() []error
- func (c *Config) IsDiskGuardEnabled() bool
- func (c *Config) ResolveScaleSets() []ScaleSetConfig
- func (c *Config) ValidateConcurrent(scaleSets []ScaleSetConfig) error
- func (c *Config) ValidateGlobal() error
- type DiagnosticsConfig
- type DiskConfig
- type DiskGuardSettings
- type DockerConfig
- type GitHubAppConfig
- type LogFileWriter
- type RetryConfig
- type ScaleSetConfig
- func (ss *ScaleSetConfig) DockerBuildCacheMaxAge() time.Duration
- func (ss *ScaleSetConfig) DockerBuildxCleanupInterval() time.Duration
- func (ss *ScaleSetConfig) DockerBuildxCleanupTTL() time.Duration
- func (ss *ScaleSetConfig) DockerPruneInterval() time.Duration
- func (ss *ScaleSetConfig) DockerPruneTTL() time.Duration
- func (ss *ScaleSetConfig) DockerReadyTimeout() time.Duration
- func (ss *ScaleSetConfig) DockerSharedVolumeCleanupInterval() time.Duration
- func (ss *ScaleSetConfig) EffectiveRetry() RetryConfig
- func (ss *ScaleSetConfig) IsBuildxCleanupEnabled() bool
- func (ss *ScaleSetConfig) IsDinD() bool
- func (ss *ScaleSetConfig) IsDockerPruneEnabled() bool
- func (ss *ScaleSetConfig) IsDockerReadinessEnabled() bool
- func (ss *ScaleSetConfig) IsTart() bool
- func (ss *ScaleSetConfig) IsTartCacheCleanupEnabled() bool
- func (ss *ScaleSetConfig) IsUpdateDisabled() bool
- func (ss *ScaleSetConfig) NewScalesetClient(logger *slog.Logger, options ...scaleset.HTTPOption) (*scaleset.Client, error)
- func (ss *ScaleSetConfig) SharedVolumeName() string
- func (ss *ScaleSetConfig) TartCacheCleanupInterval() time.Duration
- func (ss *ScaleSetConfig) TartCacheMaxAge() time.Duration
- func (ss *ScaleSetConfig) Validate() error
- func (ss *ScaleSetConfig) ValidationErrors() []error
- type TartConfig
Constants ¶
const ( DefaultActionsTokenIssuer = "https://token.actions.githubusercontent.com" DefaultActionsJWKSURL = "https://token.actions.githubusercontent.com/.well-known/jwks" DefaultResultsUpstreamURL = "https://results-receiver.actions.githubusercontent.com" )
const ( DefaultProvider = "docker" DefaultMaxRunners = 10 DefaultRunnerImage = "ghcr.io/actions/actions-runner:latest" DefaultRunnerGroup = "default" DefaultDockerSocket = "/var/run/docker.sock" DefaultDinD = true DefaultTartRunnerDir = "/Users/admin/actions-runner" DefaultTartLinuxRunnerDir = "/home/admin/actions-runner" DefaultLogLevel = "info" DefaultLogFormat = "text" DefaultHealthPort = 8080 DefaultHealthAddress = "127.0.0.1" DefaultSystemName = "dockerscaleset" // DefaultDrainTimeout covers the longest jobs currently run on these // hosts while matching GitLab Runner's documented two-hour graceful-stop // budget. Service-manager stop timeouts add a separate one-minute margin. DefaultDrainTimeout = 2 * time.Hour // shared-volume mount when docker.shared-volume-name is unset. DefaultSharedVolumeName = "runner-shared" // cleanup sweeps when SharedVolumeMaxAge > 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 // DefaultDisableUpdate keeps GitHub from updating the runner binary inside // the container or VM. True matches the image-based model: the runner is // refreshed by rebuilding the image, and ephemeral runners avoid // downloading an update on every job. Allowing updates cannot save an // image whose runner version GitHub has retired (see DisableUpdate). DefaultDisableUpdate = true // DefaultBuildxCleanup is disabled because buildx builders are daemon-global // and may belong to workloads outside runner. Dedicated daemons can opt in. DefaultBuildxCleanup = false // DefaultDockerPrune is disabled because pruning acts on the entire daemon, // including objects not created by runner. Operators with a dedicated // runner daemon can opt in explicitly. DefaultDockerPrune = false // DefaultDockerPruneInterval is the period between Docker runtime prune // sweeps when the prune is enabled and no explicit interval is set. DefaultDockerPruneInterval = 6 * time.Hour // DefaultDockerPruneTTL removes stopped containers and dangling images // older than this. It is deliberately generous — well beyond any realistic // job — so intermediates of an in-progress build are never disrupted. DefaultDockerPruneTTL = 24 * time.Hour // DefaultDockerBuildCacheMaxAge prunes daemon build cache entries not used // within this window. Cache still hit by recurring builds keeps refreshing // its last-used time and survives; only abandoned entries age out. DefaultDockerBuildCacheMaxAge = 7 * 24 * time.Hour // 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 // DefaultDiskGuard enables the disk guard by default. Safe to leave on // because its tier ladder only acts under real disk pressure (a // filesystem below min-free) and its budget pass only touches stores the // operator gave an explicit budget — it is not a routine sweeper running // on a timer regardless of need. It deliberately does NOT respect a // store's own Enabled(), which gates only that store's routine cleanup // (prune/buildx-cleanup default off and max-tier defaults to 3, so a // guard that honored Enabled() would ship // unable to reclaim anything). A host whose disk runner does not own // opts out with `[disk] guard = false`, not by disabling individual // stores. DefaultDiskGuard = true // DefaultDiskMinFree is the free-space level that triggers reclamation. DefaultDiskMinFree = "10%" // DefaultDiskTargetFree is the level reclamation aims to restore. DefaultDiskTargetFree = "20%" // DefaultDiskGuardInterval is the period between guard sweeps. DefaultDiskGuardInterval = time.Hour // DefaultDiskMaxTier stops short of wiping cache volumes — that makes // the next build cold, so it requires an explicit opt-in. DefaultDiskMaxTier = 3 // Startup retries: the first failed start waits 2.5–5s, doubling up to // DefaultRetryMax, and the fifth consecutive failure enters a // five-minute cooldown. See RetryConfig. DefaultRetryInitial = 5 * time.Second DefaultRetryMax = time.Minute DefaultRetryCooldownAfter = 5 DefaultRetryCooldown = 5 * time.Minute // DefaultReadyTimeout bounds how long a new runner may take to report // "Listening for Jobs" before its start counts as failed. DefaultReadyTimeout = 5 * time.Minute )
Default values for configuration fields. All flag definitions, config templates, and fallback logic should reference these constants instead of hardcoding values.
const (
DefaultLogMaxSize = int64(10 * 1024 * 1024)
)
const MaxMacOSVMsPerHost = 2
MaxMacOSVMsPerHost is Apple's limit on concurrently running macOS guests per host. Linux Tart guests do not consume this limit.
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 DrainTimeoutOrDefault ¶ added in v0.14.0
DrainTimeoutOrDefault applies the drain-timeout default to a configured value: nil inherits DefaultDrainTimeout; zero or a negative duration is kept, since it explicitly disables draining.
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 NewLoggerWithWriter ¶ added in v0.4.0
NewLoggerWithWriter creates a process logger writing to console and, when file is non-nil, teeing to it. The writer may be shared with scale-set loggers.
func NewScaleSetLoggerWithWriter ¶ added in v0.4.0
func NewScaleSetLoggerWithWriter(level, format string, name string, index int, console *os.File, file io.Writer) *slog.Logger
NewScaleSetLoggerWithWriter creates a scale-set logger writing to console and, when file is non-nil, teeing to it. The writer may be shared with the process logger. The prefix color comes from index, cycling through scaleSetColors.
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 ActionsCacheConfig ¶ added in v0.18.0
type ActionsCacheConfig struct {
Enabled bool `mapstructure:"enabled"`
ListenAddress string `mapstructure:"listen-address"`
AdvertiseURL string `mapstructure:"advertise-url"`
DataDir string `mapstructure:"data-dir"`
MaxSizeBytes int64 `mapstructure:"max-size-bytes"`
MaxIdleDays int `mapstructure:"max-idle-days"`
TokenIssuer string `mapstructure:"token-issuer"`
JWKSURL string `mapstructure:"jwks-url"`
Audiences []string `mapstructure:"audiences"`
UpstreamResultsURL string `mapstructure:"upstream-results-url"`
}
ActionsCacheConfig opts the manager into a private, host-local v2 receiver.
func (ActionsCacheConfig) EffectiveJWKSURL ¶ added in v0.18.0
func (c ActionsCacheConfig) EffectiveJWKSURL() string
func (ActionsCacheConfig) EffectiveMaxIdleDays ¶ added in v0.18.0
func (c ActionsCacheConfig) EffectiveMaxIdleDays() int
func (ActionsCacheConfig) EffectiveTokenIssuer ¶ added in v0.18.0
func (c ActionsCacheConfig) EffectiveTokenIssuer() string
func (ActionsCacheConfig) EffectiveUpstreamResultsURL ¶ added in v0.18.0
func (c ActionsCacheConfig) EffectiveUpstreamResultsURL() string
func (ActionsCacheConfig) Validate ¶ added in v0.18.0
func (c ActionsCacheConfig) Validate(healthPort int) error
func (ActionsCacheConfig) ValidationErrors ¶ added in v0.21.0
func (c ActionsCacheConfig) ValidationErrors(healthPort int) []error
ValidationErrors reports independent cache configuration problems in runtime check order. Validate keeps returning the first for startup.
type CacheVolumeMount ¶ added in v0.3.0
CacheVolumeMount is one resolved cache-volumes entry — merged from the short and long forms by ParseCacheVolumes — naming a Docker volume, the absolute container path it mounts at, and its optional retention budget. BudgetBytes 0 means no budget is configured (every short-form entry, and a long-form entry whose Budget is ""); OnExceed only matters when BudgetBytes != 0.
type CacheVolumeSpec ¶ added in v0.5.0
type CacheVolumeSpec struct {
Name string `mapstructure:"name"`
Path string `mapstructure:"path"`
Budget string `mapstructure:"budget"`
OnExceed string `mapstructure:"on-exceed"`
}
CacheVolumeSpec is one [[docker.cache]] long-form cache-volume entry: like a CacheVolumes short-form "name:/path" string, plus an optional retention budget. See ParseCacheVolumes for how it merges with the short form and what each field validates to.
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"`
HealthAddress string `mapstructure:"health-address"`
DryRun bool `mapstructure:"dry-run"`
LogFile *string `mapstructure:"log-file"`
// Concurrent is the GitLab Runner-style process-wide instance limit. Zero
// automatically uses the sum of resolved scale-set max-runners values.
Concurrent int `mapstructure:"concurrent"`
// DrainTimeout is a pointer so an omitted value can inherit the two-hour
// default while an explicit "0s" can disable draining.
DrainTimeout *time.Duration `mapstructure:"drain-timeout"`
// Default values for scale sets + single-mode fields.
// Squashed so TOML keys (url, name, provider, etc.) stay at the top level.
Defaults ScaleSetConfig `mapstructure:",squash"`
// Disk configures the periodic disk-pressure guard (see DiskConfig).
// Global like the fields above: one guard watches every scale set's
// stores host-wide, grouped by filesystem rather than by scale set.
Disk DiskConfig `mapstructure:"disk"`
Diagnostics DiagnosticsConfig `mapstructure:"diagnostics"`
ActionsCache ActionsCacheConfig `mapstructure:"actions-cache"`
// Multi-scaleset mode: entries as produced by Load, with map-level
// inheritance from the top-level defaults already applied.
ScaleSets []ScaleSetConfig `mapstructure:"scaleset"`
// Warnings carries non-fatal load diagnostics (unknown config keys,
// single-mode keys mixed with [[scaleset]] entries) surfaced by callers:
// `runner run` logs them, `runner validate` fails on them.
Warnings []string `mapstructure:"-"`
// Deprecations are advisory. They never make validation or service
// installation fail while older configurations remain supported.
Deprecations []string `mapstructure:"-"`
}
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 Load ¶ added in v0.3.0
Load builds a Config from the given viper instance. Inheritance for [scaleset] entries happens here at the map level: a key present in a scaleset entry always wins, even when set to a zero value (e.g. `memory = 0` or `dind = false` override a non-zero default).
Unknown keys and mixed single/multi-mode keys go into Config.Warnings; validation treats them as errors while older deployments can still start. Sunset notices go into Config.Deprecations so they never block validation.
func (*Config) EffectiveConcurrent ¶ added in v0.8.0
func (c *Config) EffectiveConcurrent(scaleSets []ScaleSetConfig) int
EffectiveConcurrent returns the process-wide instance limit. An omitted or zero value preserves historical behavior by allowing the sum of every scale set's own maximum.
func (*Config) EffectiveDrainTimeout ¶ added in v0.6.0
EffectiveDrainTimeout returns the configured process-wide drain budget.
func (*Config) GlobalValidationErrors ¶ added in v0.21.0
GlobalValidationErrors collects independent process-wide config problems. Runtime startup uses the first one; `runner validate` can report all of them.
func (*Config) IsDiskGuardEnabled ¶ added in v0.5.0
IsDiskGuardEnabled reports whether the periodic disk guard is enabled (default true unless explicitly disabled).
func (*Config) ResolveScaleSets ¶
func (c *Config) ResolveScaleSets() []ScaleSetConfig
ResolveScaleSets returns the resolved list of scale set configs. [scaleset] entries arrive from Load with inheritance already applied at the map level (a key present in an entry wins, even when zero), so multi mode only applies provider-dependent defaults and token resolution here. Without [scaleset] entries, Defaults itself is the single scale set.
func (*Config) ValidateConcurrent ¶ added in v0.8.0
func (c *Config) ValidateConcurrent(scaleSets []ScaleSetConfig) error
ValidateConcurrent ensures an explicit host-wide limit can satisfy every scale set's promised warm floor. Local max-runners values may sum above the global limit; the broker arbitrates that normal oversubscription case.
func (*Config) ValidateGlobal ¶ added in v0.4.0
ValidateGlobal checks process-wide settings that are not part of any scale set and therefore would otherwise bypass ScaleSetConfig.Validate.
type DiagnosticsConfig ¶ added in v0.13.0
type DiagnosticsConfig struct {
Enabled *bool `mapstructure:"enabled"`
CaptureLogs bool `mapstructure:"capture-logs"`
}
func (DiagnosticsConfig) IsEnabled ¶ added in v0.13.0
func (d DiagnosticsConfig) IsEnabled() bool
type DiskConfig ¶ added in v0.5.0
type DiskConfig struct {
// Guard enables the periodic disk guard. Pointer: nil = inherit default
// (true) — see DefaultDiskGuard's doc comment for why leaving it on is
// safe even though it deletes data.
Guard *bool `mapstructure:"guard"`
// MinFree is the free-space threshold that triggers reclamation: a
// percentage like "10%" (of the filesystem's total capacity) or an
// absolute size like "20GB". Defaults to DefaultDiskMinFree when unset.
MinFree string `mapstructure:"min-free"`
// TargetFree is the free-space level reclamation aims to restore before
// stopping; must be strictly greater than MinFree (see Validate).
// Defaults to DefaultDiskTargetFree when unset.
TargetFree string `mapstructure:"target-free"`
// Interval is the period between guard sweeps. <= 0 (unset) resolves to
// DefaultDiskGuardInterval (see Resolve), matching every other sweep
// interval in this package (e.g. PruneInterval).
Interval time.Duration `mapstructure:"interval"`
// MaxTier is the highest cachestore.Tier the guard may reclaim at while
// chasing TargetFree; must be between 1 and 4 (see Validate). 0 (unset)
// resolves to DefaultDiskMaxTier.
MaxTier int `mapstructure:"max-tier"`
}
DiskConfig configures the periodic disk-pressure guard (internal/diskguard): the free-space thresholds that trigger and bound reclamation, how often it sweeps, and the highest cachestore.Tier it may reach. See package diskguard's Config and Guard for what these drive at runtime.
func (DiskConfig) Resolve ¶ added in v0.14.0
func (dc DiskConfig) Resolve() (DiskGuardSettings, error)
Resolve applies the [disk] defaults, parses both thresholds and checks that they make sense together: MinFree strictly below TargetFree, and MaxTier a real tier (1-4). Both matter more than they look: MinFree >= TargetFree makes every sweep both trigger immediately and never satisfy its own target, and MaxTier outside 1-4 (in particular the zero value) silently disables the tier ladder — see diskguard.Guard.sweepFilesystem's target/free subtraction, which assumes the ladder ran at least one tier.
A zero-value DiskConfig (the operator never touched [disk]) resolves to the defaults: they are substituted before parsing, never compared as raw zero values.
func (DiskConfig) Validate ¶ added in v0.5.0
func (dc DiskConfig) Validate() error
Validate reports whether Resolve accepts these settings.
func (DiskConfig) ValidationErrors ¶ added in v0.21.0
func (dc DiskConfig) ValidationErrors() []error
ValidationErrors reports independent disk settings problems while Resolve retains its first-error behavior for startup and other callers.
type DiskGuardSettings ¶ added in v0.14.0
type DiskGuardSettings struct {
// MinFree and TargetFree are the thresholds as configured, or their
// defaults, kept as text for logs.
MinFree, TargetFree string
MinFreeThreshold bytesize.Threshold
TargetFreeThreshold bytesize.Threshold
Interval time.Duration
MaxTier int
}
DiskGuardSettings are the [disk] settings with every default applied and both thresholds parsed: exactly what the disk guard runs with.
type DockerConfig ¶ added in v0.2.3
type DockerConfig struct {
Readiness *bool `mapstructure:"readiness"`
ReadyTimeout *time.Duration `mapstructure:"ready-timeout"`
Socket string `mapstructure:"socket"`
DinD *bool `mapstructure:"dind"` // pointer: nil = inherit default (true)
WorkspaceRoot string `mapstructure:"workspace-root"` // private host directory for per-runner Docker socket proxies
Memory int `mapstructure:"memory"` // Memory limit in MB (0 = unlimited)
CPU int `mapstructure:"cpu"` // CPU cores (0 = unlimited)
PidsLimit int64 `mapstructure:"pids-limit"` // Max pids (processes + threads) per container (0 = unlimited)
Platform string `mapstructure:"platform"` // e.g. "linux/amd64" to force architecture
// ActionsCacheURL selects an explicit cache receiver. NativeActionsCache
// fills an empty value from the manager's advertised URL.
// A stock runner image is not sufficient for either endpoint.
ActionsCacheURL string `mapstructure:"actions-cache-url"`
// NativeActionsCache uses the manager's advertised native receiver URL.
NativeActionsCache bool `mapstructure:"native-actions-cache"`
// Network is the name of a pre-existing Docker network to attach runner
// containers to ("" = the daemon's default bridge). Lets operators isolate
// runners from the rest of the host network, e.g.
// `docker network create --opt com.docker.network.bridge.enable_icc=false runners`.
// Not validated here — the daemon fails container creation with a clear
// error if the network does not exist.
Network string `mapstructure:"network"`
// mount ("" = DefaultSharedVolumeName). Different scalesets — or two
// runner processes on one host — can use isolated volumes by picking
// distinct names.
SharedVolumeName string `mapstructure:"shared-volume-name"`
// CacheVolumes are named volumes mounted into every runner container at
// tool-default cache paths, so workflows hit warm caches with zero
// workflow changes. Entry format "volume-name:/absolute/container/path",
// e.g. "gradle-cache:/home/runner/.gradle". Cache volumes are persistent
// caches: they are deliberately never removed at exit and never swept by
// any TTL. Same name across scalesets = shared cache, different = isolated.
//
// This is the short form. See Cache for the long form, which adds an
// optional retention budget; ParseCacheVolumes merges the two.
// Sunset: migrate tool caches to workflow Actions cache for new deployments.
CacheVolumes []string `mapstructure:"cache-volumes"`
// Cache is the long form of CacheVolumes — [[docker.cache]] tables
// instead of "name:/path" strings — for entries that need a retention
// budget. An entry here whose Name also appears in CacheVolumes replaces
// it entirely (see ParseCacheVolumes); the two are never merged field by
// field.
// Sunset: retained for existing configurations; its budget does not map
// directly to the native Actions cache's global byte limit.
Cache []CacheVolumeSpec `mapstructure:"cache"`
// duration. Accepts Go duration strings, e.g. "168h". It must exceed
// the longest workflow run on this host: the volume holds handoff data
// a later job in the same run still reads.
//
// 0 (default) is not "cleanup off, everything else unchanged" — it is
// the only retention policy this volume has. runner stopped removing
// the volume at exit (that broke runs in flight across a restart), and
// the disk guard cannot reclaim un-expired scratch data at any tier, so
// with no max-age nothing ever frees it. The volume is still measured
// and listed by `runner cache`, and startup warns about the missing
// setting.
SharedVolumeMaxAge time.Duration `mapstructure:"shared-volume-max-age"`
// runner is up. Ignored when SharedVolumeMaxAge 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 the
// safe default (false). Enable only on a daemon dedicated to runners.
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"`
// Prune enables the periodic runtime prune of the shared Docker daemon:
// stopped containers and dangling images older than PruneTTL, plus
// age/budget-based build cache retention. Pointer: nil = inherit the safe
// default (false). Like buildx-cleanup, this assumes the daemon is dedicated to
// runners: stopped containers and dangling images older than the TTL are
// treated as garbage regardless of what created them.
Prune *bool `mapstructure:"prune"`
// PruneInterval is how often the runtime prune sweep runs while runner
// is up. Defaults to DefaultDockerPruneInterval when unset.
PruneInterval time.Duration `mapstructure:"prune-interval"`
// PruneTTL is the age threshold of the sweep: dangling images and stopped
// containers older than this are removed. Defaults to DefaultDockerPruneTTL
// when unset (0); <= 0 (i.e. negative) disables the image/container
// portion while keeping build cache retention.
PruneTTL time.Duration `mapstructure:"prune-ttl"`
// BuildCacheMaxAge prunes daemon build cache entries not used within this
// window. Defaults to DefaultDockerBuildCacheMaxAge when unset (0);
// <= 0 (i.e. negative) disables the age-based cache prune.
BuildCacheMaxAge time.Duration `mapstructure:"build-cache-max-age"`
// BuildCacheBudgetGB is an optional hard cap on the daemon build cache
// (in GB) — least-recently-used entries are evicted down to the cap on
// each sweep. 0 (default) means no cap (age-based pruning still runs).
BuildCacheBudgetGB int `mapstructure:"build-cache-budget"`
}
DockerConfig holds Docker-specific provider settings.
func (DockerConfig) ParseCacheVolumes ¶ added in v0.3.0
func (dc DockerConfig) ParseCacheVolumes() ([]CacheVolumeMount, error)
ParseCacheVolumes parses and merges CacheVolumes (short form) and Cache (long form) into one list of mounts, ordered by first appearance across both. An entry present in both forms is resolved entirely from its long-form entry — path, budget, and on-exceed all come from there, and the short-form entry of the same name is discarded rather than partially merged — matching docker-compose's own short/long merge convention.
Errors: an empty volume name or path, a non-absolute/non-clean container path, a volume name outside Docker's volume-name pattern, the same volume name repeated within one form (CacheVolumes or Cache — but not across the two; see above), two entries (from either form) resolving to the same container path, a long-form Budget that fails to parse or names a percentage (see parseCacheVolumeBudget), or a long-form OnExceed other than "", "warn", "wipe".
type GitHubAppConfig ¶ added in v0.10.0
type GitHubAppConfig struct {
ClientID string `mapstructure:"client-id"`
InstallationID int64 `mapstructure:"installation-id"`
PrivateKeyFile string `mapstructure:"private-key-file"`
PrivateKeyEnv string `mapstructure:"private-key-env"`
}
GitHubAppConfig stores references to a private key, never its PEM contents. Like PAT credentials, this configuration is local to a single scale set.
type LogFileWriter ¶ added in v0.4.0
type LogFileWriter struct {
// contains filtered or unexported fields
}
LogFileWriter is a concurrency-safe rotating writer shared by every logger in a process. Rotation keeps one backup at name + ".1". Every open, rename and unlink is relative to the directory opened at start, so replacing that directory's path afterwards cannot redirect the log.
func OpenLogFile ¶ added in v0.4.0
func OpenLogFile(path string, dirPerm fs.FileMode) (*LogFileWriter, error)
OpenLogFile opens path for appending, creating its directory with dirPerm.
func OpenRootLogFile ¶ added in v0.10.0
func OpenRootLogFile(path, trustedRoot string, dirPerm fs.FileMode) (*LogFileWriter, error)
OpenRootLogFile opens path for a root writer. Every component from / is opened without following symlinks; directories below trustedRoot are created with dirPerm when missing and must be changeable only by root. trustedRoot itself may be group-writable (/var/log is on some distributions): once the writer holds its directory, renaming anything above it cannot redirect writes or rotation.
func (*LogFileWriter) Close ¶ added in v0.4.0
func (w *LogFileWriter) Close() error
type RetryConfig ¶ added in v0.13.0
type RetryConfig struct {
Initial time.Duration `mapstructure:"initial"`
Max time.Duration `mapstructure:"max"`
CooldownAfter int `mapstructure:"cooldown-after"`
Cooldown time.Duration `mapstructure:"cooldown"`
}
func DefaultRetry ¶ added in v0.13.0
func DefaultRetry() RetryConfig
func (RetryConfig) CoolingDown ¶ added in v0.14.0
func (r RetryConfig) CoolingDown(failures int) bool
CoolingDown reports whether that many consecutive failures have moved from the exponential ramp to the flat cooldown.
func (RetryConfig) Delay ¶ added in v0.14.0
func (r RetryConfig) Delay(failures int, sample float64) time.Duration
Delay is the jittered wait after the given number of consecutive failed starts; sample in [0, 1] picks the point within the jitter window.
func (RetryConfig) Validate ¶ added in v0.13.0
func (r RetryConfig) Validate() error
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"`
Provider string `mapstructure:"provider"`
GitHubApp *GitHubAppConfig `mapstructure:"github-app"`
Retry *RetryConfig `mapstructure:"retry"`
// DisableUpdate stops GitHub from updating the runner binary inside the
// container or VM. Pointer: nil = inherit default (true), matching the
// image-based model — the runner is refreshed by rebuilding the image, and
// ephemeral runners skip a download on every job.
//
// Setting false does not protect an image from runner retirement: every
// ephemeral runner starts at the image's version, and GitHub refuses a
// retired version ("Runner version vX is deprecated and cannot receive
// messages") on the same message poll that would carry the update. It
// only makes a still-supported runner fetch the latest release before its
// first job.
DisableUpdate *bool `mapstructure:"disable-update"`
// Docker provider settings
Docker DockerConfig `mapstructure:"docker"`
// Tart VM provider settings
Tart TartConfig `mapstructure:"tart"`
}
ScaleSetConfig holds per-scale-set configuration. In multi mode, inheritance from the top-level defaults happens in Load at the map level: a key present in a [scaleset] entry always wins, even when set to a zero value.
func (*ScaleSetConfig) DockerBuildCacheMaxAge ¶ added in v0.14.0
func (ss *ScaleSetConfig) DockerBuildCacheMaxAge() time.Duration
DockerBuildCacheMaxAge is the idle age past which build cache is pruned. A negative value is kept: it disables the age-based prune while a build-cache budget still applies.
func (*ScaleSetConfig) DockerBuildxCleanupInterval ¶ added in v0.14.0
func (ss *ScaleSetConfig) DockerBuildxCleanupInterval() time.Duration
DockerBuildxCleanupInterval is how often the buildx cleanup sweep runs.
func (*ScaleSetConfig) DockerBuildxCleanupTTL ¶ added in v0.14.0
func (ss *ScaleSetConfig) DockerBuildxCleanupTTL() time.Duration
DockerBuildxCleanupTTL is the age past which an orphaned buildx builder is removed. Unlike the prune TTL, a negative value has no meaning of its own.
func (*ScaleSetConfig) DockerPruneInterval ¶ added in v0.14.0
func (ss *ScaleSetConfig) DockerPruneInterval() time.Duration
DockerPruneInterval is how often the prune sweep runs.
func (*ScaleSetConfig) DockerPruneTTL ¶ added in v0.14.0
func (ss *ScaleSetConfig) DockerPruneTTL() time.Duration
DockerPruneTTL is the age past which the prune sweep removes stopped containers and dangling images. A negative value is kept: it disables that portion while build-cache retention still runs.
func (*ScaleSetConfig) DockerReadyTimeout ¶ added in v0.13.0
func (ss *ScaleSetConfig) DockerReadyTimeout() time.Duration
func (*ScaleSetConfig) DockerSharedVolumeCleanupInterval ¶ added in v0.14.0
func (ss *ScaleSetConfig) DockerSharedVolumeCleanupInterval() time.Duration
DockerSharedVolumeCleanupInterval is how often the shared-volume TTL sweep runs. The max-age itself has no default: unset means no retention policy.
func (*ScaleSetConfig) EffectiveRetry ¶ added in v0.13.0
func (ss *ScaleSetConfig) EffectiveRetry() RetryConfig
func (*ScaleSetConfig) IsBuildxCleanupEnabled ¶ added in v0.2.23
func (ss *ScaleSetConfig) IsBuildxCleanupEnabled() bool
IsBuildxCleanupEnabled reports whether orphaned buildx builder cleanup is enabled (default false unless explicitly enabled).
func (*ScaleSetConfig) IsDinD ¶
func (ss *ScaleSetConfig) IsDinD() bool
IsDinD returns whether Docker-in-Docker is enabled for this scale set.
func (*ScaleSetConfig) IsDockerPruneEnabled ¶ added in v0.3.0
func (ss *ScaleSetConfig) IsDockerPruneEnabled() bool
IsDockerPruneEnabled reports whether the periodic Docker runtime prune is enabled (default false unless explicitly enabled).
func (*ScaleSetConfig) IsDockerReadinessEnabled ¶ added in v0.13.0
func (ss *ScaleSetConfig) IsDockerReadinessEnabled() bool
func (*ScaleSetConfig) IsTart ¶
func (ss *ScaleSetConfig) IsTart() bool
IsTart returns whether this scale set uses the Tart VM provider.
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) IsUpdateDisabled ¶ added in v0.3.3
func (ss *ScaleSetConfig) IsUpdateDisabled() bool
IsUpdateDisabled reports whether GitHub is barred from updating the runner binary inside the container or VM (default true unless explicitly enabled).
func (*ScaleSetConfig) NewScalesetClient ¶ added in v0.10.0
func (ss *ScaleSetConfig) NewScalesetClient(logger *slog.Logger, options ...scaleset.HTTPOption) (*scaleset.Client, error)
NewScalesetClient selects the configured App or PAT credentials. The SDK handles JWT signing and credential exchange when API requests need them, and its default HTTP client and retry policy apply unless options say otherwise.
func (*ScaleSetConfig) SharedVolumeName ¶ added in v0.3.0
func (ss *ScaleSetConfig) SharedVolumeName() string
SharedVolumeName returns the named Docker volume backing the shared-volume mount, falling back to DefaultSharedVolumeName when unset.
func (*ScaleSetConfig) TartCacheCleanupInterval ¶ added in v0.14.0
func (ss *ScaleSetConfig) TartCacheCleanupInterval() time.Duration
TartCacheCleanupInterval is how often the Tart cache prune runs.
func (*ScaleSetConfig) TartCacheMaxAge ¶ added in v0.14.0
func (ss *ScaleSetConfig) TartCacheMaxAge() time.Duration
TartCacheMaxAge is the idle age past which `tart prune` evicts a cached image layer.
func (*ScaleSetConfig) Validate ¶
func (ss *ScaleSetConfig) Validate() error
Validate checks required fields and logical constraints for a scale set.
func (*ScaleSetConfig) ValidationErrors ¶ added in v0.21.0
func (ss *ScaleSetConfig) ValidationErrors() []error
ValidationErrors returns independent scale-set problems in runtime check order.
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)
// MTU is applied to the guest's network interface before the runner
// starts. A host whose route to GitHub runs through a tunnel (Cloudflare
// WARP, a VPN) cannot carry the 1500-byte packets a default guest asks
// for, so TLS handshakes from the VM stall while the host itself works.
// 0 (default) = auto: match the host's route MTU to the scale set's
// GitHub host when it is below 1500, otherwise leave the guest alone.
// -1 = never touch it. 1280–1500 = always use this value.
MTU int `mapstructure:"mtu"`
// DNS replaces the guest's resolvers (e.g. ["1.1.1.1", "8.8.8.8"]) before
// the runner starts. Empty (default) keeps the resolver Tart's NAT hands
// out, which proxies through the host and can stop answering after the
// host's VPN disconnects.
DNS []string `mapstructure:"dns"`
// NetBridged attaches each VM to this host interface (`tart run
// --net-bridged=<interface>`, e.g. "en0") instead of Tart's shared NAT,
// so the guest takes its address and route from the host's network. Use
// it when the host's NAT does not serve guests: macOS bootpd can fail to
// hand out a lease, leaving the guest on a 169.254.x.x address with no
// route out. Empty (default) keeps NAT.
NetBridged string `mapstructure:"net-bridged"`
// 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"`
// CacheBudgetGB 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).
CacheBudgetGB int `mapstructure:"cache-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 provider settings.