# CI/CD Integration

This guide covers using Chaser as throwaway compute for pipelines, builds, and automated checks.

## One-shot stateless execution

The simplest pattern -- run a command on a fresh sandbox and get the result:

```bash
curl -sS "$CHASER_API_URL/v1/exec" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ephemeral": true,
    "image": "ghcr.io/example/dev:latest",
    "command": "npm ci && npm test",
    "timeout_ms": 900000
  }' | jq
```

No workspace, no session management. Chaser provisions a sandbox, runs the command, and returns `exit_code` and `output`.

## Queued execution with jobs

For retriable, scheduled, or bulk work, use the jobs API:

```bash
# Single command job
curl -sS "$CHASER_API_URL/v1/jobs" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "sandbox.exec",
    "input": {
      "ephemeral": true,
      "image": "ghcr.io/example/dev:latest",
      "command": "npm ci && npm test"
    }
  }' | jq

# Multi-step pipeline
curl -sS "$CHASER_API_URL/v1/jobs" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "pipeline.run",
    "input": {
      "workspace": "ci-project",
      "steps": [
        {"command": "npm ci", "timeout_ms": 300000},
        {"command": "npm run lint", "timeout_ms": 120000},
        {"command": "npm test", "timeout_ms": 600000}
      ]
    }
  }' | jq
```

Jobs support `run_at` for delayed execution and `idempotency_key` for safe retries.

## CLI for CI scripts

```bash
# Direct exec
chaser jobs exec --ephemeral --image ghcr.io/example/dev:latest \
  "npm ci && npm test" --wait --json

# On a persistent workspace (for cached dependencies)
chaser jobs exec --workspace ci-project "npm test" --wait --json
```

## GitHub Actions integration

Chaser can execute GitHub Actions `workflow_job` events when your repository uses self-hosted runner labels targeting Chaser (e.g., `chaser` or `chaser-*`). The `github.runner` job kind handles this integration.

## When to use workspaces in CI

Use ephemeral execution when:
- Every run should be fully isolated
- You want no state carryover between runs

Use workspace-backed execution when:
- You want cached `node_modules`, build artifacts, or `.git` history across runs
- Multiple pipeline steps need shared filesystem state
- You want to inspect the workspace after a failure

## Related

- [Command Execution](/docs/sessions/command-execution) -- exec API details
- [Jobs](/docs/platform/jobs) -- scheduling, pipelines, and job kinds
- [Workspaces](/docs/platform/workspaces) -- persistent storage for CI