Why does a 2-core (75GB) runner create a 106GB root volume for custom images?

[satoru-shibano]

Why are you starting this discussion?

Question

What GitHub Actions topic or product is this about?

Actions Runner Image

Discussion Details

Issue Summary

When creating a custom image on a 2-core runner with 75GB SSD specification, the root volume (/dev/root) is
unexpectedly expanded to 106GB. This results in a 110GB custom image that cannot be used on 2-core runners due to disk
capacity constraints.

Environment

• Runner: GitHub-hosted (Arm Limited)
• Runner Size: 2-core, 8GB RAM, 75GB SSD (as specified)
• Base Image: Ubuntu 24.04 by Arm Limited (20260127.52.1)
• Custom Image Creation Runner: hodai-custom-image-generator-2core (2-core, 75GB SSD)

Current Behavior

When running a workflow to create a custom image:

1. Runner specifications show: 2-core : 8 GB RAM : 75 GB SSD
2. However, df -h shows the actual volume size:

Filesystem Size Used Avail Use% Mounted on
/dev/root 106G 25G 81G 24% /
tmpfs 3.9G 100K 3.9G 1% /dev/shm
tmpfs 1.6G 1.1M 1.6G 1% /run
...

3. After image creation, the resulting custom image is 110GB
4. This image cannot be used on 2-core runners due to the 74GB size limit

Expected Behavior

• Runner with 75GB SSD specification should have a root volume of ~75GB or less
• Created custom image should be <74GB to be usable on 2-core runners
• Previously (several months ago), the same setup created images with ~72GB volumes, which worked fine

Steps to Reproduce

1. Create a runner with 2-core, 75GB SSD specification
2. Create a workflow that:
   • Runs on this runner
   • Uses snapshot: <image-name> to create a custom image
3. Check df -h in the workflow
4. Observe that /dev/root shows 106GB instead of expected ~75GB

Workflow Configuration

jobs:                                                                                                                    
  build:                                                                                                                 
    runs-on: hodai-custom-image-generator-2core  # 2-core, 75GB SSD                                                      
    snapshot: hodai-custom-image                                                                                         
    steps:                                                                                                               
      - name: Check disk usage                                                                                           
        run: df -h                                                                                                       
                                                                                                                         
Questions                                                                                                                
                                                                                                                         
1. Why is the root volume expanded to 106GB when the runner specification clearly states 75GB SSD?                       
2. Is this a recent change in GitHub-hosted runners? (Previously, we had ~72GB volumes)                                  
3. How can we ensure the custom image stays within the 74GB limit for 2-core runners?                                    
4. Is there a way to control the root volume size during custom image creation?                                          
                                                                                                                         
Related Information                                                                                                      
                                                                                                                         
