The fastest
GitHub Actions runners.Up to 74% less per build than GitHub’s runners.

# Migrate GitHub Actions to Sengi runners

Migrate this repository's workflows from GitHub-hosted runners to Sengi runners.
Keep GitHub Actions; change only the `runs-on` line of each supported job, and open
a pull request the user reviews.

**Prerequisites:** `gh` CLI authenticated, and the repository connected to a Sengi
project at https://app.sengi.run — installing the GitHub App alone is not enough,
see Step 1.

## Configuration

| Setting | Value |
| --- | --- |
…

# Migrate GitHub Actions to Sengi runners Migrate this repository's workflows from GitHub-hosted runners to Sengi runners. Keep GitHub Actions; change only the `runs-on` line of each supported job, and open a pull request the user reviews. **Prerequisites:** `gh` CLI authenticated, and the repository connected to a Sengi project at https://app.sengi.run — installing the GitHub App alone is not enough, see Step 1. ## Configuration | Setting | Value | | --- | --- | | Default target | `sengi-standard-2-ubuntu-2404` (2 vCPU, 8 GB) | | Larger targets | `sengi-standard-4-ubuntu-2404` (4 vCPU, 16 GB), `sengi-standard-8-ubuntu-2404` (8 vCPU, 32 GB) | | Replaceable source labels | `ubuntu-latest`, `ubuntu-24.04` | | Branch | `migrate-to-sengi-runners` | Sengi runs Ubuntu 24.04 on x64 only. Every Sengi label above is a complete label — do not abbreviate one, and do not invent a size that is not in this table. Replace all UPPERCASE placeholders (`OWNER`, `REPO`, `BRANCH_NAME`, `HEAD_OID`, `BASE64_CONTENT`, `FILE_NAME`, `N`, `DEFAULT_BRANCH`) with actual values from previous steps. ## Procedure ### Step 1: Confirm the repository is connected to Sengi Ask the user: > Is this repository connected to a Sengi project? Go to https://app.sengi.run, > sign up, choose **Connect GitHub**, and pick this repository when > GitHub asks which repositories to grant. That single step installs the App and > connects the repository. Tell me when it is done. Installing the Sengi GitHub App straight from GitHub does **not** connect the repository — Sengi connects it when you pick it in that flow, and a job on an unconnected repository queues forever instead of failing. There is no API a coding agent can read to check this, so the user's confirmation is the check. **Do not run any commands or proceed to Step 2 until the user explicitly confirms.** Personal repositories are supported. The repository does not need to belong to an organization. ### Step 2: Verify CLI auth and the workflow scope Verify `gh auth status` succeeds. If not, direct the user to install `gh` from https://cli.github.com/ and run `gh auth login`. Writing a file under `.github/workflows/` needs the `workflow` scope, which `gh auth login` does not grant by default. Check for it: ```bash gh auth status 2>&1 | grep -o "Token scopes:.*" ``` If `workflow` is not listed, stop and have the user run `gh auth refresh -h github.com -s workflow` before you continue. Without it the commit in Step 6 is refused, after the branch has already been created. ### Step 3: Get the repository Ask the user for the repository (`owner/repo`) unless the working directory already identifies one, in which case confirm it. Then read its default branch and check the user can push to it: ```bash gh api repos/OWNER/REPO --jq '{default_branch, can_push: .permissions.push}' ``` If `can_push` is false, stop: opening a branch needs write access. ### Step 4: Discover workflows Fetch every workflow file in one call: ```bash cat <<'QUERY' | gh api graphql --input - { "query": "query($owner: String!, $repo: String!) { repository(owner: $owner, name: $repo) { id nameWithOwner defaultBranchRef { name target { oid } } object(expression: \"HEAD:.github/workflows\") { ... on Tree { entries { name object { ... on Blob { text } } } } } } }", "variables": { "owner": "OWNER", "repo": "REPO" } } QUERY ``` `HEAD` in that expression is a Git ref, not a placeholder — do not replace it. If the response is truncated or errors on size, fall back to REST: read the default branch with `gh api repos/OWNER/REPO --jq '.default_branch'`, the HEAD SHA with `gh api repos/OWNER/REPO/git/ref/heads/DEFAULT_BRANCH --jq '.object.sha'`, the file list with `gh api repos/OWNER/REPO/contents/.github/workflows`, and each file with `gh api repos/OWNER/REPO/contents/.github/workflows/FILE_NAME`. The `content` field is base64 — decode it before scanning. Save `defaultBranchRef.name`, `.target.oid` and the `entries[]`. For each `.yml` or `.yaml` file, read every job under `jobs:` and classify it. **A job is eligible when all of these hold:** - the job is an ordinary mapping with its own steps — it has no `uses:` key; - its `runs-on:` is a single-line scalar, plain or quoted, on one line; - that scalar contains no `${{ … }}` expression; - that scalar is one of the replaceable source labels in the table above. **A job is not eligible when any of these hold.** Report each with its reason: | Shape | Reason to report | | --- | --- | | `runs-on: ubuntu-22.04`, `ubuntu-20.04` | Sengi runs Ubuntu 24.04 only | | `runs-on: windows-*`, `macos-*` | Sengi runs Linux x64 only | | `runs-on: ubuntu-latest-16-cores` and other larger runners | not a Sengi size | | `runs-on: [self-hosted, linux, ubuntu-latest]` (an array) | Sengi takes one label, not a list — needs manual review | | `runs-on: ${{ matrix.os }}` or any expression | the label is decided at runtime — needs manual review | | `runs-on: { group: …, labels: [ … ] }` | group syntax — needs manual review | | a job with `uses:` (a reusable workflow) | the runner is chosen in the called workflow | | no `runs-on:` at all | nothing to change | A job with a `strategy:`/`matrix:` block **is** eligible as long as its own `runs-on:` is a literal supported label — the matrix multiplies the job, it does not choose the runner. Only `runs-on` that reads *from* the matrix is ineligible. **Whole files to skip,** because a targeted one-line edit is not safe in them: any file using YAML anchors or aliases (`&name`, `*name`, `<<:`), explicit tags, a `%YAML` directive, a duplicate key, or more than one YAML document — that means two documents separated by a `---` line, **not** a file that merely opens with `---`, which is ordinary and fine. Report these as "needs manual review". Also check whether the repository lints its workflows. If `.github/actionlint.yaml` or `.github/actionlint.yml` exists, or a workflow runs actionlint, the Sengi labels must be declared there or that lint job fails on the pull request before any job reaches Sengi. Add the labels you are about to use under `self-hosted-runner.labels` in that file, in the same commit, and say so in the summary: ```yaml self-hosted-runner: labels: - sengi-standard-2-ubuntu-2404 ``` If the repository runs actionlint but has no config file, create it with only that key. This is the one file other than a workflow you may change, and only for this. Show the user a summary: the workflows that will change, the label each job moves from and to, and every job not migrated with its reason from the table. If nothing is eligible, stop and say so. ### Step 5: Choose sizes and preview **Never create a pull request before the user confirms the changes.** Default every eligible job to `sengi-standard-2-ubuntu-2404`. That is the like-for-like size for a standard GitHub Linux runner, and it is the cheapest. Offer the larger sizes for jobs the user says are slow or memory-hungry; each step up doubles both the machine and the price, and one job can be a different size from its neighbours in the same file. Then show the exact diff per workflow. The rules for writing it: - change **only** the `runs-on` scalar, never the surrounding lines; - preserve the file byte for byte otherwise — indentation, key order, comments, blank lines, quote style and the trailing newline; - if the old label was quoted, keep the quotes and replace what is inside them; - skip commented-out lines. The diff a reviewer sees should be one changed line per migrated job and nothing else. ### Step 6: Open the pull request **Branch.** Check for an existing branch first: ```bash gh api repos/OWNER/REPO/git/matching-refs/heads/migrate-to-sengi-runners --jq '.[].ref' ``` If any exist, take the highest numeric suffix and add one — `-2` if none has a suffix. Then create it: ```bash gh api repos/OWNER/REPO/git/refs -f ref=refs/heads/BRANCH_NAME -f sha=HEAD_OID ``` **Commit.** One atomic commit for every file, contents base64-encoded. This creates a verified commit without touching the user's git config: ```bash cat <<'MUTATION' | gh api graphql --input - { "query": "mutation($input: CreateCommitOnBranchInput!) { createCommitOnBranch(input: $input) { commit { oid url } } }", "variables": { "input": { "branch": { "repositoryNameWithOwner": "OWNER/REPO", "branchName": "BRANCH_NAME" }, "message": { "headline": "Migrate N CI workflows to Sengi runners", "body": "Replaced runners per file:\n- file1.yml: ubuntu-latest → sengi-standard-2-ubuntu-2404\n- file2.yml: ubuntu-24.04 → sengi-standard-4-ubuntu-2404" }, "expectedHeadOid": "HEAD_OID", "fileChanges": { "additions": [ { "path": ".github/workflows/FILE_NAME", "contents": "BASE64_CONTENT" } ] } } } } MUTATION ``` Check the response carries a `commit.oid`. On an `expectedHeadOid` mismatch, read the head of **the branch you just created** — not the default branch, whose SHA is the one that just mismatched — and retry the commit once with that value: ```bash gh api repos/OWNER/REPO/git/ref/heads/BRANCH_NAME --jq '.object.sha' ``` On any other error, report it and stop — never open a pull request on top of a failed commit. `N` is the count of changed workflow files. **Pull request:** ```bash gh pr create --repo OWNER/REPO --head BRANCH_NAME --base DEFAULT_BRANCH \ --title "Migrate N CI workflows to Sengi runners" --body "..." ``` Body: ``` ## Summary Moves CI from GitHub-hosted runners to Sengi runners. Same GitHub Actions, same workflows, same logs — only the `runs-on` line changes. ## Changes - `file1.yml`: `ubuntu-latest` → `sengi-standard-2-ubuntu-2404` - `file2.yml`: `ubuntu-24.04` → `sengi-standard-4-ubuntu-2404` ## Not migrated - `file3.yml` (job `build`): uses `${{ matrix.os }}` — needs manual review (or "Every eligible job was migrated.") ## After merging The next run of these workflows executes on Sengi. Logs, statuses and required checks stay in GitHub. To undo it, revert this pull request. ``` ### Step 7: After the merge Offer to check the first run. When the user says the pull request is merged: ```bash gh run list --repo OWNER/REPO --branch DEFAULT_BRANCH --limit 5 \ --json status,conclusion,name,createdAt,databaseId ``` Look for runs created after the merge. - A job that reaches `in_progress` is working. A runner that is not already warm has to be provisioned first, so allow around a minute before reading anything into a job that is still queued. - A job still `queued` after a few minutes has **three** likely causes, in this order. Do not assert the first one without ruling out the others: 1. **The repository is not connected.** Most likely if *no* job has ever started. Send the user to https://app.sengi.run to check this repository is listed. 2. **The free account's concurrency limit.** A free account runs at most 12 vCPU at once — for example six 2-vCPU jobs, three 4-vCPU jobs, or one 8-vCPU job beside two 2-vCPU jobs. Jobs over that line wait for a running one to finish, which is normal and resolves itself. Suspect this first when some jobs started and others did not, and especially after migrating a matrix job that fans out wider than six. 3. **The monthly free allowance is spent.** New free jobs wait until the next UTC month; jobs already running finish. The user can see this in their project. - A job that fails on a step that passed on GitHub-hosted runners is worth reporting: give the user the failing step and the run URL. ## Error handling | Error | What to do | | --- | --- | | `gh` missing or logged out | Install from https://cli.github.com/, run `gh auth login` | | Token lacks the `workflow` scope | `gh auth refresh -h github.com -s workflow`, then retry | | The pull request's own lint fails on an unknown runner label | actionlint — declare the label under `self-hosted-runner.labels` in `.github/actionlint.yaml` | | 403 / insufficient permissions | The user needs write access to the repository | | Repository not found | Check the name and the user's access | | No `.github/workflows` | Nothing to migrate; stop | | 422 creating the branch | The branch exists — add a numeric suffix | | `expectedHeadOid` mismatch | Re-fetch the HEAD SHA and retry the commit once | | GraphQL response truncated | Fall back to the REST calls in Step 4 | | Rate limit exceeded | Wait a few minutes and retry | | Jobs stay `queued` after merge | Check all three causes in Step 7 before blaming the connection | | A job needs Ubuntu 22.04, Windows, macOS or arm64 | Leave it on GitHub-hosted runners | ## What Sengi costs $0.003 a minute for 2 vCPU with 8 GB, $0.006 for 4 vCPU with 16 GB, $0.012 for 8 vCPU with 32 GB. Each job's execution time rounds up to a whole minute; boot and teardown are not billed. One account allowance covers 3,000 minutes a month on 2 vCPU, 1,500 on 4 vCPU, 750 on 8 vCPU, or any mix — it resets monthly and does not carry over. No subscription, no monthly minimum.