quickstart →

Building a custom AMI with Packer

Learn how to build a custom AMI using Packer to prepopulate with your software, ensure compliance, and control over your GitHub Actions workflows.

RunsOn provides base images (AMIs) for your workflows, which are regularly updated ↗.

In some cases though, you might want to generate a new AMI from one of those base images, and use it in your workflows.

This can be useful if you want to:

  • prepopulate the AMI with your own software, docker images, data, etc.
  • fulfill advanced compliancy requirements, with a stable image that you control.

An easy way to do this is to regularly rebuild your own AMI from the base images with Packer.

Use base images in a region without a public RunsOn AMI#

RunsOn publishes public AMIs in a limited set of regions. If your target region does not have one, deploy the standalone ami_sync Terraform module once per AWS account and destination region, in its own state:

main.tf
module "ami_sync" {
source = "runs-on/runs-on/aws//modules/ami_sync"
enabled = true
stack_name = "runs-on-shared"
# Pass tags and, if needed, the key used to encrypt copied snapshots.
common_tags = { Team = "platform", Environment = "production" }
# kms_key_id = "default"
}

The module immediately copies the latest default Ubuntu 24 and Ubuntu 26 base images (x64 and arm64) from us-east-1, then refreshes them on a schedule and retains the newest copies. RunsOn looks for AMIs in your account before its public account, so runners discover the copies automatically — no product-level flag, custom image definition, or redeploy is needed.

Pass the product stack’s tags as common_tags when an SCP requires tags at resource creation. Set kms_key_id if copied snapshots must use a particular EBS key. For a different AMI family or prefix, override the module’s images input. See the standalone module example ↗.

Reference the latest base image from SSM Parameter Store#

Since v3.5.0, every RunsOn stack (Flex and Fleet, CloudFormation and Terraform) publishes the current AMI ID of each built-in image to SSM Parameter Store, in the stack’s own account and region:

/<stack-name>/images/<image-id>

For example, a stack named runs-on publishes /runs-on/images/ubuntu24-full-x64 and /runs-on/images/ubuntu24-full-arm64. Each parameter holds the AMI that RunsOn itself launches for that image, including ami_sync copies, and the stack refreshes it every hour. An image that is not available in the region has no parameter.

Tools that accept an SSM parameter can then build on the latest RunsOn image without looking up AMI IDs. For example, in an EC2 Image Builder recipe:

{
"parentImage": "ssm:/runs-on/images/ubuntu24-full-arm64"
}

The parameters use the aws:ec2:image data type, so EC2 launch templates can also use them as the image ID (resolve:ssm:/runs-on/images/<image-id>).

How the base images boot#

The base images boot fast because they start very little. Before you write a Packer template, check what your base image ships:

Base imageBoots withSSH daemonSSM agent
ubuntu22-full-*, ubuntu24-full-*cloud-initInstalled, disabledYes
ubuntu26-full-*rolaunchInstalled, disabledYes
ubuntu24-minimal-*rolaunchInstalled, disabledNo

On images that boot with rolaunch, cloud-init is disabled. User data must be a shell script starting with #!: a #cloud-config document is not run.

Packer connects over SSH, including when you set ssh_interface = "session_manager": Session Manager only tunnels the SSH connection. So the build instance must start the SSH daemon from its user data, and on the minimal images Session Manager also needs the agent installed by that same script. Plain SSH as ubuntu works on every image.

AWS settings for the RunsOn agent#

The RunsOn agent uses the EC2 instance role for its own AWS requests, including post-job metrics uploads and Sticky Disk clean markers. AWS credentials in environment variables or shared AWS profile files do not replace that role. Your workflow’s AWS tools and actions keep their own credential settings.

The agent does not load ~/.aws/config, ~/.aws/credentials, or the AWS SDK settings for custom CA bundles (AWS_CA_BUNDLE), service endpoints (AWS_ENDPOINT_URL and AWS_ENDPOINT_URL_<SERVICE>), FIPS or dual-stack endpoints, or retry mode and attempt limits. If your custom AMI needs a private certificate authority, install it in the operating system’s trust store.

IMDS still reads AWS_EC2_METADATA_DISABLED and AWS_EC2_METADATA_SERVICE_ENDPOINT directly. Keep IMDS available to the agent; disabling it prevents the agent from obtaining instance-role credentials.

Manifest file#

In this example we will generate a new AMI for arm64, from the Ubuntu 26 full image.

main.tf
packer {
required_plugins {
amazon = {
source = "github.com/hashicorp/amazon"
version = "~> 1"
}
}
}
variable "subnet_id" {
type = string
}
variable "region" {
type = string
}
variable "ami_prefix" {
type = string
}
data "amazon-ami" "runs-on-ami" {
filters = {
name = "runs-on-v2.2-ubuntu26-full-arm64-*"
root-device-type = "ebs"
virtualization-type = "hvm"
}
most_recent = true
owners = ["135269210855"]
region = "${var.region}"
}
source "amazon-ebs" "build-ebs" {
ami_name = "${var.ami_prefix}-runs-on-${formatdate("YYYY-MM-DD-hhmmss", timestamp())}"
instance_type = "t4g.small"
region = "${var.region}"
source_ami = "${data.amazon-ami.runs-on-ami.id}"
ssh_username = "ubuntu"
subnet_id = "${var.subnet_id}"
user_data_file = "./scripts/user_data.sh"
}
build {
sources = ["source.amazon-ebs.build-ebs"]
provisioner "shell" {
execute_command = "sudo sh -c '{{ .Vars }} {{ .Path }}'"
script = "./scripts/provision.sh"
}
# Always last: clears the build instance's state from the AMI.
provisioner "shell" {
execute_command = "sudo bash -c '{{ .Vars }} {{ .Path }}'"
script = "./scripts/finalize.sh"
}
}

