Creating Custom Images

Creating Custom Images

✅ Available:	>= 1.7.241002

You can create custom runner server images using the images create command. This command generates a snapshot of the server disk, which can later be used to launch a new server without requiring further dynamic runner server configuration.

Common use cases

• Consistency: Ensure that runners are deployed with identical configurations, reducing variance.
• Dependencies: Pre-install key packages or libraries to avoid network or repository downtime affecting CI/CD jobs.
• Deployment times: Pre-configure environments to eliminate the need for installing software during job runs may reduce the deployment time.

❗ Warning:	Creating and reimaging runner servers using snapshots takes significantly longer compared to servers that use default system or application images. Therefore, the benefit of the reduced deployment time depends on whether the time saved during server configuration outweighs the additional time needed to create a new server from the snapshot.

Using custom snapshots as images for runner servers is particularly useful in high-availability production CI/CD pipelines, where reducing the reliance on dynamic software installation is critical. Such installations can introduce instability and occasionally fail for various reasons.

Using custom snapshots

Once the snapshot is created, you can use it by specifying the snapshot through the image- runner label.

For example,

job-name:
  runs-on: [self-hosted, image-x86-snapshot-<snapshot_name>]

See Specifying The Runner Image.

❗Warning:	Snapshot creation happens asynchronously, meaning the snapshot image won’t be immediately available after the create command completes. You can monitor the snapshot’s creation status via the Hetzner Cloud web console.
✋Note:	In Hetzner Cloud, snapshots cannot be assigned a name directly. Instead, the --name option sets the image's description attribute.

Creating a custom snapshot image

To create a custom snapshot image, you must specify both the --name and --setup-script options:

• The --name option sets the snapshot's name.
• The --setup-script specifies the shell script that will run on the server created from the base image, customizing it by installing and configuring necessary software, ensuring no further setup is needed when new runners are created.

Example command

github-hetzner-runners images create --name my-custom-image --setup-script ./my-custom-setup.sh

After the snapshot is created, you can check its status via the Hetzner Cloud web console. Once complete, you can use the snapshot as follows:

job-name:
  runs-on: [self-hosted, image-x86-snapshot-my-custom-image]

Deleting and listing available snapshots

See Deleting Images and Listing Images on how to delete and list available snapshots.

Available options for the create command

• -n, --name The name of the snapshot (required).
• --setup-script Path to the custom setup script to be executed on the server, which customizes the default image (required).
• -l, --location Specifies the server's location.
• -t, --type The server type, default: cpx11.
• -i, --image Specifies the base server image's architecture, type, and name or description. The architecture can be either 'x86' or 'arm'. The type can be one of 'system', 'snapshot', 'backup', or 'app'. Default: x86:system:ubuntu-22.04.
• --server-name The server name, default: snapshot-server.