- Custom image size limit for 2-core runners: 74GB (https://docs.github.com/en/actions/hosting-your-own-runners/managing-
self-hosted-runners-with-actions-runner-controller/about-actions-runner-controller#runner-scale-set-runners)             
- We've attempted to reduce disk usage by removing unnecessary packages, but the base volume size (106GB) remains the    
issue                                                                                                                    
                                                                                                                         
Impact                                                                                                                   
                                                                                                                         
This issue prevents us from using custom images on 2-core runners, forcing us to upgrade to 4-core runners (which have   
150GB disk), significantly increasing our GitHub Actions costs.                                                          
                                                                                                                         
Any guidance or clarification on this behavior would be greatly appreciated!        

[CodeWIthAbdullah-007]

Why does a 2-core (75GB) runner create a 106GB root volume for custom images?

Thanks for raising this. What you’re observing is expected behavior based on how GitHub provisions runners for custom image creation versus how disk limits are enforced when those images are used at runtime.

When a 2-core runner is used to build a custom image, it may be provisioned on a larger underlying block device (~106GB) than the advertised 75GB SSD. The 75GB value represents the maximum disk size supported when running jobs on 2-core runners, not necessarily the physical disk size of the VM used during image generation.

On Ubuntu 24.04, the root filesystem is automatically expanded at boot (via growpart and resize2fs) to use all available space on the attached device. As a result, the root filesystem (/dev/root) expands to approximately 106GB, which is what is reported by df -h.

When a snapshot is created, GitHub preserves the partition layout and filesystem size of the runner. This means the resulting custom image reflects the expanded root filesystem and therefore ends up being larger than the ~74GB image size limit enforced for 2-core runners at runtime.

This behavior may differ from what was observed previously, as changes to base images (such as Ubuntu 24.04) and underlying runner infrastructure can affect how disks are provisioned and initialized.

Why reducing disk usage does not change the image size

Removing packages or cleaning caches does not reduce the final image size in this case. Snapshot creation captures the filesystem size, not just the amount of data stored within it. As long as the root filesystem remains expanded, the image size will exceed the supported limit.

Recommended workaround

To ensure a custom image can be used on 2-core runners, the root filesystem should be resized to within the supported limit prior to snapshot creation.

As a final step in the image build workflow, run:

sudo resize2fs /dev/root 74G

This should be done after all installations and before the snapshot is taken.

Summary

In short, this is an infrastructure and image-building behavior difference, not a workflow misconfiguration. Until disk sizing is aligned or enforced during custom image creation, manually resizing the root filesystem is the recommended approach for producing custom images compatible with 2-core runners.

[satoru-shibano]

Thank you for the helpful suggestion, @CodeWIthAbdullah-007!

Unfortunately, I encountered an issue when attempting to resize the filesystem as you suggested.

What Happened

When running sudo resize2fs /dev/root 74G in the workflow:

resize2fs 1.47.0 (5-Feb-2023)
resize2fs: On-line shrinking not supported
Filesystem at /dev/root is mounted on /; on-line resizing required
Error: Process completed with exit code 1.

Root cause: While resize2fs supports expanding a mounted filesystem online, it does not support shrinking a
mounted filesystem. Since /dev/root is the root filesystem and cannot be unmounted during the workflow execution, we
cannot reduce its size using this method.

[supremeinferno]

Why does a 2-core (75GB) runner create a ~106GB root volume for custom images?

This happens because runner size (CPU/RAM) and disk size are decoupled, especially when using custom images.

Key reasons:

• Custom image snapshot size

  • The root volume is created from the image snapshot, not from the runner’s advertised disk size.
  • Snapshots are often rounded up to a larger size for safety.

• Filesystem & OS overhead

  • Boot partitions, reserved filesystem blocks, and OS metadata consume extra space.
  • This can easily push a 75GB disk closer to ~100GB.

• Safety buffer for CI workloads

  • Custom images are commonly used for Docker builds, caches, and large dependencies.
  • GitHub provisions extra disk space to avoid unexpected “disk full” failures.

Important notes:

• The billing and limits are still based on the runner type, not the expanded root volume.
• The root volume is ephemeral and deleted after the job completes.

Can this be reduced?

• You cannot shrink the root volume below the image snapshot size.
• You can reduce it by:
• Using a smaller base image
• Removing unnecessary packages before creating the custom image

[satoru-shibano]

@supremeinferno

Thank you for the detailed explanation!
I understand that the root volume size is determined by the custom image snapshot rather than the runner's advertised disk size.
However, I'd like to clarify a few points about our specific setup:
Our runner configuration:

Size: 2-cores, 8GB RAM, 75GB SSD
Image source: Partner
Image name: Ubuntu 24.04 by Arm Limited

Questions and concerns:

Is there no option to use a different base image?

Since we're using a partner-provided image (Ubuntu 24.04 by Arm Limited), can we switch to a different base image, or are we locked into this partner's image for this runner type?

Removing packages doesn't reduce the image size

I tried removing unnecessary packages, but the created image size remained unchanged.
This seems to be because we cannot resize the root volume online during the image creation process.
Even when adding or removing packages, the resulting image snapshot size stays the same.

Is the ~106GB volume size fixed for this partner image?

Is this volume size predetermined by Arm Limited's base image, and essentially unchangeable on our end?

Are there any workarounds?

Since we cannot shrink the root volume below the snapshot size, and package removal doesn't help, are there any other approaches to optimize disk usage?

We want to understand whether this is a limitation we need to accept when using partner-provided ARM images, or if there are alternative solutions available.

[supremeinferno]

This is expected behavior for partner-provided ARM images.

On GitHub-hosted runners, the runner disk size (75GB) only defines the tier.
When using partner images (e.g. Ubuntu 24.04 by Arm Limited), the root filesystem size is taken directly from the image snapshot, which is ~106GB in this case.

Key points:

• Snapshot size is fixed and cannot be shrunk.
• Removing packages does not reduce snapshot size (it’s based on filesystem layout, not used space).
• The base image cannot be changed for this runner type.
• GitHub does not support filesystem resizing during custom image creation.

So yes the ~106GB root volume is predetermined by the partner image and effectively unchangeable.
This is a platform limitation, not a misconfiguration or bug.

The only mitigation is managing disk usage within jobs (cleanup, avoid large root-level caches, move artifacts elsewhere).