Migrate GitHub Actions with your coding agent

# 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 card, no subscription, no monthly minimum.