StarSling
Getting Started

Set up with an AI agent

Give your coding agent one stable entrypoint for the complete StarSling setup

View Markdown

Use the Markdown version of this page as the stable setup entrypoint for coding agents:

Read https://docs.starsling.dev/start.md then set me up on StarSling.

The instructions below guide the agent through signing up with GitHub, installing and authenticating the Sling CLI, installing the sling skill, installing the GitHub App, and opening a reviewed runner-migration pull request.

AI prompt
# Onboard a Repository to StarSling

Set up StarSling for the user's repository from start to finish: sign the user up with GitHub, install and authenticate the Sling CLI, install the sling skill for the current coding agent, install the StarSling GitHub App from the StarSling dashboard, and migrate the repository's GitHub Actions workflows to StarSling Runners.

Pause whenever the user must approve something in a browser. Do not claim onboarding is complete until `sling doctor --agent` confirms the environment, the migration pull request has been created, and the StarSling GitHub App is installed. If the installation is only pending organization owner approval, onboarding is not finished: say so, and do not call it complete until an owner approves. If the Sling CLI cannot run on this machine (Step 3), `sling doctor --agent` is not required: still complete the migration and the App installation, and tell the user which Sling steps were skipped.

## Configuration

**Branch:** `migrate-starsling-runners`

**Label reference:** Before mapping any runner, fetch the current StarSling label reference:

```bash
curl -fsSL https://docs.starsling.dev/configuration/label-reference.md
```

It is the source of truth for which StarSling labels exist: OS versions, vCPU sizes, GPU labels, and the label recommended for `ubuntu-latest`. Only choose a target label that appears in it. If you cannot fetch it, tell the user, map only `ubuntu-latest`, `ubuntu-26.04`, and `ubuntu-24.04` to `starsling-ubuntu-26.04`, `starsling-ubuntu-26.04`, and `starsling-ubuntu-24.04`, and skip every sized label.

**Runner mapping:**

- This is a provider-only migration. The target must have the same Ubuntu version, CPU architecture, and vCPU count as the source, and no GPU unless the source has one. The only exceptions are GitHub's standard runners and `ubuntu-latest`, below. Treat a Linux label with no ARM marker (such as `arm` or `arm64`) as x64. If the label reference has no exact match, skip the label and flag it for manual review.
- Leave labels that already start with `starsling-` unchanged.
- GitHub's standard runners (`ubuntu-latest`, `ubuntu-26.04`, `ubuntu-24.04`) have 2 vCPU on private and internal repositories and 4 vCPU on public ones. Map them to the 4-vCPU StarSling label (no size suffix) in both cases. On a private or internal repository, say in the preview and the PR body that each job moves from 2 to 4 vCPU. On a public repository, say that GitHub's standard runners are free for public repositories, so StarSling minutes are a new cost. For every target, show its price per minute from the label reference.
- Map `ubuntu-latest` to the label the reference recommends for it. On GitHub, `ubuntu-latest` may still resolve to an older Ubuntu version for some repositories; in that case the migration is also an OS upgrade. Say so in the preview and the PR body, and ask the user to run the workflows before merging.
- When a source label explicitly names an Ubuntu version, preserve it, whatever the provider or label format (for example `2404` means Ubuntu 24.04).
- A label from another provider must state both its Ubuntu version and its vCPU count (for example `blacksmith-8vcpu-ubuntu-2404`). If either is missing, or you cannot tell whether a number is the vCPU count (for example `8x16` or a bare `-8`), skip the label. Never fall back to a default size.
- The organization's own runners are not migrated. GitHub larger runners have names the organization chooses (for example `ubuntu-latest-8-cores` or `ubuntu-24.04-16core`), so the name does not reliably state the OS version or size, and the runner may carry a static IP or private networking. An organization can even name one `ubuntu-24.04-8`. Before mapping, list the organization's larger runners:

  ```bash
  gh api --paginate orgs/OWNER/actions/hosted-runners --jq '.runners[].name'
  ```

  Skip any label that matches one of these names, and ask the user to check that runner's configuration in their GitHub organization settings. If you cannot list them (usually 403, because only organization owners can), say so in the preview. Do not use the self-hosted runner list to decide this: other providers' runners register as self-hosted runners too. Skip every label that is neither a GitHub standard runner label nor clearly named for another provider (such as a `blacksmith-` prefix), because it may be the organization's own runner.
