GitHub Actions runners are in private preview. Contact support to request access.
runs-on label. A sandbox keeps its disk between runs, can run on Spot, and replaces the caches and builders other runner vendors provide. This page covers what to change so jobs use those safely.
Copy this prompt into your coding agent in the repository containing your GitHub Actions workflows:
Move this repository's workflows to Ravion runners.
Checklist
Work through every job in.github/workflows.
Decide which jobs move
Move every Linux job, whatever it runs on today. Leave these on their current runner, and say why:- macOS, Windows and GPU jobs. Sandboxes are x86_64 Linux.
- ARM jobs that push container images, because a sandbox would build them for
linux/amd64. Count registry logins and scripts or targets named for pushing an image as pushing. Other ARM jobs, such as tests, move to sandboxes. To keep a job on ARM, use an EC2 label. runs-onthat comes from the matrix or another value only known at run time. If an expression just picks between literal labels, replace each Linux label inside it and keep the expression.- Jobs that call a reusable workflow. Migrate the jobs in the reusable workflow’s file instead.
- Jobs whose vendor setup can’t be removed safely. See Make changes for your current runner.
Replace runs-on
- Put your execution environment’s ID in
ee. Keep CPU, memory, disk anddisk_cacheonauto; don’t carry the old runner’s size over. - Make
idunique to the job: the run ID, the run attempt, the workflow file name and the job ID (ci-testfor jobtestinci.yml). For a matrix job, add-${{ strategy.job-index }}; joined matrix values can collide. If a reusable workflow is called more than once in the same run, add a value each caller passes in, such as an input, because both calls share everything else. - Replace the whole value, including
self-hostedand vendor labels. Ifruns-onis a YAML alias shared with jobs that don’t move, give the moved job its own value.
Decide whether a job is interruptible
Interruptible jobs can run on Spot hosts and restart from the beginning if their host is lost. Setinterruptible=true only when running the whole job twice is harmless.
- Not interruptible: jobs that publish, release or deploy, or could leave something half-changed:
npm publish,docker push,git push,gh release create,terraform apply,kubectl apply,prisma migrate deploy,goreleaser, release actions and deploy actions. Every job in a workflow triggered by releases, tags orrelease*branches is also not interruptible. So is any job you can’t classify. - Interruptible: tests, lint, builds that don’t push,
terraform plan, and AI review jobs such asanthropics/claude-code-action. Posting comments, updating pull requests and uploading artifacts or caches are safe to repeat.
environment: by itself doesn’t decide it either way. Read the scripts the job calls.
Make changes for your current runner
Ravion runners serve the Actions cache, keep the disk between runs and provide Docker and Buildx, so most vendor actions become unnecessary. Swap forks of standard actions for the standard action, and remove vendor cache, disk and builder setup. When you swap an action, drop inputs the standard one doesn’t accept. Agents: apply every tab whose runner appears in the repository.- GitHub-hosted
- Blacksmith
- Depot
- Namespace
- RunsOn
- Others
Remove disk-freeing actions such as
jlumbroso/free-disk-space and easimon/maximize-build-space, unless a later step reads their outputs. Automatic sizing gives the job the disk it needs. GitHub larger runners for Linux move like any other job.Vendor Docker builders
Remove a vendor’s Docker builder setup only if the default Buildx builder can do the same job. Leave the job on its current runner if a build setsbuilder or outputs, targets a platform other than linux/amd64, uses Bake, exports its cache to the vendor’s registry, or a script runs docker buildx create or use, or the vendor’s CLI.
Narrow .next caches
An actions/cache step that caches all of .next restores the last build’s output over the newer one on the kept disk. When its key doesn’t change with the source, change that path to .next/cache, the Next.js build cache. Leave the step alone if another step reads its outputs, such as cache-hit to skip next build, or another step uses the same key.
Keep ignored files at checkout
actions/checkout runs git clean -ffdx by default, which deletes the node_modules and build output the disk cache restored. Add clean: false:
environment:, or check that the tree is clean, for example with git status --porcelain or git diff --exit-code.
Make steps work on a kept workspace
Each run starts with the files the job’s last run left, so steps that expect an empty folder can fail from the second run on. Make them work either way, for example:
Also check the scripts each job calls for steps that exit when a path exists, append to files they expect to be empty, or collect files with a pattern such as
dist/** or reports/*.xml. Delete only those paths first. Don’t delete the whole workspace or turn off the disk cache: that throws away the speedup.
AWS credentials
A Ravion job’s AWS role has no permissions by default. Jobs that used ECR or other AWS services through their old runner’s instance role need GitHub OIDC, and ECR jobs need the login steps in Amazon ECR. Docker containers in the job, includingservices: and container:, can’t reach the job’s credentials. Creating an IAM role changes your AWS account, so list it as a follow-up if you can’t do it.
Fix checkout depth and cache keys
- Shallow checkout. Change
fetch-depth: 0to1when the job doesn’t use git history. Keep it for jobs that compute versions or changelogs, rungit describe, diff against a base branch, or use tools likechangesetsornx affected. - Keys that never restore. Add
restore-keysto anactions/cachekey built fromgithub.shaorgithub.run_id, using the key’s stable prefix, so later runs restore the most recent entry. - Keys that never change. Fix
hashFilespatterns that only search the repository root, such ashashFiles('**.ts'), tohashFiles('**/*.ts').
Report optional speedups
Don’t remove explicit cache steps as part of the migration, such asactions/cache, Swatinem/rust-cache or type=gha Docker caches. The disk cache may make them redundant, but other runners, cold disks or other jobs may still need them. Report the ones that look redundant so they can be decided separately.
After the migration
- Check that every workflow still parses, no job IDs changed, and only the moved jobs’
runs-onchanged. - The first run on each branch starts with a cold cache.
- If a job fails, it’s most likely a tool GitHub’s image has and Ravion’s image doesn’t. Install it with a
setup-*action or arunstep.
Hit a bug, or something in this guide that didn’t work or was unclear? Report it with
ravion bug or ravion feedback. Include the repository, workflow, job and the run’s URL. See Report bugs and feedback. For urgent issues, also email support@ravion.com.Next steps
Runners
Labels, sizing and requirements.
Caching
Disk cache, Actions cache and artifacts.