config

package
v0.22.1 Latest Latest
Warning

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

Go to latest
Published: Nov 14, 2026 License: MIT Imports: 34 Imported by: 0

Documentation

Index

Constants

View Source
const (
	DefaultActionsTokenIssuer = "https://token.actions.githubusercontent.com"
	DefaultActionsJWKSURL     = "https://token.actions.githubusercontent.com/.well-known/jwks"
	DefaultResultsUpstreamURL = "https://results-receiver.actions.githubusercontent.com"
)
View Source
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

	// DefaultSharedVolumeName is the named Docker volume backing the
	// shared-volume mount when docker.shared-volume-name is unset.
	DefaultSharedVolumeName = "runner-shared"

	// DefaultSharedVolumeCleanupInterval is the period between shared-volume
	// 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.

View Source
const (
	DefaultLogMaxSize = int64(10 * 1024 * 1024)
)
View Source
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

func BuildLabels(name string, labels []string) []scaleset.Label

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

func DrainTimeoutOrDefault(configured *time.Duration) time.Duration

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

func NewLogger(level, format string) *slog.Logger

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

func NewLoggerWithWriter(level, format string, console *os.File, file io.Writer) *slog.Logger

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

type CacheVolumeMount struct {
	Volume      string
	Path        string
	BudgetBytes uint64
	OnExceed    string
}

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

func Load(v *viper.Viper) (Config, error)

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

func (c *Config) EffectiveDrainTimeout() time.Duration

EffectiveDrainTimeout returns the configured process-wide drain budget.

func (*Config) GlobalValidationErrors added in v0.21.0

func (c *Config) GlobalValidationErrors() []error

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

func (c *Config) IsDiskGuardEnabled() bool

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

func (c *Config) ValidateGlobal() error

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
	SharedVolume  string         `mapstructure:"shared-volume"`
	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"`

	// SharedVolumeName is the named Docker volume backing the shared-volume
	// 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"`

	// SharedVolumeMaxAge deletes files in shared-volume older than this
	// 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"`
	// SharedVolumeCleanupInterval is how often the cleanup sweep runs while
	// 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

func (*LogFileWriter) Write added in v0.4.0

func (w *LogFileWriter) Write(p []byte) (int, 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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL