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 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:

# 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:

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:

- 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:

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