Documentation
¶
Index ¶
- func ResolveToken(flagToken string, cfg *Config) (string, error)
- func ResolveURL(flagURL string, cfg *Config) (string, error)
- type Config
- type DockerImage
- type DockerMount
- type LibvirtImage
- type LibvirtMount
- type Provisioner
- type RunnerConfig
- type RunnerPhase
- type RunnerRequest
- type RunnerSnapshot
- type RunnerState
- type ScaleSetClient
- type Scaler
- func (s *Scaler) HandleDesiredRunnerCount(ctx context.Context, count int) (int, error)
- func (s *Scaler) HandleJobCompleted(ctx context.Context, jobInfo *scaleset.JobCompleted) error
- func (s *Scaler) HandleJobStarted(ctx context.Context, jobInfo *scaleset.JobStarted) error
- func (s *Scaler) Runners() []RunnerSnapshot
- func (s *Scaler) Shutdown(ctx context.Context)
- type SimpleHandler
- type TartImage
- type TartMount
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ResolveToken ¶
ResolveToken determines the GitHub token using the following precedence:
- flagToken (--token CLI flag)
- GITHUB_TOKEN environment variable
- $CREDENTIALS_DIRECTORY/github-token (systemd-creds)
- token_file from config
Types ¶
type Config ¶
type Config struct {
URL string `yaml:"url"`
TokenFile string `yaml:"token_file"`
Runners map[string]RunnerConfig `yaml:"runners"`
}
Config is the outrunner configuration file format.
func LoadConfig ¶
LoadConfig reads and parses a config file.
type DockerImage ¶
type DockerImage struct {
Image string `yaml:"image"`
RunnerCmd string `yaml:"runner_cmd"`
Mounts []DockerMount `yaml:"mounts"`
}
DockerImage configures a Docker-based runner.
type DockerMount ¶ added in v1.1.0
type DockerMount struct {
Source string `yaml:"source"`
Target string `yaml:"target"`
ReadOnly bool `yaml:"read_only"`
}
DockerMount defines a bind mount for a Docker container.
type LibvirtImage ¶
type LibvirtImage struct {
Path string `yaml:"path"`
RunnerCmd string `yaml:"runner_cmd"`
Socket string `yaml:"socket"`
CPUs int `yaml:"cpus"`
MemoryMB int `yaml:"memory"`
Mount *LibvirtMount `yaml:"mount"`
}
LibvirtImage configures a libvirt/QEMU-based runner.
type LibvirtMount ¶ added in v1.1.0
type LibvirtMount struct {
Source string `yaml:"source"`
}
LibvirtMount defines a virtiofs host directory share for a libvirt VM. The directory is exposed via virtiofs; the tag is derived from the source basename. On Windows guests, VirtioFsSvc mounts it automatically as a drive letter.
type Provisioner ¶
type Provisioner interface {
// Start provisions a new runner environment and starts the GitHub Actions
// runner process inside it. The runner should use the JIT config to
// register itself with GitHub and pick up the assigned job.
//
// Start must return after the runner process has been launched.
// It does not need to wait for the job to complete.
Start(ctx context.Context, req *RunnerRequest) error
// Stop tears down the runner environment. Called after the job completes
// or if the runner needs to be forcefully removed.
Stop(ctx context.Context, name string) error
// Close releases any resources held by the provisioner (e.g., Docker client).
Close() error
}
Provisioner creates and destroys ephemeral runner environments. Each implementation handles a different backend (Docker, libvirt, etc.).
type RunnerConfig ¶
type RunnerConfig struct {
Labels []string `yaml:"labels"`
MaxRunners int `yaml:"max_runners,omitempty"`
Docker *DockerImage `yaml:"docker,omitempty"`
Libvirt *LibvirtImage `yaml:"libvirt,omitempty"`
Tart *TartImage `yaml:"tart,omitempty"`
}
RunnerConfig defines a runner environment and the scale set it registers. The map key in Config.Runners is used as the scale set name. Exactly one of Docker, Libvirt, or Tart must be set.
func (*RunnerConfig) ProviderType ¶
func (r *RunnerConfig) ProviderType() string
ProviderType returns which provisioner backend this runner uses.
type RunnerPhase ¶
type RunnerPhase int
RunnerPhase represents the current lifecycle phase of a runner.
const ( RunnerProvisioning RunnerPhase = iota RunnerIdle RunnerRunning RunnerStopping )
func (RunnerPhase) String ¶
func (p RunnerPhase) String() string
type RunnerRequest ¶
type RunnerRequest struct {
// Name is a unique identifier for this runner instance.
Name string
// JITConfig is the base64-encoded JIT configuration from GitHub.
// Pass to: ./run.sh --jitconfig <JITConfig>
JITConfig string
// Runner is the matched runner configuration.
Runner *RunnerConfig
}
RunnerRequest contains everything a provisioner needs to start a runner.
type RunnerSnapshot ¶
type RunnerSnapshot struct {
Name string
RunnerID int
Phase RunnerPhase
CreatedAt time.Time
StartedAt time.Time
}
RunnerSnapshot is a point-in-time copy of a runner's state, safe to read without holding the scaler's mutex.
type RunnerState ¶
type RunnerState struct {
Name string
RunnerID int // from GenerateJitRunnerConfig().Runner.ID
Phase RunnerPhase
CreatedAt time.Time
StartedAt time.Time // when Start() completed (provisioning finished)
// contains filtered or unexported fields
}
RunnerState holds the full state of a single runner instance.
func (*RunnerState) SignalDone ¶
func (r *RunnerState) SignalDone()
SignalDone closes the done channel, signaling the runner goroutine to stop. Safe to call multiple times.
type ScaleSetClient ¶
type ScaleSetClient interface {
GenerateJitRunnerConfig(ctx context.Context, setting *scaleset.RunnerScaleSetJitRunnerSetting, scaleSetID int) (*scaleset.RunnerScaleSetJitRunnerConfig, error)
RemoveRunner(ctx context.Context, runnerID int64) error
}
ScaleSetClient is the subset of scaleset.Client that Scaler uses. Extracted as an interface for testability.
type Scaler ¶
type Scaler struct {
// contains filtered or unexported fields
}
Scaler implements listener.Scaler by provisioning real runner environments. Each runner gets its own goroutine that manages the full lifecycle: provisioning, waiting for job completion, stopping, and deregistration.
func NewScaler ¶
func NewScaler(logger *slog.Logger, client ScaleSetClient, scaleSetID, maxRunners int, namePrefix string, runner *RunnerConfig, prov Provisioner) *Scaler
func (*Scaler) HandleDesiredRunnerCount ¶
func (*Scaler) HandleJobCompleted ¶
func (*Scaler) HandleJobStarted ¶
func (*Scaler) Runners ¶
func (s *Scaler) Runners() []RunnerSnapshot
Runners returns a snapshot of current runner states.
type SimpleHandler ¶
type SimpleHandler struct {
// contains filtered or unexported fields
}
SimpleHandler outputs logs in a human-readable format:
2026-03-30 21:08:31 INFO Loaded config runners=1
func NewSimpleHandler ¶
func NewSimpleHandler(w io.Writer, level slog.Leveler) *SimpleHandler
type TartImage ¶
type TartImage struct {
Image string `yaml:"image"` // OCI image or local VM name
RunnerCmd string `yaml:"runner_cmd"`
CPUs int `yaml:"cpus"`
MemoryMB int `yaml:"memory"`
Mounts []TartMount `yaml:"mounts"`
}
TartImage configures a Tart-based runner (macOS/Linux on Apple Silicon).
type TartMount ¶ added in v1.1.0
type TartMount struct {
Name string `yaml:"name"`
Source string `yaml:"source"`
ReadOnly bool `yaml:"read_only"`
}
TartMount defines a shared directory for a Tart VM. Name is passed as the --dir label; it becomes the subdirectory name under the mount point inside the guest.
