Custom images for GitHub-hosted runners are now available in public preview

[ebndev]

Custom images for GitHub-hosted runners are now available in public preview. This feature allows you to start with a GitHub-curated base image and build your own virtual machine image tailored to your workflow needs.

Custom images can include your repository code, prepulled container images, required binaries, certificates, and other dependencies. Developers benefit from:

• Faster workflows: Start jobs with preinstalled tools and dependencies, reducing setup time and dramatically speeding up builds.
• Hardened security: Standardize your build environments, enforce organization-wide image policies, and minimize vulnerabilities by reducing the attack surface.
• Cost optimization: Faster job starts mean fewer billed minutes, helping you lower your overall CI/CD costs.
• Enterprise-grade customization: Preinstall exactly what your teams need. From certificates and proxies to monitoring agents, all while maintaining full control over image lifecycle and rollout.
• Lifecycle management: Administrators can set policies for the number of versions per image, removal of images that have not been used for a predetermined amount of time, and the maximum image age before it is disabled, to align with organizational security and compliance requirements.

How to get started

Custom images let you define exactly what your GitHub Actions runner environment looks like, so every workflow starts with the tools, dependencies, and configurations you need already in place. Here’s how to get started:

1. Create a larger runner that can generate custom images.
Begin by setting up a runner capable of building custom images. This runner uses a base image (either a GitHub partner image or one you’ve already generated) as the foundation for your new image. This layered approach lets you build on trusted environments and add only what you need.

2. Run an image-generating workflow.
In your workflow file, add a new snapshot type to your job. This tells GitHub Actions to capture the state of your runner after installing all required tools and packages.

3. Add your runner to a runner group with the custom image.
Once your image is built, a larger runner uses it and is then assigned to a runner group. Runners already using the named image will automatically pick up new versions of the image. In your workflows, you still need to reference the runner or runner group name—you cannot target runners solely by the image name. All subsequent workflow runs using this runner will start with your custom environment, saving time and ensuring consistency. Please allow 10-15 minutes after the image has been created before the new version is ready to use.

4. Use your custom image in future workflows.
To use your custom image, set the runs-on target in your workflow to the name of the runner (or runner group with a runner) using the custom image. Every job will start with your dependencies preinstalled, so you can focus on building and shipping faster.

Learn more

For detailed instructions, advanced configuration options, and troubleshooting tips, see our official documentation on managing larger runners. You’ll find step-by-step guides, workflow examples, and best practices for using custom images with GitHub-hosted runners.

🌟Leave a comment!

Join the discussion and leave feedback in the comments below!

Disclaimer: The UI for features in public preview is subject to change.

[crohr]

In your workflow file, add a new snapshot type to your job.

Not sure where this new keyword should be added?

[Gaardsholt]

Yeah a link to the documentation would have been great - but I guess it's this one: https://docs.github.com/en/actions/how-tos/manage-runners/larger-runners/use-custom-images#generating-a-custom-image

[herzogf]

This feature is great - we hope to use it for dependabot accessing registries with self-signed certs.
One question: my newly built image takes forever to provision; instead of the 15 minutes described in the docs the image still hangs at "Replicating image to regions (97%)" after 2 hours. Are those initial performance issues or known problems atm?

update for clarification: the custom image is the basic ubuntu-latest + some certificate files ;-) so no 8k movies included. Total size is shown as "0 GB".

[herzogf]

Is it possible to create a custom image with hard-coded / baked-in environment variables so that the workflow runs using this image will automatically have those environment variables set?
In our custom image build we tried to write env vars into $GITHUB_ENV and ~/actions-runner/.env but the workflows that use the custom image don't have those env vars set 😕

Our use case: dependabot needs to connect to an artifact repo with self-signed certs. We want to create a custom image with those self-signed certs and the environment variable "NODE_EXTRA_CA_CERTS" set so that the official dependabot action picks those up. We'd like to do something like dependabot/dependabot-core#6160 (comment) but with GH hosted runners and hoped that the custom image feature would make this possible.

[varunsh-coder]

I was able to do this using

- name: Set env variables
  run: |
       echo "ENV1=true" | sudo tee -a /etc/environment

I did notice that these env variables are available to steps that run on the runner host, but not to steps that run in a container job.

[audunsolemdal]

I am trying to optionally support setting snapshot in my workflow templates

