Skip to main content
GitHub Actions runners are in private preview. Contact support to request access.
Moving a job to Ravion runners takes more than a new 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.

Open in Cursor

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-on that 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.
Don’t rename moved jobs or workflow files. Automatic sizing starts a job at the size of the runner it last ran on, and learns its sizes, by workflow file and job name.

Replace runs-on

  • Put your execution environment’s ID in ee. Keep CPU, memory, disk and disk_cache on auto; don’t carry the old runner’s size over.
  • Make id unique to the job: the run ID, the run attempt, the workflow file name and the job ID (ci-test for job test in ci.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-hosted and vendor labels. If runs-on is 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. Set interruptible=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 or release* 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 as anthropics/claude-code-action. Posting comments, updating pull requests and uploading artifacts or caches are safe to repeat.
A GitHub 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.
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 sets builder 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:
Keep the default for jobs that publish, deploy or release, use a GitHub 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, including services: 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: 0 to 1 when the job doesn’t use git history. Keep it for jobs that compute versions or changelogs, run git describe, diff against a base branch, or use tools like changesets or nx affected.
  • Keys that never restore. Add restore-keys to an actions/cache key built from github.sha or github.run_id, using the key’s stable prefix, so later runs restore the most recent entry.
  • Keys that never change. Fix hashFiles patterns that only search the repository root, such as hashFiles('**.ts'), to hashFiles('**/*.ts').

Report optional speedups

Don’t remove explicit cache steps as part of the migration, such as actions/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-on changed.
  • 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 a run step.
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.