Running in CI

In-process tests (.NET, C) need only the engine’s library; they start no server. Server-form tests (Rust, Java, TypeScript, Python, Go, or any HTTP client) need an Embedded engine running beside the test job. The engine needs no database, no volume and no warm-up, so the simplest way to get one is a service container from the registry.tinyfactory.ai/tinyblox/tinyconductor image: the CI system starts it before your job, waits until it is healthy, and removes it when the job ends.

The image starts the Embedded engine by default, listening on port 8080. A container engine listens beyond loopback, so it needs a credential: give it one in CONDUCTOR_AUTH_CREDENTIALS_JSON, and give your tests the same token in TINYCONDUCTOR_TOKEN. Every server-form example reads TINYCONDUCTOR_URL and TINYCONDUCTOR_TOKEN and sends the token as Authorization: Bearer …. Store the token as a CI secret, or generate a random one per pipeline; it only guards an engine that lives for one job.

/healthz answers with "status":"UP" and "mode":"embedded". The image has a built-in health check on /readyz, so the CI system knows when the engine is ready. The tests themselves never wait on time, because the engine’s clock is virtual.

GitHub Actions

jobs:
  process-tests:
    runs-on: ubuntu-latest
    services:
      tinyconductor:
        image: registry.tinyfactory.ai/tinyblox/tinyconductor:0.1.0
        ports:
          - 127.0.0.1:8080:8080
        env:
          CONDUCTOR_AUTH_CREDENTIALS_JSON: >-
            [{"token":"${{ secrets.TINYCONDUCTOR_TEST_TOKEN }}","subject":"ci",
              "tenantId":"default","kind":"service","actions":["*"]}]
    env:
      TINYCONDUCTOR_URL: http://127.0.0.1:8080
      TINYCONDUCTOR_TOKEN: ${{ secrets.TINYCONDUCTOR_TEST_TOKEN }}
    steps:
      - uses: actions/checkout@v4          # your processes and tests
      - name: Process tests
        run: python3 -m unittest -v        # or: gradle test, npm test, go test ./...

The job waits for the service’s health check before its first step. If the image is private in your registry, add credentials: to the service with a user and token that can read it.

GitLab CI

process-tests:
  image: python:3.12                        # your test toolchain
  services:
    - name: registry.tinyfactory.ai/tinyblox/tinyconductor:0.1.0
      alias: tinyconductor
  variables:
    CONDUCTOR_AUTH_CREDENTIALS_JSON: '[{"token":"$TINYCONDUCTOR_TEST_TOKEN","subject":"ci","tenantId":"default","kind":"service","actions":["*"]}]'
    TINYCONDUCTOR_URL: http://tinyconductor:8080
    TINYCONDUCTOR_TOKEN: $TINYCONDUCTOR_TEST_TOKEN
  script:
    - python3 -m unittest -v                # or: gradle test, npm test, go test ./...

TINYCONDUCTOR_TEST_TOKEN is a masked CI/CD variable. GitLab passes the job’s variables to its services too, so the engine and the tests share the token. The tests reach the engine by its alias, tinyconductor.

Docker Compose

For a pipeline that runs its tests in containers, or to reproduce CI on your own machine:

services:
  tinyconductor:
    image: registry.tinyfactory.ai/tinyblox/tinyconductor:0.1.0
    environment:
      CONDUCTOR_AUTH_CREDENTIALS_JSON: '[{"token":"${TINYCONDUCTOR_TOKEN}","subject":"ci","tenantId":"default","kind":"service","actions":["*"]}]'
  tests:
    image: python:3.12
    working_dir: /work
    volumes: [".:/work"]
    environment:
      TINYCONDUCTOR_URL: http://tinyconductor:8080
      TINYCONDUCTOR_TOKEN: ${TINYCONDUCTOR_TOKEN}
    command: python3 -m unittest -v
    depends_on:
      tinyconductor:
        condition: service_healthy

Run it with TINYCONDUCTOR_TOKEN=$(openssl rand -hex 24) docker compose up --abort-on-container-exit --exit-code-from tests.

Without containers

Where the job cannot run containers, download the release archive for the runner’s platform and start the program on loopback, where it needs no credential (the list of downloads is in Embedded mode):

tar -xzf tinyconductor-0.1.0-linux-x86_64.tar.gz
./tinyconductor-0.1.0-linux-x86_64/tinyconductor --mode embedded > engine.log 2>&1 &
for attempt in $(seq 1 60); do
  curl -sf http://127.0.0.1:8080/healthz && break
  sleep 1
done

The retry loop only guards against an engine that never came up. Cache the archive between pipelines the way you cache any download, keyed by its file name.

In-process tests

The .NET and C tests start no engine. They need the library at build time: the C library comes from the lib folder of the release archive for the runner’s platform (see .NET and C and FFI), and the .NET SDK from the TinyConductor.Testing package file attached to the release. Rust tests use the server form, like Java or Go (see Rust).