Sling — Operator & API Reference

Start here

If you're an engineer adding a new repo to Sling, work through these in order:

1. Add a block to config/repositories.json
2. Make sure the right GitHub App is installed on the repo (svenlabs-ci-app for SvenLabs-owned repos, gdt-ci-app for GDT)
3. Set the corresponding env vars on the Sling server (App ID + private-key path + webhook secret)
4. Restart Sling: pm2 restart sling --update-env
5. Open a labelled test issue and confirm the next Night Shift cron picks it up

Public routes

What's served and where. All routes below are mounted on https://sling.svenlabs.ai.

Onboarding + presentation (EPIC #441)

Operator surfaces

Webhook + ingest endpoints

Comment commands (PR + issue)

Sling reads slash-commands from issue comments and PR comments. The webhook handler dispatches to the matching governance / pipeline action.

config/repositories.json schema

One entry per repo Sling manages. Minimal example with the most common fields:

{
  "id": "workos",
  "github_repo": "svenlabsllc/workos",
  "github_app": "svenlabs-ci-app",
  "branch": "develop",
  "productionBranch": "main",
  "sourceBranch": "main",
  "execution_mode": "claude-code",
  "language": "typescript",
  "test_command": "pnpm test",
  "labels": ["auto-implement", "sling"],
  "max_concurrent_tasks": 1,
  "claude_model": "auto",
  "hipaa_mode": false,
  "governance": { ... },
  "staging":   { ... },
  "uat":       { ... }
}

Branching model

Three orthogonal fields control the branch lifecycle. The split (#403) lets us merge to develop while cutting from main, so PRs don't carry unrelated divergence as their base.

Branch naming: {type}/auto-{issue}/{slug} where type ∈ feat | fix | hotfix | chore | refactor | docs.

Environment variables

Execution modes

Mode resolution priority: task label → repo config (execution_mode) → task property (executionMode) → default stiv.

STIV pipeline + checkpointing

Phases written to PostgreSQL task_steps. On retry, completed phases are skipped (sling#291 resilience).

1. workspace — clones repo, checks out sourceBranch, creates feature branch
2. spec — turns the issue into structured ACs
3. tests — generates tests for each AC (skipped on skip-tests)
4. implement — writes code; up to 3 attempts per file
5. quality — lint + types + existing test suite
6. review — AI auto-review, score 0-10
7. push + pr — pushes branch, opens PR with rolling comment

Workspace + branch are reused across retries. Heavy subprocesses run with nice -n 15 ionice -c2 -n7; default cap is 2 concurrent tasks.

Project lifecycle state machine

src/utils/lifecycle-store.js is the source of truth for where a ticket sits in the producer / BO / release loop (workflow PDF steps 11 + 13).

spec_review
  → building
    → ready_for_uat
      → uat_in_review
        → back_in_engineering ⇆ building
        → push_to_production | push_to_production_immediately
          → in_production
            → reverted

Two tables back it: project_lifecycle (current state per task) and project_lifecycle_history (audit trail with actor + reason). Use transitionAsync() for fire-and-forget calls; illegal transitions warn but never throw.

UAT + push to production

The UAT Slack message offers BOs three branches:

The urgent path records urgent = true + triggered_by = <slack user> on the releases row and prefixes the Slack message with :rotating_light: URGENT. It does not bypass branch protection — those are enforced by GitHub at merge time.

E2E testing

The post-PR pipeline runs Playwright E2E and downloads videos / traces / screenshots on every build, including every /retry re-entry. Artifacts are stored at /data/sling-artifacts/{owner}/{repo}/pr-{N}/{timestamp}/ with 30-day retention.

QA video + trace are forced ON via --trace=on --video=on appended to the default Playwright command. Opt out per-repo:

"staging": {
  "e2e": { "qaVideo": false, "qaTrace": false }
}

When the repo provides its own testCmd, Sling does not modify it — pass the flags yourself.

Auto-review noise controls (EPIC #413 / #419)

The auto-review comment is rolled in place: first run creates a comment, every subsequent run edits it with a <sub>_Last updated …_</sub> footer.

Governance

Risk tiers determine whether a task auto-runs, requires human approval, or is rejected outright. Per-repo overrides live under governance in repositories.json.

EPIC protection (#399)

Issues labelled epic are excluded from auto-split. Sling will not break an EPIC into child issues automatically.

AI issue creation (#397 + #400)

AI-originated issue creation is blocked by default; SLING_AI_ISSUE_CREATION=true opts in. When enabled, dedup-candidate + product-repo-map signals are surfaced on every proposal. See I1 / I5 / I6 under infra#384.

Night Shift cron

Runs every 5 min via node-cron. Fetches eligible issues across all configured repos via getOctokitForRepo (sling#468), routes them through governance, queues them to workers. Stale task_issue_map rows reclaim themselves when their PR is closed-without-merge (sling#291).

API endpoints (operators)

POST /api/autodev/ingest

Receives AutoDev specification bundles from IntentOS. Auth: Authorization: Bearer <HMAC> with AUTODEV_INGEST_SECRET. Target repo resolved from X-Target-Repo header, or AUTODEV_DEFAULT_OWNER/_REPO.

curl -X POST https://sling.svenlabs.ai/api/autodev/ingest \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <hmac>" \
  -H "X-Target-Repo: svenlabsllc/workos" \
  -d '{ "title": "...", "requirements": [...], "constraints": [...], "acceptance": [...] }'

POST /api/intentos/ingest

IntentOS webhook for spec ingestion. Same HMAC pattern, separate secret (INTENTOS_WEBHOOK_SECRET).

POST /api/onboarding/event

Public beacon for B8 telemetry. Always 204. Validates a small whitelist (page, event_type, section, browser family); silently drops anything else. DNT-respecting on the client side.

Runbooks

Operator playbooks live under docs/runbooks/ in the Sling repo:

• db-restore.md — restoring a corrupted PostgreSQL state (#418 R1)
• sling-down.md — what to do when Sling is offline (#418 R3)
• env-vars.md — exhaustive env variable reference
• docs/adr/ — architectural decision records

Source: src/handlers/docs.js. Update this file whenever a public route, env var, or repositories.json field is added.