- Skip macOS, Windows, ARM, and GPU runners from other providers, and Ubuntu versions the reference does not list (such as `ubuntu-22.04`). Flag each one for manual review.

Examples (labels must still be checked against the reference):

| Source | Target |
|---|---|
| `ubuntu-latest` | The label the reference recommends for `ubuntu-latest` (4 vCPU) |
| `ubuntu-24.04` | `starsling-ubuntu-24.04` (4 vCPU) |
| A third-party label that states Ubuntu 24.04 and 8 vCPU | `starsling-ubuntu-24.04-8` |
| A third-party label that states no vCPU count | Not migrated — size unknown |
| `starsling-ubuntu-24.04`, `starsling-ubuntu-24.04-gpu` | Unchanged — already StarSling |
| `ubuntu-latest-8-cores`, `ubuntu-24.04-16core` | Not migrated — the organization's own larger runner; check its configuration |
| `ubuntu-22.04` | Not migrated — no StarSling equivalent |
| `ubuntu-24.04-arm`, `macos-latest`, `windows-latest` | Not migrated — unsupported OS or architecture |
| `[self-hosted, linux, ubuntu-latest]` | Not migrated — targets the organization's own runners |

Replace all UPPERCASE placeholders (`OWNER`, `REPO`, `BRANCH_NAME`, `HEAD_OID`, `BASE64_CONTENT`, `FILE_NAME`, `N`, `DEFAULT_BRANCH`, `CURRENT_AGENT_ID`, `EDITED_FILE`, `PR_BODY_FILE`) with actual values from previous steps.

## Procedure

### Step 1: Sign Up with GitHub

