Quickstart
Connect GitHub, point one job at your machine and watch it run.
Before you start
Self-service sign-up is not open. Today a machine, its GitHub App and its runner pools are set up by the machine’s operator. The steps below are the part that happens in your GitHub organisation. See pricing for plans and whether checkout is open.
You need:
- A GitHub.com organisation. Runners are registered at the organisation level.
- An organisation owner who can approve a GitHub App installation.
- A workflow job that runs on Linux x64.
Install the GitHub App
Install the machine’s GitHub App on your organisation and select the repositories whose jobs may use the machine. Running jobs needs three permissions: Metadata read, Actions read and organisation Self-hosted runners read and write. The App subscribes to the Workflow job event.
The organisation owner must approve the installation. Permissions added later take effect only after the owner accepts them. Read Secrets and GitHub App permissions for what each permission is used for.
Allow repositories in the runner group
Your machine’s runners register in a runner group of your organisation. In the organisation’s Actions settings, allow that group for the repositories that may use the machine. You can also restrict it to specific workflows.
The group is the control over which code can run on the machine. Keep it as narrow as the work you intend to move.
Change runs-on for one job
Start with one job that does not deploy anything. Change one line:
jobs:
test:
runs-on: battleship-ubuntu-latest
timeout-minutes: 20
permissions:
contents: read
steps:
- run: 'printf "Runner: %s\n" "$RUNNER_NAME"'battleship-ubuntu-latest is 4 vCPU, 12 GiB of memory and 20 GB of disk, the size that follows ubuntu-latest. GitHub sends the job to your machine when the job’s repository is allowed in the runner group. Runner sizes and labels lists the other sizes.
If your organisation restricts a runner group to chosen repositories and you want the workflow to name that group, write the group and the label together:
runs-on:
group: enginebox-ci
labels: battleship-ubuntu-latestenginebox-ci is an example group name; use the group configured for your machine.
Move a workflow with your agent
A coding agent can make the same change for you. Give it this prompt in the repository. It is the prompt the Copy prompt button on the home page copies:
Move this repository's GitHub Actions jobs to Battleship (https://thebattleship.dev).
1. Read every workflow in .github/workflows.
2. For each job that runs on a GitHub-hosted Linux runner (for example `runs-on: ubuntu-latest`), change `runs-on` to `battleship-ubuntu-latest`. Leave the steps exactly as they are.
3. Do not change macOS or Windows jobs, reusable workflows you cannot see, or any job you are unsure about. List those and say why.
4. Show me the diff before committing. Do not push or open a pull request until I say so.
Setup guide: https://thebattleship.dev/docs/quickstart/The prompt asks for the one-line runs-on change in your Linux jobs only, and for the diff before anything is committed. Read the diff as you would any other change to a workflow.
Watch the first job
Push the change or run the workflow manually. The job appears in the Actions tab like any other. While a runner starts, GitHub shows the job as queued; it then runs and reports its result and logs to GitHub.
If the job stays queued, check that the repository is allowed in the runner group, that every label in runs-on belongs to your pool, and that the machine has a free slot. Queueing and capacity explains the reasons a job waits. Machines shows where to see what the machine has free.
What your existing steps can expect
Each job runs as a non-root user in a new virtual machine made from a prepared image with the official runner installed. Standard runner images are prepared with passwordless sudo for that user, as on GitHub-hosted Linux runners, so steps such as sudo apt-get install work.
Docker-based actions and steps need an image with Docker inside the virtual machine. The machine’s own Docker socket is never given to a job. Setup actions still download any tool version the image does not include.
The Smart Workspaces profile is stricter: it supports neither sudo installs nor Docker jobs.
Move more jobs, or move back
Once the first job passes, change runs-on for the next jobs. Run a job that is known to fail as well, so you see failures reported correctly. To return a job to GitHub-hosted runners, restore its previous runs-on. Nothing else in the workflow changes.
Once several jobs have moved, Usage shows how much of the machine they book.
Sign in
Already have an account? Sign in. We email you a one-time code; there is no password. The same button is at the top of every page of this guide.