CI and automated testing

Run untrusted test suites, syntax checks, linting, and build validation safely in isolated containers.

Use this guide when you need to execute user-submitted code checks (tests/lint/build) in CI without risking host integrity.

Diagram: CI validation pipeline

Recommended baseline

For untrusted CI workloads, start with:

• mode: "ephemeral"
• network: "none" by default
• explicit timeout and memory
• no persistent state unless explicitly required

import { DockerIsol8 } from "@isol8/core";

const engine = new DockerIsol8({
  mode: "ephemeral",
  network: "none",
  timeoutMs: 30000,
  memoryLimit: "512m",
});

await engine.start();

Pattern 1: run unit tests against submitted code

async function runPythonTests(submittedCode: string, testCode: string) {
  const result = await engine.execute({
    runtime: "python",
    installPackages: ["pytest"],
    code: `
with open("/sandbox/solution.py", "w") as f:
  f.write("""${submittedCode.replace(/"""/g, '"""')}""")

with open("/sandbox/test_solution.py", "w") as f:
  f.write("""${testCode.replace(/"""/g, '"""')}""")

import subprocess
proc = subprocess.run(
  ["python3", "-m", "pytest", "/sandbox/test_solution.py", "-q", "--tb=short"],
  capture_output=True, text=True, timeout=20
)
print(proc.stdout)
if proc.stderr:
  print(proc.stderr)
raise SystemExit(proc.returncode)
`,
  });

  return {
    passed: result.exitCode === 0,
    stdout: result.stdout,
    stderr: result.stderr,
    durationMs: result.durationMs,
  };
}

Pattern 2: syntax validation (cheap fail-fast gate)

Python

const result = await engine.execute({
  runtime: "python",
  stdin: code,
  code: `
import ast, sys
src = sys.stdin.read()
ast.parse(src)
print("VALID")
`,
});

Node

const result = await engine.execute({
  runtime: "node",
  stdin: code,
  code: `
const fs = require("node:fs");
const src = fs.readFileSync("/dev/stdin", "utf8");
new Function(src);
console.log("VALID");
`,
});

CLI quick check

isol8 run -e "import ast,sys; ast.parse(sys.stdin.read()); print('VALID')" \
  --runtime python \
  --stdin "print('hello')"

Pattern 3: linting gate

const lint = await engine.execute({
  runtime: "python",
  installPackages: ["flake8"],
  stdin: submittedCode,
  code: `
import subprocess, sys
open("/sandbox/code.py", "w").write(sys.stdin.read())
proc = subprocess.run(
  ["python3", "-m", "flake8", "/sandbox/code.py", "--max-line-length=120"],
  capture_output=True, text=True
)
print(proc.stdout)
if proc.stderr:
  print(proc.stderr)
raise SystemExit(proc.returncode)
`,
});

Pattern 4: build verification

If build needs external dependency resolution, explicitly allow it.

const buildEngine = new DockerIsol8({
  mode: "ephemeral",
  network: "host", // trusted CI context only
  timeoutMs: 120000,
  memoryLimit: "1g",
});

await buildEngine.start();

const result = await buildEngine.execute({
  runtime: "bash",
  files: {
    "/sandbox/package.json": packageJson,
    "/sandbox/index.ts": indexTs,
    "/sandbox/tsconfig.json": JSON.stringify({
      compilerOptions: {
        strict: true,
        target: "ES2022",
        module: "ESNext",
      },
    }),
  },
  code: `
cd /sandbox
npm install --ignore-scripts
npx tsc --noEmit
`,
});

await buildEngine.stop();

network: "host" should be used only in trusted CI contexts where unrestricted network access is acceptable.

Pattern 5: artifact capture from test runs

Capture generated test reports using outputPaths.

const result = await engine.execute({
  runtime: "python",
  code: `
open("/sandbox/report.txt", "w").write("tests: 42\\npassed: 41\\nfailed: 1\\n")
print("report-ready")
`,
  outputPaths: ["/sandbox/report.txt"],
});

const reportBase64 = result.files?.["/sandbox/report.txt"];

Parallel CI jobs

Run independent validations concurrently; isol8 enforces concurrency with semaphores/maxConcurrent.

const jobs = submissions.map((s) =>
  engine.execute({
    runtime: "python",
    stdin: s.code,
    code: "import ast,sys; ast.parse(sys.stdin.read()); print('ok')",
  })
);

const results = await Promise.all(jobs);

Remote CI runners

For centralized build/test infrastructure, use remote server + RemoteIsol8.

import { RemoteIsol8 } from "@isol8/core";

const remote = new RemoteIsol8(
  {
    host: "http://ci-runner.internal:3000",
    apiKey: process.env.ISOL8_API_KEY!,
    sessionId: "pr-123-checks",
  },
  {
    network: "none",
    timeoutMs: 45000,
    memoryLimit: "768m",
  }
);

await remote.start();
const result = await remote.execute({
  runtime: "python",
  code: "print('remote checks start')",
});
await remote.stop();

Reliability patterns for CI pipelines

• fail fast with syntax check before expensive test/build stages
• keep network off unless a stage explicitly requires dependency downloads
• pre-bake stable dependencies with isol8 setup for predictable timing
• return structured machine-readable output from each stage (JSON/text summary)
• enforce explicit timeouts per stage to avoid hanging workers

Related pages

Execution guide

Request fields, limits, and lifecycle behavior used by CI tasks.

Packages and images

Pre-bake dependencies for stable, faster CI execution.

Security model

Network and isolation controls for untrusted code validation.

Remote server and client

Run CI checks on centralized remote executors.