# What is StarSling? (/)



## Introduction

Developers typically spend 20-30% of their time on annoying eng tasks outside of their code editor:

* Fixing exceptions
* Patching failed builds and flaky tests
* Investigating and remediating incidents
* Optimizing database and application performance

These tasks are spread out across many different developer tools and workflows. StarSling is unifying these tools and bringing AI agents to the rest of the software development lifecycle (SDLC), starting with continuous integration (CI). Learn more at [starsling.dev](https://starsling.dev).

## StarSling Runners: self-driving CI

StarSling Runners are an AI-native drop-in replacement for `ubuntu-latest` and `ubuntu-24.04` that make your GitHub Actions up to 6x faster. StarSling agents do continuous deep scans of your CI setup and ship optimizations to keep speeding up your builds and save you minutes.

## Quick Start

2,000 free minutes for your first month — no credit card required.

### Step 1: Install the StarSling GitHub App

<Callout type="info">
  [Install StarSling GitHub App](https://github.com/apps/starslingdev)
</Callout>

<Callout type="warn">
  StarSling Runners are not available for personal repositories, only GitHub organizations. If you install the GitHub App in a personal repo, StarSling Runners will not pick up the jobs. [Learn why →](/troubleshooting/common-issues#personal-repositories-not-supported)
</Callout>

### Step 2: Update Your Workflow(s)

Paste this prompt into any AI coding agent (Claude Code, Cursor, Codex, etc.):

<div className="[&_.fd-scroll-container]:max-h-[200px]">
  ````markdown title="AI prompt"
  # Migrate GitHub Actions to StarSling Runners

  Migrate the user's workflows from GitHub-hosted runners to StarSling Runners.

  **Prerequisites:** `gh` CLI authenticated, [StarSling GitHub App](https://github.com/apps/starslingdev) installed on the repo's org.

  ## Configuration

  **Target:** `starsling-ubuntu-24.04` | **Branch:** `migrate-starsling-ubuntu-2404`

  **Source runners to replace:** `ubuntu-latest`, `ubuntu-24.04`

  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 GitHub App Installation

  Ask the user: "Have you installed the [StarSling GitHub App](https://github.com/apps/starslingdev) on your org? It's required for runners to pick up jobs after merge. If not, please install it first and let me know when you're ready."

  **Do not run any commands or proceed to Step 2 until the user explicitly confirms the app is installed.**

  ### Step 2: Verify CLI Auth

  Verify `gh auth status` succeeds. If not, direct the user to install from https://cli.github.com/ and run `gh auth login`.

  ### Step 3: Get Repository

  Ask the user for the repository (`owner/repo`). Then run `gh api repos/OWNER/REPO --jq '.owner.type'`. If the result is `User` (not `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."

  ### Step 4: 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 } } } } } } }",
    "variables": { "owner": "OWNER", "repo": "REPO" }
  }
  QUERY
  ```

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

  If the response is truncated or errors due to size, fall back to the REST API: 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 matching supported runners, and
  - matrix-driven patterns (e.g., `runs-on: ${{ matrix.os }}`) where the matrix values include supported runner labels.

  Show the user a summary including:
  - Workflows that will be migrated and which runners are being replaced
  - Any Ubuntu runners NOT in the supported list (e.g., `ubuntu-22.04`, `ubuntu-20.04`, larger runners like `ubuntu-latest-16-cores`) listed as "Not migrated — unsupported runner label"

  If no direct or matrix-backed supported runners match, stop.

  ### Step 5: Preview Changes

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

  Show what will change per workflow:
  - Replace supported runners in `runs-on:` string values with `starsling-ubuntu-24.04` (preserve quotes/comments)
  - Replace matching `runner:`/`os:` values in `matrix.include` sections
  - Skip commented lines

  **Complex `runs-on` patterns:**
  - **Array syntax** (e.g., `runs-on: [self-hosted, linux, ubuntu-latest]`): Only replace the matching label within the array; do not collapse to a single string
  - **Group/labels syntax** (e.g., `runs-on: { group: ..., labels: [...] }`): Skip and flag for manual review
  - **Expressions** (`${{ matrix.os }}`, ternary/conditional): If `runs-on` uses `${{ matrix.os }}` and the matrix values are hardcoded runner labels, replace the labels in the matrix definition and flag the workflow for manual verification. If the matrix values come from other expressions, skip entirely and flag for manual review

  **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 6: Create PR

  **Branch:** Before creating, check for existing branches: `gh api repos/OWNER/REPO/git/matching-refs/heads/migrate-starsling-ubuntu-2404 --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:

  ```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-24.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 mutation returned an `expectedHeadOid` mismatch, re-fetch the HEAD SHA (Step 4) and retry the commit once. For any other errors, report and stop — do not create a PR against a failed commit.

  **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** via `gh pr create --repo OWNER/REPO --head BRANCH_NAME --base DEFAULT_BRANCH --title "Migrate N CI workflows to StarSling Runners" --body "..."` with this body structure:

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

  ## Changes
  - `file1.yml`: `ubuntu-latest` → `starsling-ubuntu-24.04`
  - `file2.yml`: `ubuntu-24.04` → `starsling-ubuntu-24.04`

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

  ## After Merging
  Workflows will automatically run on StarSling Runners. Ensure the [StarSling GitHub App](https://github.com/apps/starslingdev) is installed with access to this repo.
  ```

  ### Step 7: Monitor (Optional)

  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 GitHub App installation and repo access at https://github.com/apps/starslingdev.

  ## Error Handling

  | Error | Solution |
  |-------|----------|
  | `gh` not found or not logged in | Install from https://cli.github.com/, run `gh auth login` |
  | 403 / insufficient permissions | User needs write access to the repository — check collaborator status or org role |
  | App not installed | Install from https://github.com/apps/starslingdev |
  | 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 | Verify app has repo access at https://github.com/apps/starslingdev |
  | Rate limit exceeded | Wait a few minutes and retry |
  | 422 on branch creation | Branch exists — append a number suffix |
  | `expectedHeadOid` mismatch | Re-fetch HEAD SHA and retry the commit |
  | `${{ matrix.os }}` / complex `runs-on` | Require manual review — determined at runtime |
  | GraphQL response truncated | Fall back to REST API for individual file fetches |
  ````
</div>

See the [full quickstart](/getting-started/quickstart) for a manual `runs-on` label swap and other migration options.

## What You Get

### Up to 6x Faster CI Runs

* **[30% faster hardware](/runners/compute-sizing)**
* **Unlimited concurrency** to minimize queue times

### AI-Powered Optimizations

* **[Optimizations](/ai-powered-features/optimizations)** — AI agents scan your workflows to continuously improve CI speed ([see real examples](https://starsling.dev/#ai-prs)). For new accounts, AI-powered optimization PRs are only available to customers on paid plans and are not enabled by default.

Teams running StarSling see this compound in production:

<Cards>
  <Card title="Mastra" href="https://starsling.dev/customers/mastra" description="Slowest test suite ~30m → ~5m; queue time ~8x shorter. 14 agent PRs." />

  <Card title="Better Auth" href="https://starsling.dev/customers/better-auth" description="E2E ~2x faster; ~20,000 CI minutes saved every month. 3 agent PRs." />

  <Card title="Partcl" href="https://starsling.dev/customers/partcl" description="Heaviest CI jobs 13x cheaper per run; queue time 16x shorter." />
</Cards>

### Up to 33% Lower Cost

Every StarSling runner is cheaper than GitHub's equivalent larger runner — up to 33%.

| Runner                      | vCPU | Memory | GitHub Price | StarSling Price | Savings |
| --------------------------- | ---- | ------ | ------------ | --------------- | ------- |
| `starsling-ubuntu-24.04-2`  | 2    | 8 GB   | $0.006/min   | $0.004/min      | **33%** |
| `starsling-ubuntu-24.04`    | 4    | 16 GB  | $0.012/min   | **$0.008/min**  | **33%** |
| `starsling-ubuntu-24.04-8`  | 8    | 32 GB  | $0.022/min   | $0.016/min      | **27%** |
| `starsling-ubuntu-24.04-16` | 16   | 64 GB  | $0.042/min   | $0.032/min      | **24%** |
| `starsling-ubuntu-24.04-32` | 32   | 128 GB | $0.082/min   | $0.064/min      | **22%** |
| `starsling-ubuntu-24.04-64` | 64   | 256 GB | $0.162/min   | $0.128/min      | **21%** |

*GitHub prices reference [GitHub Actions runner pricing](https://docs.github.com/en/billing/reference/actions-runner-pricing) for Linux x64 larger runners (as of 2026-05-06).*

**2,000 free minutes for your first month** — no credit card required to start.

## Comparison to GitHub

| Feature                   | GitHub-hosted | StarSling           |
| ------------------------- | ------------- | ------------------- |
| Queue time                | 30-60s        | **Under 30s (P50)** |
| Build speed               | Baseline      | **Up to 6x faster** |
| Optimization improvements | Manual        | **AI-powered**      |

## Get Started

<Cards>
  <Card title="Quickstart" href="/getting-started/quickstart" description="Get running in under 5 minutes" />

  <Card title="Instance Types" href="/runners/instance-types" description="Runner specs, labels, and compute" />

  <Card title="Pricing" href="/pricing" description="2,000 free minutes for your first month" />
</Cards>


# Optimizations (/ai-powered-features/optimizations)



StarSling's AI agents continuously perform deep scans of your workflows and open PRs to optimize your CI speed. See [real examples of AI-authored PRs](https://starsling.dev/#ai-prs) or browse the [customer case studies](https://starsling.dev/customers).

<Callout type="info">
  For new accounts, AI-powered optimization PRs are only available to customers on paid plans and are not enabled by default.
</Callout>

## How It Works

StarSling monitors your CI workflows and identifies opportunities to improve performance, reliability, and efficiency. When an optimization is found, StarSling opens a pull request with the suggested changes and an explanation.

## What Gets Optimized

### Caching

Detect missing or misconfigured caches and add them automatically.

* [Better Auth](https://starsling.dev/customers/better-auth): fixed a Turborepo cache that wasn't hitting between runs and cached Playwright browser installs.
* [Partcl](https://starsling.dev/customers/partcl): cached build artifacts across shards.

### Dependency installation

Suggest faster install strategies (e.g., frozen lockfiles, parallel installs).

### Build steps

Identify redundant or slow steps that can be parallelized or removed.

* [Mastra](https://starsling.dev/customers/mastra): sharded the E2E kitchen-sink suite across 3 parallel jobs.
* [Partcl](https://starsling.dev/customers/partcl): parallelized a test suite the team had never had time to split.

### Test reliability

Replace fixed `sleep` calls with real readiness checks and add service healthchecks.

* [Mastra](https://starsling.dev/customers/mastra): swapped blind sleeps for polling across MongoDB and Chroma and added Docker healthchecks.
* [Better Auth](https://starsling.dev/customers/better-auth): added Docker Compose healthchecks.

### Workflow structure

Recommend job splitting, matrix strategies, and dependency ordering.

### Runner configuration

Flag suboptimal runner labels or resource usage.

* [Partcl](https://starsling.dev/customers/partcl): right-sized the heaviest jobs from 64-core down to 8-core machines.

## How Optimizations Are Delivered

1. StarSling analyzes your workflow runs and configuration
2. When an optimization is identified, a PR is opened with the changes
3. Each PR includes an explanation of what changed and why
4. You review and merge at your own pace

> "Within a day of migrating to StarSling Runners, their agents opened up a PR that literally made our Rust CI tests 2x faster!"
>
> — Vamshi Balanaga, Co-founder & CTO, [Partcl](https://starsling.dev/customers/partcl)

## See It In Action

Real CI optimizations StarSling agents have shipped, with measured before/after numbers:

<Cards>
  <Card title="Mastra — 6x faster tests" href="https://starsling.dev/customers/mastra" description="14 agent-authored PRs cut the slowest test suite from ~30m to ~5m and shortened queue time ~8x." />

  <Card title="Better Auth — 2x faster E2E" href="https://starsling.dev/customers/better-auth" description="Three agent optimization PRs halved per-job E2E runtime, saving ~20,000 CI minutes per month." />

  <Card title="Partcl — 13x cheaper per run" href="https://starsling.dev/customers/partcl" description="Build caching, test parallelization, and 64→8-core right-sizing made the heaviest CI jobs 13x cheaper and cut queue time 16x." />
</Cards>

See all [StarSling case studies →](https://starsling.dev/customers).


# GitHub App Permissions (/configuration/github-app-permissions)



The StarSling GitHub App requests specific permissions to provide runner functionality and AI-powered optimizations.

## Required Permissions

### Repository Permissions

| Permission           | Access       | Purpose                                                                                                           |
| -------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------- |
| **Actions**          | Read & Write | Register runners and receive workflow job events                                                                  |
| **Checks**           | Read & Write | Report runner assignment and job status                                                                           |
| **Code**             | Read & Write | Read workflow and source files for AI optimization scanning, and commit proposed changes to pull request branches |
| **Pull requests**    | Read & Write | Open AI optimization pull requests                                                                                |
| **Workflows**        | Read & Write | Propose changes to `.github/workflows` files via pull requests                                                    |
| **Deployments**      | Read         | Repository context for AI optimization analysis                                                                   |
| **Discussions**      | Read         | Repository context for AI optimization analysis                                                                   |
| **Issues**           | Read         | Repository context for AI optimization analysis                                                                   |
| **Metadata**         | Read         | Basic repository information (required by all GitHub Apps)                                                        |
| **Pages**            | Read         | Repository context for AI optimization analysis                                                                   |
| **Repository hooks** | Read         | Receive webhook deliveries and view hook metadata                                                                 |
| **Security events**  | Read         | Repository context for AI optimization analysis                                                                   |

### Organization Permissions

| Permission              | Access       | Purpose                                               |
| ----------------------- | ------------ | ----------------------------------------------------- |
| **Self-hosted runners** | Read & Write | Register and manage runners at the organization level |
| **Members**             | Read         | Organization membership for access management         |
| **Organization hooks**  | Read         | Receive webhook deliveries and view hook metadata     |

## Permission Details

### Actions (Read & Write)

**Why:** StarSling needs to register self-hosted runners with your repository and receive webhook events when workflows start.

**What we do:**

* Register ephemeral runners
* Remove runners after job completion
* Receive `workflow_job` webhooks

**What we don't do:**

* Modify your workflow files outside of a pull request you review (see [Workflows](#workflows-read--write))
* Access workflow run logs (except for optimization scanning)

### Checks (Read & Write)

**Why:** To report runner assignment status and provide visibility into job execution.

**What we do:**

* Update check status when runner is assigned
* Report runner health information

### Code (Read & Write)

**Why:** To read workflow definitions and repository source code for AI optimization scanning, and to commit proposed changes to pull request branches.

**What we do:**

* Read workflow definitions for optimization scanning
* Read source code files in your repository to provide context for AI optimization suggestions
* Process file contents in memory during analysis
* Commit optimization changes to a new branch and open a pull request

**What we don't do:**

* Persist source code beyond the temporary 24-hour AI analysis window (see [Data Handling](/security/data-handling))
* Push to your default branch or existing branches — changes are isolated to pull request branches for your review

### Pull Requests (Read & Write)

**Why:** To open AI optimization pull requests against your repository.

**What we do:**

* Open pull requests with optimization changes and explanations

**What we don't do:**

* Approve or merge pull requests
* Close or modify PR metadata

### Workflows (Read & Write)

**Why:** To propose optimizations to your GitHub Actions workflow files.

**What we do:**

* Include updated `.github/workflows/*.yml` files in optimization pull requests

**What we don't do:**

* Change workflow files outside of a pull request you review and merge

### Read-Only Permissions

The remaining read scopes — deployments, discussions, issues, pages, security events, repository and organization hooks, and organization members — give StarSling's agents repository and organization context for optimization analysis and let the app receive the webhook events that trigger runner provisioning. None of these are used to modify your repositories or organization.

## Data Access Summary

| Data Type                 | Accessed | Stored      | Retained |
| ------------------------- | -------- | ----------- | -------- |
| Workflow events           | Yes      | No          | No       |
| Workflow definitions      | Yes      | No          | No       |
| Source code (AI analysis) | Yes      | Temporarily | 24 hours |
| Secrets                   | No       | No          | No       |
| Environment variables     | No       | No          | No       |

For a full breakdown of access, storage, and retention, see [Data Handling](/security/data-handling).

## Security Practices

### Secrets Passthrough

Your GitHub secrets are passed directly to the runner by GitHub. StarSling never sees, stores, or logs secret values.

### Ephemeral Runners

Each job runs in its own single-use, hardware-isolated microVM that's destroyed after the run — there's nothing for a later job or a fork pull request to persist on or reach. This is the same isolation as GitHub-hosted runners. See [Isolation](/security/data-handling#isolation) for details.

### Encrypted Transit

All communication uses TLS 1.3. Webhooks are verified using GitHub's signature.

## Revoking Access

To remove StarSling:

1. Go to your repository or organization settings
2. Navigate to **Integrations** → **GitHub Apps**
3. Find StarSling and click **Configure**
4. Click **Uninstall**

After uninstalling:

* All runners are immediately deregistered
* No further webhooks are received
* No data is retained beyond 24 hours

<Cards>
  <Card title="Security & Compliance" href="/security/compliance" description="Certifications and security practices" />

  <Card title="Data Handling" href="/security/data-handling" description="How we handle your data" />
</Cards>


# Label Reference (/configuration/label-reference)



StarSling uses structured labels to specify runner configuration. The numeric suffix on each label indicates the vCPU count (e.g. `-8` = 8 vCPU). The label without a suffix is the 4 vCPU default.

## StarSling Labels

| Label                       | OS           | vCPU | Memory | Price per minute |
| --------------------------- | ------------ | ---- | ------ | ---------------- |
| `starsling-ubuntu-24.04-2`  | Ubuntu 24.04 | 2    | 8 GB   | $0.004           |
| `starsling-ubuntu-24.04`    | Ubuntu 24.04 | 4    | 16 GB  | $0.008           |
| `starsling-ubuntu-24.04-8`  | Ubuntu 24.04 | 8    | 32 GB  | $0.016           |
| `starsling-ubuntu-24.04-16` | Ubuntu 24.04 | 16   | 64 GB  | $0.032           |
| `starsling-ubuntu-24.04-32` | Ubuntu 24.04 | 32   | 128 GB | $0.064           |
| `starsling-ubuntu-24.04-64` | Ubuntu 24.04 | 64   | 256 GB | $0.128           |

## GitHub Label Mapping

The default `starsling-ubuntu-24.04` (4 vCPU / 16 GB) replaces these GitHub-hosted runner labels:

| GitHub-hosted Label | StarSling Label          |
| ------------------- | ------------------------ |
| `ubuntu-latest`     | `starsling-ubuntu-24.04` |
| `ubuntu-24.04`      | `starsling-ubuntu-24.04` |

For larger workloads, opt into a bigger size by appending the vCPU suffix (e.g. `starsling-ubuntu-24.04-8`). For cost-sensitive or lightweight jobs, use the 2 vCPU `starsling-ubuntu-24.04-2` label.

## Examples

### Basic Usage

```yaml
jobs:
  build:
    runs-on: starsling-ubuntu-24.04
```

### Drop-in Replacement

```yaml
jobs:
  build:
    # Before: runs-on: ubuntu-latest
    runs-on: starsling-ubuntu-24.04
```

### Larger Size

```yaml
jobs:
  build:
    runs-on: starsling-ubuntu-24.04-8
```

## Invalid Labels

These will fail to match a runner:

| Invalid Label             | Reason                         |
| ------------------------- | ------------------------------ |
| `starsling-ubuntu-22.04`  | Only Ubuntu 24.04 is supported |
| `starsling/ubuntu-24.04`  | Use hyphens, not slashes       |
| `starsling-ubuntu-latest` | Use `starsling-ubuntu-24.04`   |

<Cards>
  <Card title="Instance Types" href="/runners/instance-types" description="Full runner specifications" />

  <Card title="Compute Specifications" href="/runners/compute-sizing" description="Hardware and performance details" />

  <Card title="Migration Guide" href="/configuration/migration-guide" description="Update your workflows" />
</Cards>


# Migration Guide (/configuration/migration-guide)



Migrate your workflows from GitHub-hosted runners to StarSling in minutes.

## Step 1: Install the StarSling GitHub App

Install the StarSling GitHub App in your organization:

<Callout type="info">
  [Install StarSling GitHub App](https://github.com/apps/starslingdev)
</Callout>

Grant access to the org repositories where you want to use StarSling Runners.

<Callout type="warn">
  StarSling Runners are not available for personal repositories, only GitHub organizations. If you install the GitHub App in a personal repo, StarSling Runners will not pick up the jobs. [Learn why →](/troubleshooting/common-issues#personal-repositories-not-supported)
</Callout>

## Step 2: Update Your Workflow(s)

### Option A: Use an AI Prompt

Paste this prompt into any AI coding agent (Claude Code, Cursor, Codex, etc.):

<div className="[&_.fd-scroll-container]:max-h-[200px]">
  ````markdown title="AI prompt"
  # Migrate GitHub Actions to StarSling Runners

  Migrate the user's workflows from GitHub-hosted runners to StarSling Runners.

  **Prerequisites:** `gh` CLI authenticated, [StarSling GitHub App](https://github.com/apps/starslingdev) installed on the repo's org.

  ## Configuration

  **Target:** `starsling-ubuntu-24.04` | **Branch:** `migrate-starsling-ubuntu-2404`

  **Source runners to replace:** `ubuntu-latest`, `ubuntu-24.04`

  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 GitHub App Installation

  Ask the user: "Have you installed the [StarSling GitHub App](https://github.com/apps/starslingdev) on your org? It's required for runners to pick up jobs after merge. If not, please install it first and let me know when you're ready."

  **Do not run any commands or proceed to Step 2 until the user explicitly confirms the app is installed.**

  ### Step 2: Verify CLI Auth

  Verify `gh auth status` succeeds. If not, direct the user to install from https://cli.github.com/ and run `gh auth login`.

  ### Step 3: Get Repository

  Ask the user for the repository (`owner/repo`). Then run `gh api repos/OWNER/REPO --jq '.owner.type'`. If the result is `User` (not `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."

  ### Step 4: 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 } } } } } } }",
    "variables": { "owner": "OWNER", "repo": "REPO" }
  }
  QUERY
  ```

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

  If the response is truncated or errors due to size, fall back to the REST API: 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 matching supported runners, and
  - matrix-driven patterns (e.g., `runs-on: ${{ matrix.os }}`) where the matrix values include supported runner labels.

  Show the user a summary including:
  - Workflows that will be migrated and which runners are being replaced
  - Any Ubuntu runners NOT in the supported list (e.g., `ubuntu-22.04`, `ubuntu-20.04`, larger runners like `ubuntu-latest-16-cores`) listed as "Not migrated — unsupported runner label"

  If no direct or matrix-backed supported runners match, stop.

  ### Step 5: Preview Changes

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

  Show what will change per workflow:
  - Replace supported runners in `runs-on:` string values with `starsling-ubuntu-24.04` (preserve quotes/comments)
  - Replace matching `runner:`/`os:` values in `matrix.include` sections
  - Skip commented lines

  **Complex `runs-on` patterns:**
  - **Array syntax** (e.g., `runs-on: [self-hosted, linux, ubuntu-latest]`): Only replace the matching label within the array; do not collapse to a single string
  - **Group/labels syntax** (e.g., `runs-on: { group: ..., labels: [...] }`): Skip and flag for manual review
  - **Expressions** (`${{ matrix.os }}`, ternary/conditional): If `runs-on` uses `${{ matrix.os }}` and the matrix values are hardcoded runner labels, replace the labels in the matrix definition and flag the workflow for manual verification. If the matrix values come from other expressions, skip entirely and flag for manual review

  **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 6: Create PR

  **Branch:** Before creating, check for existing branches: `gh api repos/OWNER/REPO/git/matching-refs/heads/migrate-starsling-ubuntu-2404 --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:

  ```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-24.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 mutation returned an `expectedHeadOid` mismatch, re-fetch the HEAD SHA (Step 4) and retry the commit once. For any other errors, report and stop — do not create a PR against a failed commit.

  **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** via `gh pr create --repo OWNER/REPO --head BRANCH_NAME --base DEFAULT_BRANCH --title "Migrate N CI workflows to StarSling Runners" --body "..."` with this body structure:

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

  ## Changes
  - `file1.yml`: `ubuntu-latest` → `starsling-ubuntu-24.04`
  - `file2.yml`: `ubuntu-24.04` → `starsling-ubuntu-24.04`

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

  ## After Merging
  Workflows will automatically run on StarSling Runners. Ensure the [StarSling GitHub App](https://github.com/apps/starslingdev) is installed with access to this repo.
  ```

  ### Step 7: Monitor (Optional)

  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 GitHub App installation and repo access at https://github.com/apps/starslingdev.

  ## Error Handling

  | Error | Solution |
  |-------|----------|
  | `gh` not found or not logged in | Install from https://cli.github.com/, run `gh auth login` |
  | 403 / insufficient permissions | User needs write access to the repository — check collaborator status or org role |
  | App not installed | Install from https://github.com/apps/starslingdev |
  | 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 | Verify app has repo access at https://github.com/apps/starslingdev |
  | Rate limit exceeded | Wait a few minutes and retry |
  | 422 on branch creation | Branch exists — append a number suffix |
  | `expectedHeadOid` mismatch | Re-fetch HEAD SHA and retry the commit |
  | `${{ matrix.os }}` / complex `runs-on` | Require manual review — determined at runtime |
  | GraphQL response truncated | Fall back to REST API for individual file fetches |
  ````
</div>

### Option B: Manual Update

Change your `runs-on` label from GitHub-hosted to StarSling:

```
starsling-ubuntu-24.04
```

```yaml title="Before"
jobs:
  build:
    runs-on: ubuntu-latest # [!code highlight]
    steps:
      - uses: actions/checkout@v4
      # ... your build steps
```

```yaml title="After"
jobs:
  build:
    runs-on: starsling-ubuntu-24.04 # [!code highlight]
    steps:
      - uses: actions/checkout@v4
      # ... your build steps
```

### Label Mapping

Use `starsling-ubuntu-24.04` to replace any of these GitHub-hosted runner labels:

| GitHub-hosted Label | StarSling Label          |
| ------------------- | ------------------------ |
| `ubuntu-latest`     | `starsling-ubuntu-24.04` |
| `ubuntu-24.04`      | `starsling-ubuntu-24.04` |

## Compatibility Notes

### Fully Compatible

* All `actions/*` official actions
* Matrix strategies
* Caching with `actions/cache`
* Artifacts with `actions/upload-artifact`
* Secrets and environment variables

### Minor Differences

| Feature        | GitHub-hosted          | StarSling              |
| -------------- | ---------------------- | ---------------------- |
| Default shell  | bash                   | bash                   |
| Home directory | `/home/runner`         | `/home/runner`         |
| Work directory | `/home/runner/work`    | `/home/runner/work`    |
| Tool cache     | `/opt/hostedtoolcache` | `/opt/hostedtoolcache` |

### Not Supported

* macOS runners (coming soon)
* Windows runners (coming soon)
* GPU runners (coming soon)

## Rollback

If you need to rollback, simply change the label back:

```yaml
# Rollback to GitHub-hosted
runs-on: ubuntu-latest
```

No other changes required.

## Troubleshooting Migration

### Runner Not Starting

1. Verify the GitHub App is installed
2. Check the label format is correct
3. Ensure your account has available runner capacity

### Slower Than Expected

1. Verify caching is working
2. Check if dependencies are being re-downloaded
3. Use matrix builds to parallelize tests

### Action Compatibility Issues

Most actions work unchanged. If an action fails:

1. Check the action's documentation for self-hosted runner support
2. Ensure required tools are available
3. [Contact support](/troubleshooting/debug-access) if issues persist

<Cards>
  <Card title="Label Reference" href="/configuration/label-reference" description="All available labels" />

  <Card title="Troubleshooting" href="/troubleshooting/common-issues" description="Common issues and fixes" />
</Cards>


# Quickstart (/getting-started/quickstart)



2,000 free minutes for your first month — no credit card required.

## Step 1: Install the StarSling GitHub App

Install the StarSling GitHub App in your organization:

<Callout type="info">
  [Install StarSling GitHub App](https://github.com/apps/starslingdev)
</Callout>

Grant access to the org repositories where you want to use StarSling Runners.

<Callout type="warn">
  StarSling Runners are not available for personal repositories, only GitHub organizations. If you install the GitHub App in a personal repo, StarSling Runners will not pick up the jobs. [Learn why →](/troubleshooting/common-issues#personal-repositories-not-supported)
</Callout>

## Step 2: Update Your Workflow(s)

### Option A: Use an AI Prompt

Paste this prompt into any AI coding agent (Claude Code, Cursor, Codex, etc.):

<div className="[&_.fd-scroll-container]:max-h-[200px]">
  ````markdown title="AI prompt"
  # Migrate GitHub Actions to StarSling Runners

  Migrate the user's workflows from GitHub-hosted runners to StarSling Runners.

  **Prerequisites:** `gh` CLI authenticated, [StarSling GitHub App](https://github.com/apps/starslingdev) installed on the repo's org.

  ## Configuration

  **Target:** `starsling-ubuntu-24.04` | **Branch:** `migrate-starsling-ubuntu-2404`

  **Source runners to replace:** `ubuntu-latest`, `ubuntu-24.04`

  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 GitHub App Installation

  Ask the user: "Have you installed the [StarSling GitHub App](https://github.com/apps/starslingdev) on your org? It's required for runners to pick up jobs after merge. If not, please install it first and let me know when you're ready."

  **Do not run any commands or proceed to Step 2 until the user explicitly confirms the app is installed.**

  ### Step 2: Verify CLI Auth

  Verify `gh auth status` succeeds. If not, direct the user to install from https://cli.github.com/ and run `gh auth login`.

  ### Step 3: Get Repository

  Ask the user for the repository (`owner/repo`). Then run `gh api repos/OWNER/REPO --jq '.owner.type'`. If the result is `User` (not `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."

  ### Step 4: 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 } } } } } } }",
    "variables": { "owner": "OWNER", "repo": "REPO" }
  }
  QUERY
  ```

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

  If the response is truncated or errors due to size, fall back to the REST API: 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 matching supported runners, and
  - matrix-driven patterns (e.g., `runs-on: ${{ matrix.os }}`) where the matrix values include supported runner labels.

  Show the user a summary including:
  - Workflows that will be migrated and which runners are being replaced
  - Any Ubuntu runners NOT in the supported list (e.g., `ubuntu-22.04`, `ubuntu-20.04`, larger runners like `ubuntu-latest-16-cores`) listed as "Not migrated — unsupported runner label"

  If no direct or matrix-backed supported runners match, stop.

  ### Step 5: Preview Changes

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

  Show what will change per workflow:
  - Replace supported runners in `runs-on:` string values with `starsling-ubuntu-24.04` (preserve quotes/comments)
  - Replace matching `runner:`/`os:` values in `matrix.include` sections
  - Skip commented lines

  **Complex `runs-on` patterns:**
  - **Array syntax** (e.g., `runs-on: [self-hosted, linux, ubuntu-latest]`): Only replace the matching label within the array; do not collapse to a single string
  - **Group/labels syntax** (e.g., `runs-on: { group: ..., labels: [...] }`): Skip and flag for manual review
  - **Expressions** (`${{ matrix.os }}`, ternary/conditional): If `runs-on` uses `${{ matrix.os }}` and the matrix values are hardcoded runner labels, replace the labels in the matrix definition and flag the workflow for manual verification. If the matrix values come from other expressions, skip entirely and flag for manual review

  **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 6: Create PR

  **Branch:** Before creating, check for existing branches: `gh api repos/OWNER/REPO/git/matching-refs/heads/migrate-starsling-ubuntu-2404 --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:

  ```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-24.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 mutation returned an `expectedHeadOid` mismatch, re-fetch the HEAD SHA (Step 4) and retry the commit once. For any other errors, report and stop — do not create a PR against a failed commit.

  **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** via `gh pr create --repo OWNER/REPO --head BRANCH_NAME --base DEFAULT_BRANCH --title "Migrate N CI workflows to StarSling Runners" --body "..."` with this body structure:

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

  ## Changes
  - `file1.yml`: `ubuntu-latest` → `starsling-ubuntu-24.04`
  - `file2.yml`: `ubuntu-24.04` → `starsling-ubuntu-24.04`

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

  ## After Merging
  Workflows will automatically run on StarSling Runners. Ensure the [StarSling GitHub App](https://github.com/apps/starslingdev) is installed with access to this repo.
  ```

  ### Step 7: Monitor (Optional)

  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 GitHub App installation and repo access at https://github.com/apps/starslingdev.

  ## Error Handling

  | Error | Solution |
  |-------|----------|
  | `gh` not found or not logged in | Install from https://cli.github.com/, run `gh auth login` |
  | 403 / insufficient permissions | User needs write access to the repository — check collaborator status or org role |
  | App not installed | Install from https://github.com/apps/starslingdev |
  | 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 | Verify app has repo access at https://github.com/apps/starslingdev |
  | Rate limit exceeded | Wait a few minutes and retry |
  | 422 on branch creation | Branch exists — append a number suffix |
  | `expectedHeadOid` mismatch | Re-fetch HEAD SHA and retry the commit |
  | `${{ matrix.os }}` / complex `runs-on` | Require manual review — determined at runtime |
  | GraphQL response truncated | Fall back to REST API for individual file fetches |
  ````
</div>

### Option B: Manual Update

Change your `runs-on` label from GitHub-hosted to StarSling:

```
starsling-ubuntu-24.04
```

### Before

```yaml title=".github/workflows/ci.yml"
jobs:
  build:
    runs-on: ubuntu-latest # [!code highlight]
    steps:
      - uses: actions/checkout@v4
      # ... your build steps
```

### After

```yaml title=".github/workflows/ci.yml"
jobs:
  build:
    runs-on: starsling-ubuntu-24.04 # [!code highlight]
    steps:
      - uses: actions/checkout@v4
      # ... your build steps
```

That's it. Push your changes and watch your builds fly.

## Label Mapping

Use `starsling-ubuntu-24.04` (4 vCPU / 16 GB) to replace these GitHub-hosted runner labels:

| GitHub-hosted Label | StarSling Label          |
| ------------------- | ------------------------ |
| `ubuntu-latest`     | `starsling-ubuntu-24.04` |
| `ubuntu-24.04`      | `starsling-ubuntu-24.04` |

StarSling also offers additional runner sizes (2, 8, 16, 32, and 64 vCPU). See [Instance Types](/runners/instance-types) for the full label reference.

## What's Next?

<Cards>
  <Card title="Security" href="/security" description="Isolation, data handling, and compliance" />

  <Card title="Instance Types" href="/runners/instance-types" description="Full runner specifications" />

  <Card title="Migration Guide" href="/configuration/migration-guide" description="Migrate existing workflows" />
</Cards>


# Tailscale Integration (/integrations/tailscale)



[Tailscale](https://tailscale.com/) is a zero-config VPN that connects your devices, services, and cloud networks using encrypted [WireGuard](https://www.wireguard.com/) tunnels.

By connecting StarSling Runners to your Tailscale network, your CI jobs get secure access to private services — databases, NFS volumes, internal APIs — without exposing them to the public internet or maintaining static IP allow lists.

## Prerequisites

Before you start, make sure you have:

* A [Tailscale account](https://login.tailscale.com) with admin access to the [ACL editor](https://login.tailscale.com/admin/acls/file)
* A GitHub repository with Actions enabled
* Tailscale 1.90.1+ on your tailnet for OIDC (any version for OAuth fallback)

By the end of this guide, you'll have configured:

* A Tailscale tag for your runners
* An OAuth client with OIDC federation
* A GitHub Actions workflow step that connects to your tailnet

## Connecting StarSling Runners to your tailnet

<Steps>
  <Step>
    ### Create a tag in your Tailnet ACLs

    [Tailscale tags](https://tailscale.com/kb/1068/tags) group non-user devices and let you manage access control policies based on device role. Create a tag for your StarSling Runners in the [admin console ACL editor](https://login.tailscale.com/admin/acls/file) by adding it under [`tagOwners`](https://tailscale.com/kb/1337/acl-syntax#tag-owners):

    ```json
    {
      "tagOwners": {
        "tag:starslingdev": ["autogroup:admin"]
      }
    }
    ```

    This tag will be assigned to every StarSling Runner that joins your tailnet. You'll use it in [ACL rules](#granting-access-to-private-services) to control what runners can access.
  </Step>

  <Step>
    ### Create a trust credential

    Go to the [Trust credentials](https://login.tailscale.com/admin/settings/trust-credentials) page in the Tailscale admin console and click **Credential**.

    1. Select **OpenID Connect**
    2. Set **Issuer** to **GitHub** — Tailscale auto-fills the issuer URL
    3. Set **Subject** to match your repository: `repo:<your-org>/<your-repo>:*`
    4. Click **Continue** to reach the **Scopes** page
    5. Expand the **Keys** section, enable **Auth Keys** (Read & Write), and add the tag `tag:starslingdev`
    6. Click **Generate credential**

    Save the **Client ID** and **Audience** values shown after generation — you'll need them in the next step.

    <Callout type="info">
      For the OAuth fallback path, create an **OAuth** credential instead of OpenID Connect. See the **OAuth Client Secret** tab in the next step.
    </Callout>
  </Step>

  <Step>
    ### Add the Tailscale step to your workflow

    <Tabs items={['OIDC (Recommended)', 'OAuth Client Secret']}>
      <Tab value="OIDC (Recommended)">
        OIDC uses short-lived tokens issued by GitHub — no long-lived secrets are stored. Requires Tailscale 1.90.1+.

        Add the following secrets to your GitHub repository (**Settings** > **Secrets and variables** > **Actions** > **Secrets**):

        | Secret               | Value                                 |
        | -------------------- | ------------------------------------- |
        | `TS_OAUTH_CLIENT_ID` | Client ID from the previous step      |
        | `TS_AUDIENCE`        | Audience value from the previous step |

        Then add the Tailscale connection step to your workflow:

        ```yaml title=".github/workflows/ci.yml"
        jobs:
          build:
            runs-on: starsling-ubuntu-24.04 # [!code highlight]
            permissions:
              id-token: write # Required for OIDC
              contents: read
            steps:
              - uses: actions/checkout@v6

              - name: Connect to Tailscale
                uses: tailscale/github-action@v4
                with:
                  oauth-client-id: ${{ secrets.TS_OAUTH_CLIENT_ID }}
                  audience: ${{ secrets.TS_AUDIENCE }}
                  tags: tag:starslingdev

              # Your runner is now on the tailnet.
              # Access any private service allowed by your ACLs.
              - name: Run tests
                run: npm test
        ```
      </Tab>

      <Tab value="OAuth Client Secret">
        If your tailnet doesn't support OIDC, create an **OAuth** credential instead. Go to [Trust credentials](https://login.tailscale.com/admin/settings/trust-credentials), click **Credential**, select the **OAuth** tab, and configure with `auth_keys` (Read & Write) scope and `tag:starslingdev`. Save the **Client ID** and **Client Secret**.

        Add the following secrets to your GitHub repository (**Settings** > **Secrets and variables** > **Actions** > **Secrets**):

        | Secret               | Value               |
        | -------------------- | ------------------- |
        | `TS_OAUTH_CLIENT_ID` | OAuth Client ID     |
        | `TS_OAUTH_SECRET`    | OAuth Client Secret |

        Then add the Tailscale connection step to your workflow:

        ```yaml title=".github/workflows/ci.yml"
        jobs:
          build:
            runs-on: starsling-ubuntu-24.04 # [!code highlight]
            permissions:
              contents: read
            steps:
              - uses: actions/checkout@v6

              - name: Connect to Tailscale
                uses: tailscale/github-action@v4
                with:
                  oauth-client-id: ${{ secrets.TS_OAUTH_CLIENT_ID }}
                  oauth-secret: ${{ secrets.TS_OAUTH_SECRET }}
                  tags: tag:starslingdev

              # Your runner is now on the tailnet.
              # Access any private service allowed by your ACLs.
              - name: Run tests
                run: npm test
        ```

        <Callout type="warn">
          The OAuth client secret is a long-lived credential stored in GitHub. Rotate it periodically — you can regenerate it in the Tailscale admin console and update the GitHub secret without downtime.
        </Callout>
      </Tab>
    </Tabs>

    Your StarSling Runner is now connected to your tailnet as an [ephemeral node](https://tailscale.com/kb/1111/ephemeral-nodes). When the job completes, the node is automatically removed.

    **Verify it works:** Add a step to your workflow to confirm connectivity:

    ```yaml
    - name: Verify Tailscale connection
      run: |
        tailscale status
        tailscale ping <your-tailscale-hostname>
    ```
  </Step>
</Steps>

## Granting access to private services

With runners connected, use [Tailscale ACLs](https://tailscale.com/kb/1337/acl-syntax) to control what they can reach. Runners are tagged with `tag:starslingdev`, which you reference in ACL rules.

### Access a specific service

Grant runners access to a private database by hostname and port:

```json
{
  "acls": [
    {
      "action": "accept",
      "src": ["tag:starslingdev"],
      "dst": ["database-hostname:5432"]
    }
  ]
}
```

### Access a subnet

Using [Tailscale subnet routers](https://tailscale.com/kb/1019/subnets), grant runners access to a VPC or on-premises network:

```json
{
  "acls": [
    {
      "action": "accept",
      "src": ["tag:starslingdev"],
      "dst": ["192.0.2.0/24:5432"]
    }
  ]
}
```

<Callout type="warn">
  Always restrict to specific ports (e.g. `:5432`). Avoid `:*` (all ports) in production — overly broad rules are the most common ACL mistake.
</Callout>

## Security and compliance

StarSling's Tailscale integration is designed for zero-trust CI environments:

* **No stored secrets (OIDC)** — each job receives a short-lived GitHub OIDC token that Tailscale validates directly. No long-lived credentials are stored in GitHub.
* **Ephemeral nodes** — runners are automatically removed from your tailnet when the job completes, leaving no persistent footprint.
* **Audit visibility** — connected runners appear as tagged nodes in the [Tailscale admin console](https://login.tailscale.com/admin/machines) and are recorded in your [tailnet audit logs](https://tailscale.com/kb/1011/log-streaming).
* **Scoped access** — tag-based ACLs enforce least-privilege per job. Runners can only reach services explicitly permitted by your ACL rules.

## Troubleshooting

### Runner can't reach private services

1. **Check the ACL.** Confirm your ACL rules allow `tag:starslingdev` to reach the target service and port. Verify the ACL has been applied in the [admin console](https://login.tailscale.com/admin/acls/file).
2. **Verify the host.** If using an IP, confirm it hasn't changed. If using a MagicDNS hostname, check for stale nodes — run `tailscale status` from the runner to see what's reachable.
3. **Look for stale nodes.** If `tailscale status` shows your target hostname as "offline" alongside a `-2` variant, delete the stale entries from the [Tailscale Admin Console](https://login.tailscale.com/admin/machines).

<Cards>
  <Card title="Tailscale: GitHub CI/CD Guide" href="https://tailscale.com/docs/solutions/connect-github-CICD-workflows-to-private-infrastructure-without-public-exposure" description="Tailscale's guide to connecting GitHub Actions to private infrastructure" />

  <Card title="NFS Mount Example" href="https://github.com/starslingdev/tailscale-mount-example" description="Mount private NFS volumes over Tailscale in GitHub Actions" />

  <Card title="Tailscale ACL Reference" href="https://tailscale.com/kb/1337/acl-syntax" description="Full ACL syntax documentation from Tailscale" />

  <Card title="Instance Types" href="/runners/instance-types" description="Runner specs and labels" />
</Cards>


# Benchmarks (/performance/benchmarks)



StarSling runners can deliver up to 6x faster build times compared to GitHub-hosted runners, depending on workload characteristics. The best way to see the difference is to benchmark your own workflows — the guide below shows how.

## Real-World Results

What StarSling delivered for real teams after they switched `runs-on` — faster runners plus the optimizations StarSling agents shipped and the team merged:

| Repo                                                       | Metric               | GitHub-hosted | StarSling | Improvement      |
| ---------------------------------------------------------- | -------------------- | ------------- | --------- | ---------------- |
| [Mastra](https://starsling.dev/customers/mastra)           | Slowest test suite   | \~30m         | \~5m      | **\~6x faster**  |
| [Mastra](https://starsling.dev/customers/mastra)           | Job queue under load | \~15m         | under 2m  | **\~8x shorter** |
| [Better Auth](https://starsling.dev/customers/better-auth) | E2E runtime per job  | 2m 22s        | 1m 04s    | **\~2x faster**  |

Across all its CI and E2E jobs, Better Auth saves roughly **20,000 CI minutes every month**.

<Callout type="info">
  These are live customer results — each links to its case study with the full methodology and the agent-authored PRs behind the numbers.
</Callout>

## Why StarSling is Faster

### 1. 30% Faster Hardware

| Spec   | GitHub-hosted                 | StarSling        |
| ------ | ----------------------------- | ---------------- |
| CPU    | 4th Gen AMD EPYC<sup>\*</sup> | 5th Gen AMD EPYC |
| Cores  | 4 vCPU                        | 4 vCPU           |
| Memory | 16 GB                         | 16 GB            |

5th Gen AMD EPYC processors deliver \~30% better single-threaded performance over 4th Gen, directly improving build and test execution times.

<small>
  ** Not publicly disclosed by GitHub in [their docs](https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners) but inferred based on publicly available information.*
</small>

### 2. Unlimited Concurrency

No concurrency limits means every job gets a runner quicker, even during peak CI loads.

## Run Your Own Benchmark

Compare your actual workflows side by side — run the same steps on a GitHub-hosted runner and a StarSling runner, then compare the timings:

```yaml title=".github/workflows/benchmark.yml"
jobs:
  github-hosted:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: time npm ci && time npm run build

  starsling:
    runs-on: starsling-ubuntu-24.04
    steps:
      - uses: actions/checkout@v4
      - run: time npm ci && time npm run build
```

<Cards>
  <Card title="Compute Sizing" href="/runners/compute-sizing" description="Choose the right runner size" />

  <Card title="Customer Results" href="https://starsling.dev/customers" description="Before/after numbers from real repos" />
</Cards>


# Pricing (/pricing)



StarSling Runners are:

* **Up to 6x Faster** — faster builds mean fewer minutes billed
* **Up to 33% Cheaper** — save on compute vs GitHub-hosted runners
* **AI-Powered** — continuous AI optimizations of your CI workflows, included at no extra cost on paid plans. For new accounts, AI-powered optimization PRs are only available to customers on paid plans and are not enabled by default.

***

## Pricing

**2,000 free minutes for your first month** to get started. After that, billing is per minute and depends on runner size — from **$0.004/min** (2 vCPU) to **$0.128/min** (64 vCPU). The 4 vCPU default is **$0.008/min**. See the [Compute](#compute) table below for all sizes.

AI-powered optimizations are included with every paid minute — no limits and no add-ons. For new accounts, AI-powered optimization PRs are only available to customers on paid plans and are not enabled by default.

|                         | Free Trial            | Usage-Based                                       | Enterprise                                        |
| ----------------------- | --------------------- | ------------------------------------------------- | ------------------------------------------------- |
| **Price**               | Free                  | $0.004–$0.128/min by runner size                  | Custom                                            |
| **Minutes**             | 2,000 for first month | Pay as you go                                     | Custom                                            |
| **AI Optimization PRs** | —                     | Included; not enabled by default for new accounts | Included; not enabled by default for new accounts |
| **Support**             | Community             | Email                                             | Dedicated                                         |
| **SLA**                 | —                     | 99.99% runner availability                        | 99.99% runner availability                        |

No credit card required to start.

***

## Enterprise

For large organizations needing advanced features and dedicated support.

**Included:**

* Custom minute allocation and volume discounts
* SSO/SAML integration
* Dedicated account manager
* Custom SLAs with contractual guarantees
* Priority incident response (\< 1 hour)
* Quarterly business reviews

**Ideal for:**

* Organizations with 50+ developers
* Monthly CI usage exceeding 50,000 minutes
* Teams requiring compliance certifications (SOC 2 Type II in progress)
* Custom security or data residency requirements

[Book a Demo →](https://cal.com/team/starsling/starsling-founders-chat) · [Contact Sales →](mailto:founders@starsling.dev)

***

## Compute

| Runner                      | vCPU | Memory | Price per Minute |
| --------------------------- | ---- | ------ | ---------------- |
| `starsling-ubuntu-24.04-2`  | 2    | 8 GB   | $0.004           |
| `starsling-ubuntu-24.04`    | 4    | 16 GB  | **$0.008**       |
| `starsling-ubuntu-24.04-8`  | 8    | 32 GB  | $0.016           |
| `starsling-ubuntu-24.04-16` | 16   | 64 GB  | $0.032           |
| `starsling-ubuntu-24.04-32` | 32   | 128 GB | $0.064           |
| `starsling-ubuntu-24.04-64` | 64   | 256 GB | $0.128           |

The 4 vCPU `starsling-ubuntu-24.04` label is the default and replaces `ubuntu-latest` and `ubuntu-24.04`. See [Label Reference](/configuration/label-reference) for the full label reference.

### Comparison to GitHub-hosted Runners (GitHub Actions)

| Runner Size   | GitHub Price | StarSling Price | Savings |
| ------------- | ------------ | --------------- | ------- |
| 2 vCPU Linux  | $0.006/min   | $0.004/min      | **33%** |
| 4 vCPU Linux  | $0.012/min   | **$0.008/min**  | **33%** |
| 8 vCPU Linux  | $0.022/min   | $0.016/min      | **27%** |
| 16 vCPU Linux | $0.042/min   | $0.032/min      | **24%** |
| 32 vCPU Linux | $0.082/min   | $0.064/min      | **22%** |
| 64 vCPU Linux | $0.162/min   | $0.128/min      | **21%** |

Comparison is against GitHub's Linux x64 larger runners. GitHub prices are sourced from the [GitHub Actions runner pricing reference](https://docs.github.com/en/billing/reference/actions-runner-pricing) (as of 2026-05-06).

StarSling is **up to 33% cheaper** than GitHub-hosted runners — while also being up to 6x faster.

### How Minutes Are Calculated

* Billed from job start to finish
* Rounded up to the nearest minute
* Queue time is **not** billed

***

## AI-Powered Optimizations

AI-powered optimizations are **included with every paid minute** at no additional cost — no per-optimization charges, no monthly caps, and no add-ons to buy. For new accounts, AI-powered optimization PRs are only available to customers on paid plans and are not enabled by default.

StarSling agents continuously:

* **Scan your GitHub Actions workflows** — Looking for caching, parallelization, and configuration improvements
* **Identify wasted minutes** — Spotting redundant or slow steps
* **Open pull requests with optimizations** — Each PR includes the change and an explanation

See the cost and speed wins these optimizations produced in real repos: [StarSling case studies →](https://starsling.dev/customers).

***

## Billing FAQ

### Do I pay for failed jobs?

Yes, but failed jobs typically exit quickly, minimizing costs.

### Do unused free minutes roll over?

No. The 2,000 free minutes are a one-time introductory offer for your first month.

### How does billing work after the free minutes?

After your first month (or once you exceed 2,000 minutes), you're billed per minute based on runner size — from $0.004/min for the 2 vCPU runner up to $0.128/min for the 64 vCPU runner (see the [Compute](#compute) table above for all sizes). AI-powered optimizations remain included.

***

## Get Started

1. **Sign up** at [starsling.dev](https://starsling.dev)
2. **Add StarSling** to your GitHub workflow with a single line change
3. **Start building** faster with AI-powered optimizations

<Cards>
  <Card title="Get Started" href="https://starsling.dev" description="Sign up for free — 2,000 minutes included" />

  <Card title="Contact Sales" href="mailto:founders@starsling.dev" description="Enterprise inquiries" />
</Cards>


# Compute Specifications (/runners/compute-sizing)



All StarSling runners provide consistent, high-performance compute on 5th Gen AMD EPYC processors. Choose a size based on the compute resources your job requires.

## Specifications

| Label                       | vCPU | Memory | Price per minute |
| --------------------------- | ---- | ------ | ---------------- |
| `starsling-ubuntu-24.04-2`  | 2    | 8 GB   | $0.004           |
| `starsling-ubuntu-24.04`    | 4    | 16 GB  | $0.008           |
| `starsling-ubuntu-24.04-8`  | 8    | 32 GB  | $0.016           |
| `starsling-ubuntu-24.04-16` | 16   | 64 GB  | $0.032           |
| `starsling-ubuntu-24.04-32` | 32   | 128 GB | $0.064           |
| `starsling-ubuntu-24.04-64` | 64   | 256 GB | $0.128           |

The numeric suffix on each label indicates the vCPU count (e.g. `-8` = 8 vCPU). The label without a suffix is the 4 vCPU default and replaces `ubuntu-latest` and `ubuntu-24.04`.

All sizes run Ubuntu 24.04 on 5th Gen AMD EPYC.

## Performance Characteristics

StarSling runners deliver excellent performance for most CI workloads:

* **Web Applications (React, Next.js, Vue)**: Fast installs and builds
* **Backend Services (Go, Rust, Java)**: Efficient parallel compilation
* **Test Suites**: Parallel test execution

Larger sizes (8 vCPU and above) are well-suited for monorepo builds, large test matrices, and compilation-heavy workloads.

## Example Usage

```yaml
runs-on: starsling-ubuntu-24.04
```

For a larger size:

```yaml
runs-on: starsling-ubuntu-24.04-8
```

## Optimization Tips

1. **Cache dependencies**: Use `actions/cache` to avoid repeated downloads
2. **Use matrix builds**: Split tests across multiple runners for parallelism
3. **Right-size your runner**: Larger isn't always better — measure before scaling up

<Cards>
  <Card title="Instance Types" href="/runners/instance-types" description="Full runner label reference" />
</Cards>


# Instance Types (/runners/instance-types)



StarSling Runners are built on Linux Ubuntu with pre-installed tools for common CI/CD workflows.

## Runner Labels

Choose a runner label based on the compute resources your job requires. For non-default sizes, the numeric suffix on each label indicates the vCPU count (e.g. `-8` = 8 vCPU). The label without a suffix is the 4 vCPU default.

| Label                       | OS           | vCPU | Memory | Price per minute |
| --------------------------- | ------------ | ---- | ------ | ---------------- |
| `starsling-ubuntu-24.04-2`  | Ubuntu 24.04 | 2    | 8 GB   | $0.004           |
| `starsling-ubuntu-24.04`    | Ubuntu 24.04 | 4    | 16 GB  | $0.008           |
| `starsling-ubuntu-24.04-8`  | Ubuntu 24.04 | 8    | 32 GB  | $0.016           |
| `starsling-ubuntu-24.04-16` | Ubuntu 24.04 | 16   | 64 GB  | $0.032           |
| `starsling-ubuntu-24.04-32` | Ubuntu 24.04 | 32   | 128 GB | $0.064           |
| `starsling-ubuntu-24.04-64` | Ubuntu 24.04 | 64   | 256 GB | $0.128           |

The `starsling-ubuntu-24.04` label (4 vCPU / 16 GB) is the default and replaces the following GitHub-hosted runner labels:

* `ubuntu-latest`
* `ubuntu-24.04`

## Example Usage

```yaml title=".github/workflows/build.yml"
jobs:
  build:
    runs-on: starsling-ubuntu-24.04
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install and Build
        run: |
          npm ci
          npm run build
```


# Compliance (/security/compliance)



StarSling is committed to meeting enterprise security requirements.

## Current Status

### SOC 2 Type II

**Status:** In progress

We are actively working toward SOC 2 Type II certification. Expected completion: Q3 2026.

### ISO 27001

**Status:** In progress

We are actively working toward ISO 27001 certification in parallel with SOC 2 Type II. Expected completion: Q3 2026.

## Security Practices

### Access Control

* All employee access requires MFA
* Production access limited to on-call engineers
* Access logged and audited quarterly

### Infrastructure Security

* Cloud infrastructure with security best practices
* Regular security patches applied
* Network segmentation between environments

### Incident Response

* 24/7 on-call rotation
* Documented incident response procedures
* Customer notification within 24 hours for security incidents

### Vulnerability Management

* Regular dependency updates
* Automated security scanning in CI
* Responsible disclosure program

## Penetration Testing

We conduct annual penetration tests with third-party security firms.

**Most recent test:** Q4 2024

**Findings:** No critical or high severity findings

Reports available under NDA for Enterprise customers.

## Vendor Security

### GitHub

We integrate with GitHub's APIs, which maintain:

* SOC 1, 2
* ISO 27001
* FedRAMP

## Security Questionnaire

For enterprise security reviews, we provide:

* CAIQ (Consensus Assessment Initiative Questionnaire)
* SIG (Standard Information Gathering)
* Custom questionnaire responses

Contact [founders@starsling.dev](mailto:founders@starsling.dev) to request security documentation.

## Responsible Disclosure

If you discover a security vulnerability, please report it to:

**[security@starsling.dev](mailto:security@starsling.dev)**

We commit to:

* Acknowledging receipt within 24 hours
* Providing status updates every 72 hours
* Not pursuing legal action for good-faith research

## Enterprise Security Features

Available for Enterprise:

* Single Sign-On (SSO) via SAML
* Audit log export
* Custom data retention policies
* Dedicated support channel
* Security review calls

<Cards>
  <Card title="Data Handling" href="/security/data-handling" description="Data practices" />

  <Card title="Contact Sales" href="mailto:founders@starsling.dev" description="Enterprise inquiries" />
</Cards>


# Data Handling (/security/data-handling)



Transparency about data handling is essential. Here's exactly what data StarSling accesses and how we handle it.

## Data Access Summary

| Data Type                     | Accessed | Stored      | Retention        |
| ----------------------------- | -------- | ----------- | ---------------- |
| Repository metadata           | Yes      | Yes         | Account lifetime |
| Workflow definitions          | Yes      | No          | -                |
| Source code                   | Yes      | Temporarily | 24 hours         |
| Repository activity & context | Yes      | No          | -                |
| Secrets                       | No       | No          | -                |
| Environment variables         | No       | No          | -                |
| Build artifacts               | No       | No          | -                |

## Detailed Breakdown

### Repository Metadata

**What:** Repository name, owner, installation ID

**Why:** To route webhooks and manage runner registration

**Stored:** Yes, in our database

**Retention:** Until you uninstall the GitHub App

### Workflow Events

**What:** Webhook payloads for `workflow_job` events

**Why:** To provision runners when jobs start

**Stored:** No (processed in memory)

**Retention:** None

### Workflow Definitions (Optimizations)

**What:** Your `.github/workflows/*.yml` files

**When:** Periodically scanned by StarSling's AI agents to identify optimization opportunities

**Why:** To suggest caching improvements, faster install strategies, build step optimizations, and workflow restructuring

**Stored:** No (processed in memory during analysis)

**Retention:** None

### Source Code (AI Analysis)

**What:** Source code files in your repository

**When:** Accessed for AI-powered optimizations

**Why:** To provide context for optimization suggestions

**Stored:** Yes, temporarily during analysis

**Retention:** Deleted within 24 hours

### Repository Activity & Context

**What:** Read-only repository signals such as deployments, issues, discussions, pages, and security events

**When:** Accessed alongside workflow and source analysis

**Why:** To give optimization suggestions broader context about your repository

**Stored:** No (processed in memory during analysis)

**Retention:** None

## What We Never Access

### Secrets

GitHub secrets are passed directly from GitHub to the runner. StarSling's infrastructure never sees secret values.

### Environment Variables

Custom environment variables are injected by GitHub, not StarSling.

### Build Artifacts

Artifacts uploaded via `actions/upload-artifact` go directly to GitHub's artifact storage.

## Changes We Make

StarSling's AI agents propose optimizations by opening pull requests. This requires write access to **code** and **workflows**, scoped to changes the GitHub App commits on new pull request branches.

**What we do:**

* Create a new branch and commit proposed changes
* Open a pull request with an explanation for your review

**What we don't do:**

* Push to your default branch or any existing branch
* Merge or approve pull requests

See [GitHub App Permissions](/configuration/github-app-permissions) for the full list of permissions and why each is requested.

## Isolation

StarSling runs every job in its own ephemeral sandbox — a single-use, hardware-isolated microVM. Each job gets a fresh microVM that is destroyed the moment the run finishes, so there's nothing for a later job, including a fork pull request, to persist on or reach.

Isolation is enforced per job at the hardware-virtualization layer, so jobs from different repositories and organizations never share a runtime. This is the same isolation model GitHub-hosted runners use.

## Data Location

| Data             | Location                      |
| ---------------- | ----------------------------- |
| Control plane    | US East                       |
| Runners          | US East (more regions coming) |
| Logs (temporary) | US East                       |

## Encryption

### In Transit

* All communications use TLS 1.3
* Webhook payloads verified with GitHub signatures
* Runner-to-GitHub communication encrypted

### At Rest

* Databases encrypted at rest with managed keys
* Logs encrypted at rest

## Data Deletion

### On Uninstall

When you uninstall the StarSling GitHub App:

1. All runners immediately deregistered
2. Account metadata deleted (within 7 days)
3. No backups retained

### On Request

Contact [support@starsling.dev](mailto:support@starsling.dev) to request immediate data deletion.

<Cards>
  <Card title="GitHub App Permissions" href="/configuration/github-app-permissions" description="Permission details" />

  <Card title="Compliance" href="/security/compliance" description="Certifications and practices" />
</Cards>


# Security (/security)



StarSling is built with security as a core principle. Your code and secrets are protected at every layer.

<Cards>
  <Card title="Data Handling" href="/security/data-handling" description="What data we access and retain" />

  <Card title="Compliance" href="/security/compliance" description="Certifications and practices" />

  <Card title="GitHub App Permissions" href="/configuration/github-app-permissions" description="What permissions we request and why" />
</Cards>

## Security Highlights

* **Secrets never touch StarSling** - Passed directly from GitHub to runner
* **Ephemeral, hardware-isolated sandboxes** - Each job runs in its own single-use microVM, destroyed after the run — the same isolation as GitHub-hosted
* **Encrypted everywhere** - TLS 1.3 for all communications
* **Minimal data retention** - Logs deleted within 24 hours


# Common Issues (/troubleshooting/common-issues)



Solutions to the most common issues with StarSling Runners.

## Runner Issues

### Personal Repositories Not Supported

**Symptom:** You installed the StarSling GitHub App on a personal repository, but jobs remain queued and are never picked up by StarSling Runners.

**Cause:** StarSling Runners only work with GitHub organizations, not personal repositories.

GitHub's self-hosted runner architecture requires organization-level permissions for secure job routing and runner management. When a workflow runs, GitHub needs to authenticate and route the job to the correct runner pool. This authentication flow relies on organization-level API endpoints and webhook events that aren't available for personal repositories.

Additionally, organization-level runner groups provide security boundaries that allow StarSling to safely manage runners across multiple repositories while maintaining isolation between different customers.

**Solution:** Move your repository to a GitHub organization. You can [create a free organization](https://github.com/account/organizations/new) and transfer your repository to it.

### Runner Not Starting

**Symptom:** Job stays in "Queued" state indefinitely.

**Possible causes:**

1. **GitHub App not installed**
   * Verify the StarSling app is installed on your repository
   * Check Settings → Integrations → GitHub Apps

2. **Invalid label format**
   * Use the correct label format
   * Example: `starsling-ubuntu-24.04`

3. **Quota exceeded**
   * Check if you've hit your account limits
   * Contact support to increase limits

**Solution:**

```yaml
# Correct format
runs-on: starsling-ubuntu-24.04

# Wrong formats
runs-on: starsling-ubuntu-22.04    # ❌ Only Ubuntu 24.04 is supported
runs-on: starsling/ubuntu-24.04    # ❌ Use hyphens, not slashes
runs-on: starsling-ubuntu-latest   # ❌ Use starsling-ubuntu-24.04
```

### Job Fails Immediately

**Symptom:** Job starts but fails within seconds.

**Possible causes:**

1. **Action compatibility issue**
   * Some actions have self-hosted runner restrictions
   * Check action documentation

2. **Missing dependencies**
   * Tool may not be pre-installed
   * Add setup step to install

**Solution:**

```yaml
steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-node@v4  # Ensure Node.js is configured
    with:
      node-version: '20'
```

### Slow Performance

**Symptom:** Builds are slower than expected.

**Possible causes:**

1. **Cache misses**
   * Check cache hit rate in logs
   * Verify cache key is correct

2. **Network downloads**
   * Dependencies being downloaded each run
   * Add caching for node\_modules, pip, etc.

3. **Sequential tests**
   * Use matrix builds to parallelize across multiple runners

## Cache Issues

### Cache Not Restoring

**Symptom:** Cache action shows "Cache not found".

**Possible causes:**

1. **Key mismatch**
   * Lockfile changed, generating new key
   * This is expected behavior

2. **Cache expired**
   * Unused caches expire after 7 days
   * Run a fresh build to repopulate

3. **Cross-branch caching**
   * Default branch caches aren't shared to feature branches initially

**Solution:**

```yaml
- uses: actions/cache@v4
  with:
    path: node_modules
    key: deps-${{ hashFiles('package-lock.json') }}
    restore-keys: |
      deps-  # Fallback to partial match
```

### Cache Upload Slow

**Symptom:** Cache upload takes several minutes.

**Possible causes:**

1. **Large cache size**
   * Check what's being cached
   * Exclude unnecessary files

2. **Network issues**
   * Temporary connectivity problems
   * Usually resolves on retry

## Workflow Issues

### Environment Variables Missing

**Symptom:** Expected env vars are undefined.

**Solution:** Ensure you're setting them correctly:

```yaml
jobs:
  build:
    runs-on: starsling-ubuntu-24.04
    env:
      NODE_ENV: production
    steps:
      - run: echo $NODE_ENV
```

<Cards>
  <Card title="Debug Access" href="/troubleshooting/debug-access" description="Get help from support" />

  <Card title="Migration Guide" href="/configuration/migration-guide" description="Ensure correct setup" />
</Cards>


# Debug Access (/troubleshooting/debug-access)



When troubleshooting isn't enough, here's how to get help.

## Viewing Logs

### GitHub Actions Logs

Standard workflow logs are available in GitHub:

1. Go to your repository
2. Click **Actions** tab
3. Select the workflow run
4. Click on the failed job
5. Expand step logs

### Runner Assignment Logs

To see StarSling-specific logs:

1. Look for the "Set up job" step
2. Expand to see runner assignment details
3. Note the runner ID for support requests

## Contacting Support

### Email Support

**[support@starsling.dev](mailto:support@starsling.dev)**

Include in your request:

* Repository name (org/repo)
* Workflow run URL
* Runner ID (if available)
* Description of the issue

**Response time:** Within 24 hours (business days)

### Priority Support (Enterprise)

Enterprise customers have access to:

* Dedicated Slack channel
* 4-hour response SLA
* Direct engineering escalation

## Community

### Discord

Join our Discord community for:

* Real-time help from other users
* Feature discussions
* Release announcements

[Join Discord](https://discord.gg/starsling)

### GitHub Discussions

For longer-form questions and feature requests:

[GitHub Discussions](https://github.com/starsling/community/discussions)

## Debug Checklist

Before contacting support, verify:

* [ ] GitHub App is installed and has repository access
* [ ] Label format is correct (`starsling-ubuntu-24.04`)
* [ ] No typos in the workflow file
* [ ] Repository is not archived
* [ ] The issue reproduces consistently

## Useful Information for Support

When reporting an issue, include:

```markdown
**Repository:** org/repo
**Workflow:** ci.yml
**Run URL:** https://github.com/org/repo/actions/runs/12345
**Runner ID:** sr-abc123xyz (from "Set up job" step)

**Issue:**
Description of what's happening vs. what you expected.

**Steps to reproduce:**
1. Push to branch X
2. Workflow triggers
3. Job fails with error Y

**What I've tried:**
- Checked label format
- Verified GitHub App installation
- etc.
```

## Status Page

Check current system status:

[status.starsling.dev](https://status.starsling.dev)

Subscribe for incident notifications via email or RSS.

## Feature Requests

Have an idea for StarSling? We'd love to hear it:

* **Discord:** #feature-requests channel
* **GitHub:** Open a discussion
* **Email:** [founders@starsling.dev](mailto:founders@starsling.dev)

Popular requests are prioritized in our roadmap.

<Cards>
  <Card title="Common Issues" href="/troubleshooting/common-issues" description="Self-service solutions" />

  <Card title="Quickstart" href="/getting-started/quickstart" description="Verify your setup" />
</Cards>