Essentially by default I want no snapshot, but at times I would like it to be settable. Currently it seems that this is not possible, as when snapshot is set, it does not support a null or empty value

e.g.

 snapshot: ${{ fromJson(inputs.snapshot_config || '{}') }}

ends up with "Required property is missing: image-name"

while

 snapshot: ${{ fromJson(inputs.snapshot_config || '') }}

or

 snapshot: ${{ fromJson(inputs.snapshot_config || null) }}

end up with syntax errors

Is this possible somehow?

[audunsolemdal]

Anecdotally speaking it appears by workflows do steps which take a long time in a quicker fashion now (e..g. azure/login@v2 seems quicker)
However, I would have expected the "Set up job" step to be able to skip preloaded/installed Github Actions, but it seems these steps are not stored in the snapshot. Is this intentional?

E.g.

...
Prepare all required actions
Getting action download info
Download action repository 'actions/download-artifact@v4' (SHA:d3f86a106a0bac45b974a628896c90dbdf5c8093)
Download action repository 'azure/login@v2' (SHA:a457da9ea143d694b1b9c7c869ebb04ebe844ef5)
Download action repository 'azure/webapps-deploy@v2' (SHA:122b7ec46017e53a3f71e3a027d67550a1641f5e)

I would expect these steps to be redundant

[sumokadet]

Can't get it to work. Any generated custom images do not show up for me in Organization / Enterprise custom images pages, so there is no information about if custom images have been generated. They just state There are no custom images available. I assume visibility of unsuccesful snapshot processes will be introduced during the preview.

I triggered it on a windows-2025 larger runner, and the action log says that it has sent the request.

> Create custom image:

Request written to: C:\actions-runner\.snapshot\request.json
This request will be processed after the job completes. You will not receive any feedback on the snapshot process within the workflow logs of this job.
If the snapshot process is successful, you should see a new image with the requested name in the list of available custom images when creating a new GitHub-hosted Runner.

[jukkatupamaki]

The steps I followed to get Custom image generation working:

1. Go to Your organization -> Settings -> Actions -> Runners -> New Runner dialog
2. Create a larger runner image with Custom image generation enabled, let's call this generator, use e.g. Ubuntu latest
3. Create a workflow that installs something to the runner e.g.

name: Build custom image

on:
  push:
    branches:
      - main
    paths:
      - ".github/workflows/build-custom-image.yml"

jobs:
  build-custom-image:
    name: Build custom image
    runs-on: generator # <-- THIS POINTS TO THE RUNNER VM WITH THE CUSTOM IMAGE GENERATION ENABLED
    snapshot: custom-image # <-- THIS IS THE NAME OF THE GENERATED CUSTOM IMAGE ONCE THIS WORKFLOW PASSES
  
    # Do something here, install stuff, etc. These should be preserved in the generated image
    # so that other workflows using the generated image do not have to install the stuff again.
    steps:
      - name: Setup Node.js
        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version: "24.3.0"

4. Once the above workflow passes, it takes a while until the custom-image can be used - so wait 5-15 minutes...
5. Go to Your organization -> Settings -> Actions -> Runners -> New Runner dialog.
6. Add a name for the new runner e.g. custom-image-8core, choose the same OS you used with the generator runner; in our case Ubuntu latest
7. Now you should see the custom-image available in the Image section of the form. Choose the Custom tab, and pick the custom-image from the list. Finish other settings and create the runner.
8. Now you need a workflow that uses the image:

name: Use custom image

on:
  push:
    branches:
      - main
    paths:
      - ".github/workflows/use-custom-image.yml"

jobs:
  use-custom-image:
    name: Use custom image
    runs-on: custom-image-8core # <-- THIS POINTS TO THE NEW RUNNER IMAGE THAT USES THE custom-image SNAPSHOT

    steps:
      - name: Do something useful
        run: node --version # should print 24.3.0?

This is how I understood it works, and got the custom image running in a workflow. Not sure about the details though, and AI tools like Claude Code offer no help as the feature is so new. Good luck!

[dinoz0rg]

That's a really interesting update! It sounds like a fantastic way to streamline workflows and improve security and cost-efficiency on GitHub. The ability to pre-install all the necessary tools and dependencies is a huge time saver, and the lifecycle management features seem really valuable for maintaining a secure and compliant environment. I especially like the emphasis on enterprise-grade customization. Thanks for sharing this!