Get started / Runner images and storage

Choose the tools and disk performance your jobs need.

Controller v0.5.0 and module 0.5.0 add two optional Linux runner images and configurable gp3 performance. Both images support x64 and ARM64. Existing image and storage defaults stay in place until you change them.

Choose a profile

Profile	Included tools	Use it for
`lean`	GitHub runner, JavaScript action runtimes, Git, curl, Docker client, and upstream utilities.	Containerized jobs and workflows that install their own tools.
`development`	Lean plus Node 24.20.0/npm, Go 1.27.1, Ubuntu Python 3/pip/venv, C/C++ build tools, pkg-config, zip/unzip, and zstd.	Common Node, Go, Python, and native compilation jobs.

These are container images running on your selected ECS-optimized EC2 AMI. They do not include the full GitHub-hosted Ubuntu software catalog. Use setup actions or your own images for other tools and versions; see workflow compatibility. Development has a larger download and disk footprint, so measure both cold start and job time for your workload.

Pin the selected image

Download and verify the signed release manifest for v0.7.0. Use runner_images.lean.reference or runner_images.development.reference as your approved image value. Each reference includes its immutable multiarchitecture digest.

# In the directory containing your verified release manifest:
jq '.runner_images' release-manifest.json
jq -r '.runner_images.development.reference' release-manifest.json

Set fleets.<name>.runner_container_image, or the global runner_container_image for a legacy single fleet. Keep digest enforcement enabled. New runners use the selected image; running jobs finish with their original image. Restore the previous digest to roll back future launches.

The release includes SBOM and provenance attestations. Development also records installed versions in /opt/gondola/tool-versions.txt. If you mirror images into a private registry, configure image-pull access in the runner’s AMI and network; runners do not inherit the controller’s registry credentials. Keep untrusted and privileged jobs in separate fleets.

Configure gp3 performance

Runner root volumes are encrypted and deleted with the instance. Defaults are 50 GiB, 3,000 IOPS, and 125 MiB/s. Merge the following overrides into your existing fleet and set approved_runner_image to the selected manifest reference.

fleets = {
  build = {
    scale_set_name         = "gondola-build"
    runner_container_image = var.approved_runner_image
    root_volume_size       = 100
    root_volume_iops       = 6000
    root_volume_throughput = 250
  }
}

Global defaults use runner_root_volume_size, runner_root_volume_iops, and runner_root_volume_throughput. Fleet settings override them. Review effective inherited values in the Terraform/OpenTofu plan; the module checks gp3 limits and performance ratios. An EC2 type’s EBS limits can still be lower than the requested volume performance.

Additional storage and provisioned performance add AWS charges. Allow space for image layers, workspaces, and cache extraction. These disks remain disposable; use S3 caching to reuse supported build data between jobs. Changes apply to new instances.