User data file#

The user data starts the SSH daemon, otherwise Packer can’t connect to the instance to perform the provisioning.

In the example this would be a file in scripts/user_data.sh:

#!/bin/bash
systemctl unmask ssh.service || true
systemctl enable ssh.service || true
systemctl start ssh.service || true

Provisioning file#

The provisioning file is where you put your scripts to install software, run commands, etc.

In the example this would be a file in scripts/provision.sh:

#!/bin/bash
set -e
apt-get update
apt-get install -y software1 software2

Finalize file#

The last provisioner removes what the build instance left behind, so that each runner launched from your AMI starts clean and fast:

  • the SSH daemon is disabled again, and the build’s SSH keys are removed. The host keys are regenerated on each runner’s first boot.
  • on images that boot with rolaunch, its state from the build instance is removed. Otherwise the runner’s boot timings start with the build instance’s boot, days earlier, and every runner shares the build’s machine-id.
  • on images that boot with cloud-init, cloud-init’s state is cleaned.
  • on Ubuntu 26 full, the build’s netplan files are removed (its network configuration doesn’t use netplan), and services your packages switched back on are kept off at boot again.

If you installed and started the SSM agent on a minimal image, disable it here as well.

In the example this would be a file in scripts/finalize.sh:

#!/bin/bash
set -euo pipefail
if systemctl list-unit-files rolaunch.service --no-legend | grep -q '^rolaunch.service'; then
# SSH can come up just before rolaunch records success: wait for it first.
systemctl start rolaunch.service
rm -f \
/var/lib/rolaunch/instance-identity.json \
/var/lib/rolaunch/runs-on-user-data.done \
/var/lib/rolaunch/timings.json \
/var/lib/rolaunch/user-data.sh
truncate -s 0 /etc/machine-id
rm -f /var/lib/dbus/machine-id
else
cloud-init clean --logs
rm -rf /var/lib/cloud/*
fi
# Ubuntu 26 full only: it configures the network without netplan, and packages
# you installed may have switched services back on that it keeps off at boot.
if [ -e /etc/systemd/network/10-runs-on-ec2.network ]; then
rm -f /etc/netplan/*.yaml
systemctl disable netavark-dhcp-proxy.service udisks2.service
systemctl enable netavark-dhcp-proxy.socket
rm -f \
/etc/systemd/system/sysinit.target.wants/systemd-binfmt.service \
/lib/systemd/system/sysinit.target.wants/systemd-binfmt.service \
/usr/lib/systemd/system/sysinit.target.wants/systemd-binfmt.service
fi
rm -f /home/ubuntu/.ssh/authorized_keys /root/.ssh/authorized_keys
shred -u /etc/ssh/*_key /etc/ssh/*_key.pub
systemctl disable ssh.service ssh.socket || true
find /var/log/journal -mindepth 1 -delete || true
sync

Building the image#

Initialize Packer:

packer init custom-ami-arm64.pkr.hcl

Then build the image:

packer build -var "ami_prefix=MY_COMPANY" -var "subnet_id=your-subnet-id" -var "region=us-east-1" custom-ami-arm64.pkr.hcl

After some time you should get a new AMI registered into your AWS account, and you can start using it by referencing the AMI ID or name in your workflows.

See the documentation on custom images for more details.

Building AMIs from scratch#

Note: for all AMIs, make sure you trigger regular rebuilds, so that you get the latest version of the GitHub Actions runner agent. GitHub will stop sending jobs to your runners if the GitHub Actions runner agent is older than 30 days.

Linux AMIs#

If you want to build a custom Linux AMI completely from scratch, you can do so, but we recommend you pre-populate that AMI with the following resources:

  • a runner user with UID 1001, and home directory /home/runner. That user should have passwordless sudo access.
  • the latest version of the GitHub Actions runner ↗ for Linux, unpacked into /home/runner. That is, /home/runner/run.sh should exist.
  • for recent RunsOn versions, the RunsOn bootstrap script ↗ for the AMI architecture, unpacked at /usr/local/bin/runs-on-bootstrap-TAG. Match the TAG value to the RunsOn version you are deploying; do not rely on the old RunsOnBootstrapTag CloudFormation output, which no longer exists in v3.

This will speed up the boot time, and avoid rate-limit issues that can occur when the runner has to download the GitHub agent and bootstrap script from GitHub for every job.

Windows AMIs#

If you want to build a custom Windows AMI completely from scratch, you can do so, but we recommend you pre-populate that AMI with the following resources:

  • the latest version of the GitHub Actions runner ↗ for Windows, unpacked into C:\actions-runner. That is, C:\actions-runner\run.cmd should exist.
  • for recent RunsOn versions, the RunsOn bootstrap script ↗ for the AMI architecture, unpacked at "C:\runs-on\bootstrap-TAG.exe". Match the TAG value to the RunsOn version you are deploying; do not rely on the old RunsOnBootstrapTag CloudFormation output, which no longer exists in v3.

This will speed up the boot time, and avoid rate-limit issues that can occur when the runner has to download the GitHub agent and bootstrap script from GitHub for every job.