amika in a job’s runs-on, and GitHub runs that job on a new Amika rig.
The rest of the workflow does not change. Steps, actions/checkout, secrets,
logs and pull request checks all stay in GitHub.
runs-on select the
provider or host, the preset, the size and the snapshot.
How it works
- GitHub queues the job and sends a webhook to the Amika Runners GitHub App.
- Amika checks the job’s labels. If they are not valid, Amika refuses the job and reports the reason in GitHub (see Refused jobs).
- Amika creates a new rig and starts the official GitHub Actions runner on it. The runner is ephemeral: it registers on the repository, takes one job and exits.
- The runner runs the job. GitHub shows the logs and the result, as for any runner.
- When the job ends, Amika deletes the rig, or keeps it if the job’s labels say so (see Keep a rig after a job).
Connect the Runners App
Runners use a separate GitHub App, Amika Runners. It needs the repository permission Administration: write to register runners. The main Amika GitHub App does not ask for this permission, so you only grant it if you use runners.- Open app.amika.dev/settings/github-actions.
- Click Connect GitHub Actions.
- On GitHub, install the App on the repositories that should run jobs on Amika. You must be an admin of each repository that you select.
- GitHub returns you to Amika, and the page shows the connected account.
Amika registers runners on each repository, not on the GitHub organization.
Choose where a job runs
With onlyamika, the job runs on your organization’s default provider, with
the coder-plus-docker preset and that provider’s default size. Add labels to
change this:
Rules:
- Labels are not case-sensitive.
- Each
amika.*label can occur once per job. amika.host.*andamika.provider.*cannot be used together.amika.snapshot.*andamika.preset.*cannot be used together. The snapshot already sets what the rig has.macoswith no preset or snapshot selects themacos-coderpreset.linuxwith no preset or snapshot selectscoder-plus-docker.- With a snapshot and no host or provider label, the job runs where the snapshot lives.
- Any other label is a custom label. Amika passes it to the runner unchanged.
A custom label must not start with
amika.. - Amika has no Windows rigs. A job with
windowsis refused.
Keep a rig after a job
By default, Amika deletes the rig when the job ends. To examine a failed job, keep its rig with a behavior label:on-successapplies to jobs that succeed, are cancelled or are skipped.on-failureapplies to jobs that fail or time out. A job whose result Amika does not learn within an hour counts as failed.stoppedkeeps the rig stopped.activestarts it again, and the rig’s normal auto-stop applies.auto-deletesets how long a kept rig stays after it stops.timeoutlimits how long the runner can run. The job’s owntimeout-minutesstill applies, but Amika cannot read it. If a job setstimeout-minutesabove 12 hours, also setamika.timeout.*.- A runner that took no job always deletes its rig.
What a runner rig has
- The rig has no repository clone. Use
actions/checkout, as on any runner. - Amika puts no credentials on the rig: no agent credentials, no organization secrets, no GitHub token and no Amika API key. The job gets its credentials from GitHub, as the workflow says.
- The
coder-plus-dockerpreset gives Docker, the tools of thecoderpreset, and passwordlesssudo. It does not have every tool of GitHub’subuntu-latestimage. actions/setup-node,actions/setup-python,actions/setup-goand the othersetup-*Actions work. The runner sets a writable tool cache for them.- macOS rigs use the
macos-coderpreset. GitHub’s macOS runners do not have Docker either.
amika.snapshot.<name>.
Runner rigs are named gha-<repository>-<suffix>. Members of your
organization can see them and connect to them like other rigs. Runner rigs
count as rig usage. Rigs on your own hosts cost nothing extra.
Forks and untrusted code
Amika never runs code from a fork on a rig. A fork author can copy any label, so Amika does not rely on labels. It refuses:- jobs for pull requests from a fork;
workflow_runevents whose head repository is a fork;issue_commentevents on pull requests, including pull requests from the same repository;check_run,check_suite,statusanddeployment_statusevents.
Refused jobs
GitHub cannot fail a single queued job. When Amika refuses a job, it adds a failed check run namedAmika runner: <job name> to the job’s commit. The
summary gives the error code, the label at fault and what to change. Cancel
the workflow run in GitHub, or GitHub fails the job after 24 hours.
Capacity and cancellation
- Full or offline host. The job waits in GitHub’s queue. Amika starts the runner when the host has room or comes back online.
- Cancel in GitHub. The runner stops the job and exits. The job counts as
cancelled, so
amika.on-success.*applies. - Stop or delete the rig in Amika. The runner dies, and GitHub fails the job when it loses contact with the runner.
- Amika deploys. A running job keeps running. The runner talks to GitHub directly.