Ask the user to open [Sign up with GitHub](https://runners.starsling.dev/login) in their browser and complete the GitHub sign-in. This creates their StarSling account and lands on the StarSling dashboard. If they already have an account, they just sign in. StarSling Runners work only with repositories owned by a GitHub organization on github.com; Step 2 checks this. Wait for them to confirm before continuing.

### Step 2: Verify GitHub Access and Get the Repository

Verify `gh auth status` succeeds. If `gh` is missing or unauthenticated, direct the user to install it from https://cli.github.com/ and run `gh auth login`. Wait for them to finish before continuing.

Check that `gh auth status` lists the `workflow` scope; changing files in `.github/workflows` requires it. If it is missing, ask the user to run `gh auth refresh -h github.com -s workflow` and wait for them. Fine-grained tokens and GitHub App tokens list no scopes; for those, continue, and treat a permissions error in Create PR as this cause.

If the current checkout's `origin` remote is a GitHub repository, suggest it: "Should I use `OWNER/REPO`?" Otherwise, ask the user for the repository (`owner/repo`). StarSling supports repositories on github.com only. If the repository is on another host (GitHub Enterprise Server or a `*.ghe.com` domain), stop and explain this.

Then run:

```bash
gh api repos/OWNER/REPO --jq '.owner.type, .visibility'
```

If the owner type is `User` rather than `Organization`, stop and explain: "StarSling Runners only work with GitHub organization repositories. You can create a free organization at https://github.com/account/organizations/new." Save the visibility (`public`, `private`, or `internal`) for the runner mapping.

### Step 3: Install the Sling CLI

First run `command -v sling`. If Sling is already installed, run `sling --version` and continue.

The CLI supports Apple Silicon macOS and x64 glibc Linux. On another platform, tell the user the Sling CLI cannot be installed here, skip Steps 3 to 5, and continue with Step 6. The workflow migration only needs `gh`.

If Sling is missing on a supported platform, tell the user you are about to run the official installer, and run it once they agree:

```bash
curl -fsSL https://runners.starsling.dev/cli/install.sh | sh
```

After installation, confirm both `command -v sling` and `sling --version` succeed.

### Step 4: Install the sling skill

Determine the Skills CLI identifier for the coding agent currently running this prompt, such as `claude-code`, `codex`, or `cursor`. Before using project scope, compare the current checkout's `origin` remote with `OWNER/REPO`. If they match, install the sling skill for that agent in the current project:

```bash
npx skills add starslingdev/skills --skill sling --agent CURRENT_AGENT_ID --yes
```

Verify it appears for the current agent:

```bash
npx skills list --agent CURRENT_AGENT_ID
```

Also confirm that the install path the installer printed is inside the checkout of `OWNER/REPO`. `skills list` reports the project the command ran from, so it passes even when the skill was installed into a different directory.

If the checkout does not match `OWNER/REPO`, do not install into the unrelated project. Ask the user to open a checkout of the target repository, or ask whether they want a global installation instead. With their approval, install and verify globally:

```bash
npx skills add starslingdev/skills --skill sling --agent CURRENT_AGENT_ID --global --yes
npx skills list --agent CURRENT_AGENT_ID --global
```

If you cannot determine the current agent identifier, ask the user which Skills CLI identifier to use (for example `claude-code`). Do not run the installer without `--agent` and `--yes`: it prompts interactively, and you cannot answer those prompts. If the user prefers, give them the command without those flags to run in their own terminal.

### Step 5: Authenticate and Verify Sling

The browser is already signed in to StarSling from Step 1, so the user only confirms the device code.

If the user's terminal and the coding agent share the same machine and user account, ask the user to run `sling login` in their own terminal and complete the GitHub browser approval. Do not run it yourself in this case. If the agent runs on a separate host or in a container whose credentials are not shared with the user's terminal, run `sling login` (without `--agent`) in the agent's CLI environment in the background, with its output redirected to a file, because it does not exit until the user approves. Read the device code and approval URL from that file, relay them to the user, wait for them to approve it in their browser, and poll `sling whoami --agent` until it succeeds. Never use `sling login --agent`. In either case, wait for approval before continuing, then run:

```bash
sling doctor --agent
sling whoami --agent
```

Read every doctor check. Exit `0` means the environment is healthy; exit `10` means a real check failed and still returns the checks. Resolve actionable failures before continuing. Advisory `version`, `auto_update`, or `agent_skill` checks do not make the environment unhealthy. Compare `local.org.slug` from `sling whoami --agent` with `OWNER`. If they differ, run `sling org switch OWNER --agent`, then run `sling whoami --agent` again and verify `local.org.slug` matches before continuing. If the switch exits `2`, read the organizations it lists:

- `OWNER` is not listed: this is expected when the StarSling GitHub App is not yet installed on `OWNER`, because StarSling only creates the organization once the App is installed. Do not ask the user to pick another organization, and do not treat a failing doctor `org` check as a blocker for this reason. Continue with Step 6, and finish this organization check there once the App is installed.
- `OWNER` is listed under a different slug, or you cannot tell: show the user the organizations it lists and ask which one to use.

### Step 6: Install the StarSling GitHub App

Check whether the App is installed:

```bash
gh api --paginate orgs/OWNER/installations --jq '.installations[] | select(.app_slug == "starslingdev") | .repository_selection'
```

- `all`: the App can access every repository in the organization. Tell the user and continue.
- `selected`: the App is installed for some repositories. Ask the user to confirm that `REPO` is one of them. If it is not, ask them to add `REPO` in the organization's GitHub settings under GitHub Apps, then confirm.
- No output: the App is not installed.
- An error (usually 403, because only organization owners can list installations): you cannot tell. Ask the user.

When the App is not installed or you cannot tell, send the user to the [StarSling dashboard](https://runners.starsling.dev/dashboard). If they do not have a StarSling account yet, they first [sign up with GitHub](https://runners.starsling.dev/login). An organization appears on the dashboard as its own card only once the App is installed on it, so `OWNER` may not have a card yet. Ask them to choose "Install GitHub App" (on the "Connect your first organization" card, or through "Connect another organization" if other organizations are already connected), pick `OWNER` on GitHub, and give the App access to `REPO`. If the dashboard offers "Continue with `OWNER`", the App is already installed and they choose that to finish connecting it. You cannot see the dashboard or the App installation status yourself, so ask the user what happened:

- Installed: the dashboard shows `OWNER` with "GitHub App installed", and the App has access to `REPO`. Continue.
- Pending owner approval: the user does not have permission to install the App on `OWNER`, so GitHub sent an installation request that an organization owner must approve. GitHub says so, and the dashboard shows "Ask your GitHub organization owner to approve the installation." Do not stop. Continue and open the migration pull request; merging it is what moves the repository's CI onto StarSling. Tell the user plainly that StarSling jobs, including this pull request's own checks for workflows that run on it, will sit queued until an owner approves the installation, and ask them to send the request to an organization owner. Put this line at the top of the PR body's "After Merging" section: "**Do not merge until an organization owner approves the StarSling GitHub App installation request.**" You never merge the pull request.
- Not installed, no request sent, or anything else unclear: do not proceed. Ask them to install the App from the dashboard.

If an open migration pull request from an earlier run carries the "Do not merge until an organization owner approves" line and the App is now installed, remove that line from its body (`gh pr view URL --json body`, edit the body in a file, then `gh pr edit URL --body-file PR_BODY_FILE`), and tell the user the pull request can be merged once they have reviewed it. Then ask whether they still want a fresh migration run; if not, stop here, since that pull request already carries the migration.

**Unless the check returned `all`, do not proceed until the user explicitly confirms the App is installed with access to the target repository, or that the installation request is pending owner approval.**

**Sling organization check:** If Step 5 deferred the organization check and the App is now installed, run `sling org switch OWNER --agent` and `sling whoami --agent` and verify `local.org.slug` matches, then run `sling doctor --agent` again and resolve any remaining actionable failures. If the installation is pending owner approval, skip this check: StarSling creates the organization only after an owner approves. If Step 3 skipped the Sling CLI, skip it too.

### Step 7: Discover Workflows

Fetch all workflow files in one API 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 isTruncated byteSize } } } } } } }",
  "variables": { "owner": "OWNER", "repo": "REPO" }
}
QUERY
```

Note: `HEAD` in the GraphQL expression is a Git ref, not a placeholder — do not replace it.

If any entry has `isTruncated: true`, or the response errors due to size, fall back to the REST API. Never edit or commit a truncated file: the commit replaces each file with exactly the content you send. Fall back as follows: fetch the default branch and HEAD SHA via `gh api repos/OWNER/REPO --jq '.default_branch'` and `gh api repos/OWNER/REPO/git/ref/heads/DEFAULT_BRANCH --jq '.object.sha'`, then fetch workflow file names via `gh api repos/OWNER/REPO/contents/.github/workflows` and each file individually via `gh api repos/OWNER/REPO/contents/.github/workflows/FILE_NAME`. The response `content` field is base64-encoded — decode it before scanning for `runs-on:` values.

Save `defaultBranchRef.name` (or REST default branch), `.target.oid` / HEAD SHA, and workflow `entries[]`. Scan each `.yml`/`.yaml` file for:
- direct `runs-on:` string values that match the runner-mapping rules, and
- matrix-driven patterns (e.g., `runs-on: ${{ matrix.os }}`) where the matrix values match the runner-mapping rules.

Skip these and list each under "Not migrated" with its reason, so nothing is dropped silently:
- **Shared workflows.** A file triggered by `workflow_call` is a reusable workflow. Changing its runners also changes them for every workflow that calls it, including callers in other repositories that the GitHub App may not cover.
- **Jobs that call a reusable workflow** (`uses:` instead of `steps:`). They have no `runs-on` of their own; the called workflow sets the runner.
- **Any `runs-on` that is not a plain label or a hardcoded matrix value:** inputs (`${{ inputs.runner }}`), variables (`${{ vars.RUNNER }}`), ternaries, `fromJSON(...)`, YAML aliases (`*name`), and the anchors they point to (`&name`): changing an anchor's label also changes every job that uses its alias.

Get the default branch's required status checks, because migrating a matrix renames its checks (for example `test (ubuntu-latest)` becomes `test (starsling-ubuntu-26.04)`):

```bash
gh api repos/OWNER/REPO/rules/branches/DEFAULT_BRANCH --jq '.[] | select(.type == "required_status_checks") | .parameters.required_status_checks[].context'
gh api repos/OWNER/REPO/branches/DEFAULT_BRANCH/protection/required_status_checks --jq '.contexts[]'
```

A 404 on the second call means there is no classic branch protection. If a call returns 403, you cannot see the required checks: say so in the preview, and warn that check names for migrated matrix jobs will change.

For each workflow, note whether this migration PR exercises it. A `pull_request` workflow whose branch and path filters match runs on this PR. A `push` workflow whose branch and path filters match the migration branch also runs on that branch, because the migration commit is a push. A workflow triggered only by `pull_request_target`, `schedule`, `workflow_run`, `workflow_dispatch`, `release`, or a `push` filter that excludes the migration branch uses the default branch's copy, so it first runs on StarSling after merge.

Show the user a summary including:
- Workflows that will be migrated and the exact source → target mapping for each runner label
- The source and target OS version, architecture, vCPU size, and target price per minute for every mapping, plus any size or cost change required by the runner-mapping rules
- Whether each migrated workflow runs on this PR, or first runs after merge
- Everything listed as "Not migrated", with the reason

If no direct or matrix-backed runners match, show the "Not migrated" list, then stop.

### Step 8: Preview Changes

**Never create a PR without the user confirming changes first.**

Show what will change per workflow:
- Replace matching runners in `runs-on:` string values with the target selected by the runner-mapping rules (preserve quotes/comments)
- Replace matching matrix values as described under **Expressions** below
- Skip commented lines

**Provider-only migration:** This migration must preserve any explicitly named Ubuntu version, CPU architecture, and vCPU size. Do not combine a provider migration with an OS, architecture, or size change. The only exceptions are GitHub's standard runners, which move to 4 vCPU, and `ubuntu-latest`, which follows its own mapping rule above, including the OS-upgrade warning. State both in the preview. If an exact mapping is unavailable, skip the label and flag it for manual review.

**Complex `runs-on` patterns:**
- **Array syntax** (e.g., `runs-on: [linux, ubuntu-latest]`): If the array contains `self-hosted`, skip it and flag it for manual review, because it targets the organization's own runners. Otherwise replace only the matching label within the array; do not collapse it to a single string
- **Group/labels syntax** (e.g., `runs-on: { group: ..., labels: [...] }`): Skip and flag for manual review
- **Expressions** (`${{ matrix.os }}`): If `runs-on` uses a matrix value and the matrix values are hardcoded runner labels, first search the whole workflow file for each label you would replace. Inside the job's `strategy.matrix` block, the label may appear in the value list and in `include` and `exclude` entries; replace it in all of them, so they stay consistent. If the label appears anywhere outside that block (for example `if: matrix.os == 'ubuntu-latest'`, or a job `name:`), do not migrate that workflow: renaming the label would silently change those conditions. Skip it and flag it for manual review, naming the lines that reference the label. Also skip it if a required status check name contains the label. Otherwise, replace the labels and flag the workflow for manual verification. If the matrix values come from other expressions, skip entirely and flag for manual review. Every other expression is skipped as described in Discover Workflows

**YAML fidelity:** Change ONLY the `runs-on` and matrix values. Preserve the original file exactly: same indentation, key ordering, comments, blank lines, and trailing newline. The PR diff should show only the runner label changes.

### Step 9: Create PR

**Existing migration PR:** First check for an open PR from an earlier run:

```bash
gh pr list --repo OWNER/REPO --state open --json headRefName,url --jq '.[] | select(.headRefName | startswith("migrate-starsling-runners")) | .url'
```

If any exist, show them all to the user and ask whether to close them and open a new one, or stop. Do not open a second migration PR without their answer.

**Branch:** Before creating, check for existing branches: `gh api repos/OWNER/REPO/git/matching-refs/heads/migrate-starsling-runners --jq '.[].ref'`. If any exist, find the highest numeric suffix and increment by 1 (if none have a suffix, use `-2`). Then create: `gh api repos/OWNER/REPO/git/refs -f ref=refs/heads/BRANCH_NAME -f sha=HEAD_OID`.

**Atomic commit** — all files in one commit, contents base64-encoded. Write each edited workflow to a file and encode it from that file without line breaks, so trailing newlines survive and the JSON string stays on one line:

```bash
base64 < EDITED_FILE | tr -d '\n'
```

Build the mutation JSON with a tool that escapes strings correctly (such as `jq`), not by pasting into a shell string.

```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 StarSling Runners",
        "body": "Replaced runners per file:\n- file1.yml: ubuntu-latest → starsling-ubuntu-26.04\n- file2.yml: ubuntu-24.04 → starsling-ubuntu-24.04"
      },
      "expectedHeadOid": "HEAD_OID",
      "fileChanges": {
        "additions": [
          { "path": ".github/workflows/FILE_NAME", "contents": "BASE64_CONTENT" }
        ]
      }
    }
  }
}
MUTATION
```

Verify the response contains a valid `commit.oid`. If the call fails, or its result is unclear (for example a timeout), the commit may still have landed. Read the branch before doing anything else:

```bash
gh api repos/OWNER/REPO/git/ref/heads/BRANCH_NAME --jq '.object.sha'
```

- Still `HEAD_OID`: no commit landed. Delete the branch so no empty branch is left behind, then report the error and stop:

  ```bash
  gh api -X DELETE repos/OWNER/REPO/git/refs/heads/BRANCH_NAME
  ```

- Any other SHA: a commit landed, so never delete the branch. If that commit's headline is your `Migrate N CI workflows to StarSling Runners` message, continue to the PR. Otherwise something else changed the branch (this is also what an `expectedHeadOid` mismatch means): report and stop.

Do not create a PR against a failed commit.

A permissions error on a workflow file usually means the token lacks the `workflow` scope (see Verify GitHub Access and Get the Repository).

**Commit message:** The headline should read `Migrate N CI workflows to StarSling Runners` where N is the count of modified workflow files (`.yml` + `.yaml`). List each file and the runner label(s) replaced in the body, as shown in the example above.

**PR:** Write the body to a file, for example with a quoted heredoc (`cat > PR_BODY_FILE <<'EOF'`) or your own file-editing tool, so no shell runs its backticks or expands `${{ }}`. Then run `gh pr create --repo OWNER/REPO --head BRANCH_NAME --base DEFAULT_BRANCH --title "Migrate N CI workflows to StarSling Runners" --body-file PR_BODY_FILE`. Use this body structure:

```
## Summary
Migrates CI workflows to [StarSling Runners](https://docs.starsling.dev) for faster builds and AI-powered optimizations.

## Changes
- `file1.yml`: `ubuntu-latest` → `starsling-ubuntu-26.04` (2 → 4 vCPU, $X/min)
- `file2.yml`: `ubuntu-24.04` → `starsling-ubuntu-24.04` (2 → 4 vCPU, $X/min)

## Size and cost
(Every vCPU or cost change from the runner-mapping rules, and the OS-upgrade note for `ubuntu-latest`.)

## Not exercised by this PR
- `release.yml`: runs on `release` — first runs on StarSling after merge
(or "Every migrated workflow runs on this PR.")

## Not Migrated
- `file3.yml`: Uses `${{ matrix.os }}` — requires manual review
(or "All workflows migrated successfully.")

## After Merging
(If the installation is pending owner approval, put this first: **Do not merge until an organization owner approves the StarSling GitHub App installation request.**)

Workflows will automatically run on StarSling Runners. Check the [StarSling dashboard](https://runners.starsling.dev/dashboard) to confirm the organization shows "GitHub App installed". To change which repositories it can access, use the organization's GitHub settings under GitHub Apps.
```

**Never push to or merge into `DEFAULT_BRANCH`.** After the pull request is created, give the user its link, then continue with Monitor.

### Step 10: Monitor (Optional)

Always ask this once the pull request is open, before you finish: ask the user if they'd like help monitoring after merge. If yes, explain they can return after merging and you'll check with:

```bash
gh run list --repo OWNER/REPO --branch DEFAULT_BRANCH --limit 5 --json status,conclusion,name,createdAt
```

Look for runs created after the merge. If any show `queued` for more than 2 minutes, suggest checking the StarSling dashboard (https://runners.starsling.dev/dashboard): the organization should show "GitHub App installed". If it does not and the user sent an installation request, an organization owner has not approved it yet. To change repository access, use the organization's GitHub settings under GitHub Apps.

## Error Handling

| Error | Solution |
|-------|----------|
| `gh` not found or not logged in | Install from https://cli.github.com/, run `gh auth login` |
| `sling` not found | Run the official installer from Step 3, then verify `sling --version` |
| Unsupported CLI platform | The Sling CLI requires Apple Silicon macOS or x64 glibc Linux — skip Steps 3 to 5, tell the user, and continue at Step 6 |
| Sling default org differs from `OWNER` | Run `sling org switch OWNER --agent`. If `OWNER` is not listed because the App is not installed yet, continue to Step 6 and switch after installing. Otherwise ask the user which organization to use |
| Sling not authenticated | Ask the user to run `sling login` and complete the browser approval |
| sling skill missing for the current agent | Re-run Step 4 with the correct Skills CLI agent identifier |
| sling skill installed outside the target checkout | Remove it with `npx skills remove --skill sling --agent CURRENT_AGENT_ID --yes` from that directory, then re-run Step 4 from the checkout of `OWNER/REPO` |
| Label reference unavailable | Map only `ubuntu-latest`, `ubuntu-26.04`, and `ubuntu-24.04` to their base StarSling labels, and skip sized labels |
| 403 / insufficient permissions | User needs write access to the repository — check collaborator status or org role |
| App not installed | Open https://runners.starsling.dev/dashboard, choose "Install GitHub App", and install it on the organization with access to the repository |
| Installation pending owner approval | The user cannot install the App on the organization themselves. Continue and open the PR, tell the user jobs (including the PR's own checks) stay queued until an owner approves, ask them to send the request to an owner, and mark the PR "Do not merge until an organization owner approves the StarSling GitHub App installation request" |
| Personal repo (owner type `User`) | StarSling requires an org repo — create one at https://github.com/account/organizations/new |
| Repository not found | Check repo name and permissions |
| No workflows found | Ensure `.github/workflows/` exists |
| Runner not available after merge | Check https://runners.starsling.dev/dashboard: the organization should show "GitHub App installed". If not, install it, or have an owner approve a pending request. Change repository access in the organization's GitHub settings under GitHub Apps |
| Rate limit exceeded | Wait a few minutes and retry |
| 422 on branch creation | Branch exists — append a number suffix |
| `expectedHeadOid` mismatch | The new branch changed after you created it — do not delete it; report and stop |
| Commit fails on `.github/workflows` permissions | Token lacks the `workflow` scope — if the branch still points to `HEAD_OID`, delete it; ask the user to run `gh auth refresh -h github.com -s workflow`, then retry from Create PR |
| Repository not on github.com | StarSling supports github.com only — stop |
| Open migration PR already exists | Show it and ask the user before opening another |
| `${{ matrix.os }}` / complex `runs-on` | Require manual review — determined at runtime |
| GraphQL response or a file truncated (`isTruncated`) | Fall back to REST API for individual file fetches |