quoll
A CLI that gives any Python, Node, Go, Rust, Java/Kotlin, PHP, Ruby, .NET or C/C++ repository a production-grade CI, Dockerfile and delivery pipeline in one command — on GitHub Actions or GitLab CI — and keeps them maintained.
Install
pipx install quoll-cli # or: uv tool install quoll-cli, pip install quoll-cli
quoll --version
Python 3.9 or later. Docker is needed for the images, Helm for the charts (only to install them yourself).
CI
cd my-project
quoll ci init
Supported stacks
| Language | Package managers | Lint | Tests (coverage threshold) | Frameworks |
|---|---|---|---|---|
| Python | pip, uv, poetry | ruff, ruff format, flake8, black, mypy | pytest | Django, FastAPI, Flask |
| Node.js | npm, pnpm, yarn, bun | eslint, prettier, biome, tsc, any package.json script |
vitest, jest, bun | Next.js, Nuxt, SvelteKit, Astro, Angular, NestJS |
| Go | go modules | gofmt, go vet, golangci-lint | go test | |
| Rust | cargo | rustfmt, clippy | cargo test, nextest (cargo-llvm-cov) | |
| Java / Kotlin | Maven, Gradle (wrappers supported) | spotless, checkstyle, ktlint, detekt, SpotBugs, PMD | JUnit via verify / check, JaCoCo coverage |
Spring Boot |
| PHP | composer | php-cs-fixer, phpcs, pint, phpstan, psalm, rector | phpunit, pest | Symfony, Laravel |
| Ruby | bundler | rubocop, standard | rspec, minitest (SimpleCov) | Rails |
| .NET | dotnet | dotnet format | dotnet test (coverlet.msbuild) | |
| C / C++ | CMake (plain, Conan, vcpkg), Meson | clang-format, clang-tidy, cppcheck | ctest, meson test (gcovr; ASan + UBSan) |
Frameworks add what the language alone can't know, for example:
- Django:
manage.py checkand a missing-migrations check in the lint job. - Symfony: the console linters (container, YAML, Twig).
- Rails: Brakeman, plus preparing the test database.
- Laravel:
.envand app key, thenphp artisan test. - Next.js: build cache.
- Nuxt, SvelteKit, Astro: their own type checks instead of plain
tsc. - Angular:
ng testwith headless Chrome.
Detection
quoll reads your project instead of asking you about it:
| Detected | From |
|---|---|
| Stack | pyproject.toml, package.json, go.mod, Cargo.toml, pom.xml / build.gradle(.kts), composer.json, Gemfile, *.sln / *.csproj, CMakeLists.txt / meson.build |
| Framework | dependencies and entry points (manage.py, bin/console, artisan, bin/rails…) |
| Package manager | lockfiles (uv.lock, poetry.lock, pnpm-lock.yaml, yarn.lock, bun.lock…), packageManager |
| Runtime version | .python-version, requires-python, .nvmrc, .node-version, engines, go.mod |
| Lint tools | ruff / flake8 / black / mypy config, eslint / prettier / biome / tsconfig, package.json scripts |
| Test runner & coverage | pytest, vitest (+ coverage plugin), jest, bun, go test |
| Build | [build-system], build script, go build |
| Branch & repository | git remote and default branch |
| Platform | the remote's host (github.com, gitlab.com, gitlab.<company>…), else an existing .gitlab-ci.yml |
It then asks only what it can't infer (coverage threshold, version matrix, Codecov, SonarCloud…), writes your choices to quoll.toml and generates the pipeline:
| Platform | Pipeline | Dependency updates (created only if missing) |
|---|---|---|
| GitHub | .github/workflows/ci.yml and .github/actions/quoll-setup (for your own workflows) |
.github/dependabot.yml |
| GitLab | .gitlab-ci.yml (rules, includes) and .gitlab/quoll-ci.yml (jobs) |
renovate.json |
Commands
| Command | What it does |
|---|---|
quoll ci init |
Detect, ask, write quoll.toml and the pipeline. --yes accepts the detected defaults (scripts, CI), --platform github|gitlab overrides the detection, --force replaces a hand-written pipeline, --local skips the branch protection and secrets. |
quoll ci update |
Regenerate the pipeline from quoll.toml, showing the diff first. |
quoll ci check |
Exit 1 if the pipeline no longer matches quoll.toml — run it in CI or pre-commit. |
quoll ci detect |
Print what quoll detects, without writing anything. |
quoll ci schedule |
GitLab: create or update the pipeline schedule of the security scans. |
quoll ci eject |
Stop managing the CI: the files become yours, [ci] leaves quoll.toml. |
At the end of init, quoll can also, through the platform's API:
- protect the default branch: changes go through pull / merge requests, merged once the pipeline passed — on GitHub the
CI resultcheck (admins included, linear history, no force push); on GitLab no direct push, "Pipelines must succeed" and fast-forward merges. No approval is required by default (authors can't approve their own changes: a single developer would be locked out); a team adds it in the repository's settings; - store what the pipeline needs (
.env.examplevariables used by tests,SONAR_TOKEN,CODECOV_TOKEN) as GitHub secrets or masked GitLab CI/CD variables.
Tokens come from QUOLL_GITHUB_TOKEN / QUOLL_GITLAB_TOKEN, gh auth token / glab, or are asked once and stored in ~/.config/quoll/config.toml. Self-managed GitLab instances are reached on the remote's host (QUOLL_GITLAB_URL for quoll new --remote, QUOLL_GITLAB_GROUP for the group of new projects).
The generated pipeline
| Job | What it does |
|---|---|
| lint | the language's formatters, linters and static analyzers (ruff/mypy, eslint/tsc, golangci-lint, clippy, phpstan/psalm, rubocop/Brakeman, clang-tidy/cppcheck…) plus the framework's checks |
| test | tests against one or several versions (matrix), with the backing services, a coverage threshold, sanitizers for C/C++; results (JUnit) and coverage shown in the pull/merge request |
| audit | known vulnerabilities in the dependencies (pip-audit, npm/pnpm/yarn/bun audit, govulncheck, cargo-audit, osv-scanner, composer audit, bundler-audit, dotnet list package --vulnerable) |
| secrets | gitleaks over the whole git history (allow-list: .gitleaksignore) |
| sast | Semgrep's default rules for every language of the repository (GitLab: report in the MR security widget) |
| sbom | after installing the dependencies: an SBOM (CycloneDX, pipeline artifact; GitLab's dependency list) and a license gate, failing on forbidden licenses (AGPL, SSPL…) by default |
Licenses are read from the installed packages (node_modules, .venv, vendor/…). A free-text license Trivy can't classify counts as UNKNOWN (add it to license_severity to block those too); dependencies installed outside the project (pip into the system interpreter, Maven/Go caches) are only partly covered. |
|
| codeql | GitHub CodeQL, results in the Security tab — optional, needs GitHub Advanced Security on private repositories |
| sonar | SonarCloud — optional |
| build | the project's build (package, binary, static site…); its output ([ci.build] artifacts: dist/, target/*.jar…) kept a week |
| docker | when there is a Dockerfile: BuildKit's Dockerfile checks, build, then a Trivy scan failing on fixable CRITICAL/HIGH vulnerabilities — before the image is ever published |
On GitHub Actions, a final CI result job is the single required status check, whatever the jobs and matrix entries:
- Least privilege & hygiene:
permissions: contents: read, per-job timeouts, superseded PR runs cancelled,merge_groupsupport for merge queues. - Reproducible installs: lockfile-based (
uv sync --locked,npm ci,pnpm install --frozen-lockfile…) with dependency caching. - Useful output: linter annotations on the PR (ruff, phpstan, psalm, rubocop), failed tests annotated and listed in the job summary, coverage summary, coverage threshold enforced for every test runner that measures it.
- Test reports for every language: pytest, Vitest, Jest (jest-junit, installed outside the project), bun, gotestsum, nextest (
cargo testhas no stable JUnit output), PHPUnit/Pest, RSpec (its JUnit formatter, outside the bundle), Surefire/Gradle,dotnet test(TRX converted by trx2junit), CTest/Meson. Cobertura coverage where the runner measures it (Go through gocover-cobertura). Java's coverage: JaCoCo without any build file change (Maven goals, a Gradle init script), the threshold over every module's report. - Security: dependency audit, secret scanning, Semgrep, optional CodeQL; jobs needing secrets (SonarCloud) skipped on fork PRs where they aren't available.
- Supply chain: every action pinned to a commit SHA (
actions/checkout@<sha> # v7), proposed updates by Dependabot; the tool images (gitleaks, Semgrep, Trivy) pinned by version.
On GitLab CI, the same jobs run in the test stage, each in the language's official image (python, ghcr.io/astral-sh/uv, node, oven/bun, golang, rust, eclipse-temurin / maven / gradle, php + Composer and the ext-* the lock file needs, ruby, dotnet/sdk):
- Pipelines: merge requests, pushes to the configured branches, tags and manual runs, without duplicate branch + MR pipelines; a new commit cancels the running pipeline. The pipeline itself is the merge gate.
- Caches kept inside the project (
.venv,.npm,.go,.cargo,.m2,vendor/bundle…), keyed on the lockfile, per job and matrix entry. - Matrix:
parallel:matrixover the versions, each entry with its resolved image. - Services started as GitLab services; their variables are exported by the script, so a project CI/CD variable of the same name (which would override job variables) can't point the tests at a real database.
- Merge request widgets: test results (JUnit), coverage on the diff (Cobertura) and the total coverage parsed from the log (badge); Semgrep's report in the security widget (Ultimate).
- Codecov in its own job reading the test job's report; SonarCloud only where
SONAR_TOKENis available. - Docker layer cache in the project's registry (
cache:<project>), shared by the CI's docker job and the delivery; a pipeline without access to the registry (a fork) builds from scratch. - Retries of the jobs lost to the infrastructure (runner, timeout, API) — never of a failing test, which would hide a flaky one.
- Steps that use a GitHub Action on GitHub (golangci-lint, govulncheck, cargo tools, osv-scanner…) run the equivalent CLI here.
quoll.toml
quoll.toml is the source of truth: edit it, then run quoll ci update (or quoll docker update). Every field is validated, with a clear error on typos. [project] is shared by the CI and the Docker image, so they can't disagree about the stack.
[project]
platform = "github" # github | gitlab
stack = "python" # go | rust | java | dotnet | php | ruby | python | node
framework = "django" # optional, one of the stack's frameworks
package_manager = "uv" # pip | uv | poetry | npm | pnpm | yarn | yarn-classic | bun | go | ...
services = ["postgres", "redis"] # postgres | mysql | redis | mongodb — for the CI tests and compose.yaml
[ci]
versions = ["3.12", "3.13"] # several = test matrix; empty = read version_file (GitHub only)
version_file = "" # e.g. ".python-version", ".nvmrc", "go.mod"
install = "uv sync --locked --all-extras"
source_dir = "src" # measured by coverage, checked by mypy
branches = ["main"]
dependency_updates = true # Dependabot (GitHub) / Renovate (GitLab) config, created once
[ci.lint]
enabled = true
tools = ["ruff", "mypy", "django-check"] # language + framework tools; node also accepts "script:<name>"
[ci.test]
enabled = true
runner = "pytest"
coverage_threshold = 80
codecov = false
reports = true # JUnit results and Cobertura coverage in pull/merge requests
sanitizers = false # ASan + UBSan (C/C++; detected on)
env_secrets = ["DATABASE_URL"] # exposed to tests from GitHub secrets / GitLab CI/CD variables
[ci.security]
audit = true # dependency vulnerabilities
secrets = true # gitleaks
sast = true # Semgrep
codeql = false # GitHub only
sbom = true # CycloneDX SBOM of the dependencies
licenses = true # license gate (Trivy)
license_severity = ["CRITICAL"] # CRITICAL = forbidden (AGPL, SSPL…), HIGH = restricted (GPL, LGPL), MEDIUM = reciprocal (MPL)
sonar = false
sonar_organization = ""
[ci.build]
enabled = true
command = "uv build"
docker = true # lint, build and scan the image (on when there is a Dockerfile)
Going beyond what quoll generates
quoll can't know every tool a project needs. The generated pipeline is one part of the CI, not all of it: three levels, pick the one that fits.
1. quoll.toml — the standard pipeline: versions, tools, thresholds, jobs on or off. Plus [[ci.steps]] to add a command, or a GitHub Action, to a generated job:
[[ci.steps]]
job = "test" # lint, test, build, audit or sbom
when = "before" # before: once the dependencies are installed; after: at the end
name = "Migrate"
run = "python manage.py migrate"
secrets = ["DJANGO_SECRET_KEY"] # read from GitHub secrets / GitLab CI/CD variables
[[ci.steps]] # GitHub only: any action of the marketplace
job = "test"
when = "after"
name = "Upload screenshots"
uses = "actions/upload-artifact@v4"
with = { name = "screenshots", path = "screenshots/" }
Or without writing TOML — the step is added, then the pipeline regenerated:
quoll ci add-step --job test --when before --name Migrate --run "python manage.py migrate" --secret DJANGO_SECRET_KEY
quoll ci add-step -d back # in a workspace: the project's directory; asks what's missing
Keeping the files in sync: quoll ci check (and docker check, cd check) fails when a generated file no longer matches quoll.toml. With pre-commit, quoll's hooks regenerate them when a quoll.toml changes:
# .pre-commit-config.yaml
repos:
- repo: https://github.com/theo-mrn/Quoll
rev: v0.2.0
hooks:
- id: quoll-ci # quoll ci update; also quoll-docker, quoll-cd
2. Your own CI, in plain YAML, next to quoll's — any tool, any action, any runner. quoll gives it the project's environment so you don't rebuild the toolchain setup:
-
GitHub: write your workflows in
.github/workflows/(quoll only ownsci.yml), and start your jobs with the generated action:steps: - uses: actions/checkout@v4 - uses: ./.github/actions/quoll-setup # toolchain, caches, dependencies — as quoll's CI with: { version: "3.13" } # optional - uses: microsoft/playwright-github-action@v1 - run: npx playwright test
-
GitLab: write
.gitlab/custom-ci.yml, included last. Your jobs extend the generated.quoll-setuptemplate, and any key of quoll's jobs can be overridden there (maps such asvariablesare merged, lists such asscriptreplaced):e2e: extends: .quoll-setup # image, caches, dependencies script: [npx playwright test] test: # quoll's test job, completed tags: [gpu] timeout: 45 minutes variables: { FEATURE_FLAGS: "on" }
3. quoll ci eject — the pipeline files become yours, as they are (quoll's header removed), and [ci] leaves quoll.toml. quoll stops managing the CI; the Docker image and the delivery stay managed.
Scheduled security scans
New vulnerabilities appear without any code change. Every week, the audit, secret scanning, Semgrep, CodeQL, SBOM/licenses and image scan run again on the default branch (lint, tests and build don't):
[ci.schedule]
enabled = true
cron = "0 6 * * 1" # UTC — Mondays at 06:00
On GitHub the schedule is part of the workflow. On GitLab it is a pipeline schedule, created by quoll ci init (or quoll ci schedule after changing the cron) through the API. A failed scheduled run notifies like any failed pipeline.
Monorepos
A repository holding several projects — a Next.js front-end and a FastAPI back-end, services in Go and Java… — is a workspace. quoll ci init at its root finds them (first-level directories, and apps/*, packages/*, services/*) and sets it up:
shop/
├── quoll.toml # the workspace: its members, and what they share
├── backend/quoll.toml # a project, in the single-project format: [project], [ci], [docker], [cd]
└── frontend/quoll.toml
# quoll.toml at the root
[project]
platform = "github"
[workspace]
members = ["backend", "frontend"]
[ci] # the repository's: triggers and repository-wide scans
branches = ["main"]
[ci.schedule]
cron = "0 6 * * 1"
[ci.security]
secrets = true # gitleaks, once for the whole repository
sast = true # Semgrep, once
Each member keeps the single-project format, so a project moved out of the repository stays a valid quoll project. In a workspace its branches, schedule, secrets and sast are the root's.
- One pipeline: every member's jobs, prefixed by its name (
backend-test,frontend-lint…) and run in its directory; on GitHub, oneCI resultgate for all. - Only what changed runs: a pull request touching
frontend/doesn't run the back-end's jobs. A change to the rootquoll.tomlor to the CI runs everything, as do tags, scheduled and manual runs. GitLab usesrules: changes; GitHub achangesjob (plaingit diff, no third-party action). - Per member: Dockerfile,
compose.yaml, image and delivery (quoll docker init/quoll cd initat the root do every member). GitHub: onecd-<member>.ymlper image, run when its directory changed; GitLab:<member>-publishjobs, and one release carrying every SBOM. - A root
compose.yamlrunning every member and their databases together: see Microservices. - Building blocks:
.github/actions/quoll-setup-<member>/.quoll-setup-<member>for your own jobs. - Every command works from the root or from a member's directory.
Docker
quoll docker init # detect, ask the port / start command if needed, write Dockerfile, .dockerignore, compose.yaml
quoll docker update # regenerate from quoll.toml, showing the diff first
quoll docker check # exit 1 if the Dockerfile no longer matches quoll.toml
Every image is multi-stage, runs as a non-root user, installs dependencies from the lockfile in their own cached layer (BuildKit cache mounts) and ships only what runs. Runtime images on Debian, Ubuntu or Alpine get the OS security fixes released since their base image was built (distroless ones have no package manager: rebuilding picks up Google's). Each framework gets an image that fits it:
| Stack | Build | Runtime image |
|---|---|---|
| Python (pip, uv, poetry) | virtualenv built in a builder stage | python:<v>-slim; gunicorn for Django and Flask, uvicorn for FastAPI (app module found in the code) |
| Node | lockfile install, build, devDependencies pruned | node:<v>-slim, or oven/bun |
| Next.js | output: "standalone" when enabled |
only the standalone server, .next/static and public/ |
| Nuxt | Nitro build | only .output/ |
| Vite SPA, Angular, Astro, SvelteKit (static) | static build | nginx-unprivileged with SPA fallback (or 404 page) |
| SvelteKit / Astro (node adapter), Angular SSR, NestJS | build | Node server |
| Go | static binary (CGO_ENABLED=0, trimmed) |
distroless/static:nonroot |
| Rust | release binary (system OpenSSL when needed) | distroless/cc:nonroot |
| Java / Kotlin | Maven/Gradle, wrapper or official image | eclipse-temurin:<v>-jre; Spring Boot jar extracted into cache-friendly layers |
| PHP, Symfony, Laravel | Composer without dev dependencies, optimized autoloader, framework scripts | FrankenPHP with the ext-* from composer.json |
| Ruby, Rails | Bundler deployment mode, system packages for native gems (pg, mysql2, vips) | ruby:<v>-slim; Rails: bootsnap, asset precompilation, bin/docker-entrypoint, writable dirs only |
| .NET | dotnet publish of the app project |
aspnet or runtime, built-in non-root user |
| C / C++ | CMake or Meson release build (Conan / vcpkg dependencies), libstdc++ linked statically | distroless/cc:nonroot |
[docker]
version = "3.13" # runtime version of the base image
port = 8000
command = "gunicorn shop.wsgi --bind 0.0.0.0:8000" # what the container runs
build_command = "" # build step, e.g. "npm run build"
output_dir = "" # what the build produces (static site or self-contained server)
static = false # serve output_dir with nginx
Services
quoll reads which databases and caches the app talks to from its client libraries:
| Service | Detected from (examples) |
|---|---|
| Postgres | psycopg, asyncpg, pg, Prisma provider = "postgresql", pgx, sqlx, org.postgresql, pdo_pgsql, Symfony/Laravel .env, pg gem, Npgsql |
| MySQL | mysqlclient, mysql2, go-sql-driver, mysql-connector, pdo_mysql, trilogy, MySqlConnector |
| Redis | redis, ioredis, go-redis, jedis/lettuce, predis, StackExchange.Redis |
| MongoDB | pymongo, mongoose, mongo-driver, mongoid, MongoDB.Driver |
They are listed in [project] services and used twice:
- CI: the test job starts them as service containers and waits until they are healthy. It sets
DATABASE_URL,REDIS_URL,MONGODB_URIand thePG*variables, plus the framework's own: Laravel'sDB_*, Spring'sSPRING_DATASOURCE_*,mysql2://for Rails. A GitHub secret or GitLab CI/CD variable with the same name is never used for tests. - compose.yaml (written by
quoll docker init): the app plus its services, with healthchecks,depends_on: service_healthy, persistent volumes and an optional.envfor secrets.docker compose up --buildruns everything.
Delivery (CD)
quoll cd init # registry, image name → .github/workflows/cd.yml or .gitlab/cd.yml
quoll cd update / check
Every push to the default branch and every v* tag:
- builds the image (BuildKit);
- scans it with Trivy before anything is pushed, failing on fixable
CRITICAL/HIGHvulnerabilities; - pushes it with tags
:<branch>,:sha-<sha>,:latest(default branch) and:1.2.3/:1.2(release tags), plus BuildKit's provenance and SBOM attestations; - generates the SBOM of the pushed digest (CycloneDX, pipeline artifact) and, on
v*tags, attaches it to the GitHub / GitLab release; - signs the image and its SBOM with Sigstore: GitHub artifact attestations (
gh attestation verify oci://<image> --owner <org>), cosign keyless on GitLab (cosign verify <image> --certificate-identity-regexp … --certificate-oidc-issuer https://gitlab.com).
| GitHub | GitLab | |
|---|---|---|
| Pipeline | .github/workflows/cd.yml |
.gitlab/cd.yml, included by quoll's .gitlab-ci.yml |
| Runs after CI | through branch protection | always: its publish stage starts once every CI job passed |
| Default registry (no secret) | GHCR, with the workflow's token | the project's container registry, with the job token |
| Build | Buildx, GitHub Actions cache | Docker-in-Docker, a Buildx container builder; Trivy runs next to the image |
| Signature | artifact attestations (public repositories, or GitHub Enterprise Cloud for private ones) | cosign keyless with the job's OIDC token (gitlab.com: Sigstore's public instance doesn't trust self-managed issuers) |
Docker Hub (registry = "dockerhub") needs DOCKERHUB_USERNAME and DOCKERHUB_TOKEN. Multi-arch images are a platforms entry away.
[cd]
registry = "ghcr" # ghcr (GitHub) | gitlab (GitLab) | dockerhub
image = "ghcr.io/acme/api"
branches = ["main"]
release_tags = true
platforms = ["linux/amd64"] # e.g. ["linux/amd64", "linux/arm64"]
scan = true
severity = ["CRITICAL", "HIGH"]
ignore_unfixed = true
sbom = true # SBOM of the image: artifact + release asset
sign = true # Sigstore signature and attestations (set false on a private repo without GitHub Enterprise)
On GitHub, branch protection (set by quoll ci init) makes sure only commits that passed CI reach the default branch, and therefore the registry.
Kubernetes
quoll k8s init # [k8s] in quoll.toml, a Helm chart per project; the CI checks it, the delivery deploys it
quoll k8s update # regenerate from quoll.toml, showing the diff first
quoll k8s check # exit 1 if a chart no longer matches quoll.toml
Each project gets a Helm chart in chart/. The templates are the same everywhere; the values come from quoll.toml:
back/chart/
├── Chart.yaml
├── values.yaml # image, port, health check, resources, URLs of the other projects…
├── values-staging.yaml # what an environment changes: replicas, public host
├── values-production.yaml
└── templates/ # Deployment, Service, ServiceAccount, Ingress, PodDisruptionBudget, HPA
[k8s]
name = "back" # release, Service and Deployment: the others reach it at http://back:3000
health_path = "/health" # found in the code (/health, /healthz…); empty: TCP checks on the port
cpu = "100m" # requests; memory_limit caps the memory (no CPU limit: no throttling)
memory = "256Mi"
memory_limit = "512Mi"
max_replicas = 0 # > 0: a HorizontalPodAutoscaler up to this
ingress_class = "" # the cluster's default
cluster_issuer = "" # cert-manager ClusterIssuer for the TLS certificate
secret = "" # Secret with the app's secrets (DATABASE_URL…), default "<name>-env"
[k8s.environments.staging]
namespace = "shop-staging"
deploy_on = "branch" # every push to the [cd] branches
host = "api.staging.example.com" # Ingress; empty: reachable inside the cluster only
replicas = 1
[k8s.environments.production]
namespace = "shop"
deploy_on = "tag" # v* tags, after an approval
replicas = 2
Secure by default — the pods run as non-root (every image's user is numeric, so Kubernetes can check it), with a read-only root filesystem (the directories the app writes to — /tmp, nginx's cache, Next.js' .next/cache… — are emptyDir volumes; Laravel, Symfony and Ruby apps keep a writable one: the frameworks write in their own tree, and Ruby refuses emptyDir's world-writable temporary directory), all capabilities dropped, no privilege escalation, RuntimeDefault seccomp, no service account token. Rolling updates never remove a ready pod before its replacement is; with two replicas or more, a PodDisruptionBudget keeps one through node drains.
In the CI, a chart job lints the chart with each environment's values, checks the rendered manifests against Kubernetes' schemas (kubeconform) and scans them for misconfigurations (Trivy), failing on HIGH/CRITICAL.
In the delivery (with quoll cd), once the image is pushed, scanned and signed, a job per environment deploys it by digest — what was scanned is what runs:
| GitHub | GitLab | |
|---|---|---|
| Staging | deploy-staging, on pushes to the delivered branches |
deploy-staging (stage deploy), same |
| Production | deploy-production, on v* tags — protect the production environment with required reviewers |
deploy-production, on v* tags, started by hand (protect the environment to choose who can) |
| Cluster access | KUBECONFIG secret of each GitHub environment (the kubeconfig's content) |
KUBECONFIG CI/CD variable of type File, scoped to each environment |
| Before deploying | the image's provenance: gh attestation verify |
its signature: cosign verify (this project's pipelines) |
| Deploying | helm upgrade --install --rollback-on-failure: waits until the release is ready, rolls it back otherwise |
same |
The app's secrets live in the cluster: kubectl create secret generic back-env --from-env-file=.env.production -n shop. A private image needs a pull secret (pull_secret in [k8s]).
In a workspace, every project deploys to the same namespaces and reaches the others at their Service, <NAME>_URL=http://<name>:<port> — the same variables as the root compose.yaml, so the front-end's /api/ proxy works unchanged. quoll add service gives a new service its chart (same namespaces), quoll remove service drops it from the others' values. quoll new --k8s sets it all up from the start.
Creating a project
quoll new # interactive
quoll new shop --front angular --back express
quoll new shop --front angular@18 --back express@4 --node 20 --platform gitlab --cd --k8s --remote
quoll new shop --front angular --back none --service orders=express --service users=express@4
From nothing to a repository whose pipeline passes on its first push:
- creates the front-end in
front/, the back-end inback/and each--serviceinservices/<name>/(only one of them: the repository is the project); - writes, for each, its Dockerfile and
compose.yaml; then the workspace's CI, its rootcompose.yaml, with--k8sa Helm chart each, and with--cdthe delivery (which then deploys them); git init, a first commit — and with--remote, the GitHub/GitLab repository, pushed,mainprotected.
| Starter | Role | How |
|---|---|---|
angular |
front | Angular's own CLI (ng new) at the chosen major — angular@18 — plus ESLint (angular-eslint) |
express |
back | quoll's template: Express (express@4 for 4) and TypeScript, Vitest + Supertest, ESLint, /health, graceful shutdown |
Versions. name@version picks the framework's major; --node 20 the runtime: the generators then run in node:20 (so the dependencies and the lockfile match it), and .nvmrc makes the CI and the Dockerfile use it too. A version its maintainers no longer support is flagged at creation: the CI's dependency audit would fail on its known vulnerabilities.
Microservices
quoll add service billing=express # services/billing/, from the root or any member
quoll add service billing=express --in apps # apps/billing/
quoll add service creates the project, its Dockerfile and quoll.toml, adds it to [workspace] members, and regenerates what depends on the members: the pipeline (billing-lint, billing-test, billing-docker…), the root compose.yaml, Dependabot's config (unless edited by hand) and, when the other members publish images, its own delivery. Files you wrote yourself are left alone, with a warning.
quoll remove service billing # deletes services/billing/ (asks first; -y doesn't)
quoll remove service billing --keep-files # only takes it out of the workspace
quoll remove service does the opposite: the project leaves the members, its jobs, its compose service and BILLING_URL, its delivery and setup action are removed. It refuses to delete a directory with uncommitted changes.
Front-end → API. With a front-end and a back-end, quoll new makes the front-end call the API on its own origin, at /api/ (no CORS, no URL baked into the build): ng serve forwards there (proxy.conf.json), and so does nginx in the image, to the URL in BACK_URL, which the root compose.yaml sets:
# front/quoll.toml
[docker.proxy]
"/api/" = "BACK_URL" # path prefix = environment variable holding the API's URL (no path)
Without BACK_URL, the container stops at startup saying what to set (in production: the API's address in your platform).
The root compose.yaml (written by quoll docker init|update in a workspace, checked by quoll docker check) runs the whole platform with docker compose up --build:
- every member on one network, each reaching the others at
<NAME>_URL(BILLING_URL=http://billing:3000), and listening on its own host port (3000, 3001… when they share one); - one instance of each backing service, with a database per member on it (
orders,users…, Postgres and MySQL), created by a one-shot container at everyupwhen missing — so a service added later gets its own too; Redis and MongoDB are shared as they are; - each member's
.env(optional) for its secrets.
Adding a starter is a plugin's business: a Starter in its starters=(...), either a generator (starter.py calling the framework's CLI through quoll.starters.run, which uses the local tool or a container) or a template directory next to the plugin (templates/<name>/, copied with {{name}}, {{version}}, {{runtime}} filled in, then commands such as npm install).
quoll new replaces the scaffolding of 0.1.x (quoll init, quoll create-project, quoll list-types), removed.
Development
uv venv && uv pip install -e ".[dev]"
.venv/bin/pytest # validates every generated workflow with actionlint, every GitLab pipeline with its schema
.venv/bin/quoll ci check # quoll's own CI is generated by quoll
QUOLL_DOCKER_TESTS=check .venv/bin/pytest tests/docker # + lint every Dockerfile with `docker build --check`
QUOLL_DOCKER_TESTS=build .venv/bin/pytest tests/docker # + build and run real apps for each stack (slow)
QUOLL_GITLAB_TESTS=run .venv/bin/pytest tests/platforms # + run real projects' GitLab pipelines with gitlab-ci-local (slow)
Architecture
Everything language-, framework- or platform-specific lives in its own folder; the rest of quoll never names one.
quoll/
├── project.py # safe file access for detectors (missing = empty, invalid = warning)
├── languages/
│ ├── __init__.py # registry: built-ins + third-party plugins (entry points)
│ ├── base.py # the contract: Language, Framework, Detection, CISteps, FrameworkCI, DockerImage
│ ├── python/
│ │ ├── __init__.py # `language = Language(...)`: markers, package managers, tools, frameworks
│ │ ├── detect.py # Project -> Detection
│ │ ├── ci.py # CIConfig -> neutral steps (install, lint, test, audit, build) + toolchain:
│ │ │ # setup actions (GitHub), image and cache (GitLab)
│ │ ├── docker.py # DockerImage: defaults (port, command...) and template context
│ │ ├── Dockerfile.j2 # multi-stage template, split into blocks (build, runtime...)
│ │ └── frameworks/
│ │ └── django/
│ │ ├── __init__.py # `framework = Framework(...)`: extra lint tools / test runners
│ │ ├── detect.py # (Project, Detection) -> bool, refining the detection
│ │ ├── ci.py # FrameworkCI: only the hooks it needs (env, lint, test, before_build)
│ │ └── docker.py # subclass of the language's image (+ a Dockerfile.j2 extending it if needed)
│ ├── node/ go/ rust/ java/ php/ ruby/ dotnet/ cpp/
├── platforms/
│ ├── base.py # the contract: Platform (pipelines), PlatformAPI (repo, secrets, protection)
│ ├── github/ # workflows, gate job, dependabot, build → scan → push, REST API
│ └── gitlab/ # .gitlab-ci.yml, renovate.json, .gitlab/cd.yml, REST API
├── workspace.py # monorepos: members, the repository's settings (Repo), discovery
├── ci/ # [ci] config, detection, the neutral Step / Cache model (steps.py), and the
│ # language-independent tools: gitleaks, Semgrep, image checks (tools.py)
├── docker/ # language-agnostic: [docker] config, Dockerfile, .dockerignore, compose.yaml
├── cd/ # [cd] config
├── k8s/ # [k8s] config, the Helm chart (fixed templates + generated values), its CI checks
│ # and deploy commands, shared by both platforms
├── services.py # postgres, mysql, redis, mongodb: containers, healthchecks, app variables
└── config/quoll_toml.py # quoll.toml: shared [project] section + one section per feature
Adding a language
- Create
quoll/languages/<name>/with:detect.py: adetect(project) -> Detectionfunction, which also fillsservicesfrom the client libraries (quoll.services.detect_services);ci.py: aCIStepssubclass.setupinstalls the toolchain on GitHub,image(and optionallyimage_setup,cache) provides it on GitLab; every other step that uses a GitHub Action also gives the equivalentruncommand;docker.pyandDockerfile.j2: aDockerImagesubclass and its template;__init__.py: exposeslanguage = Language(...).
- Add
<name>to_BUILTINinquoll/languages/__init__.py. Its position sets the detection priority. - Add a sample project to
SAMPLE_BY_LANGUAGEintests/samples.pyand the language's own tests totests/languages/test_<name>.py.
Adding a framework
- Create
quoll/languages/<language>/frameworks/<name>/with:detect.py: returns True when the framework is used, and may adjust the detection;ci.py(optional): aFrameworkCIsubclass overriding only the hooks it needs;docker.py(optional): a subclass of the language's image overridingdefaultsorcontext. Add aDockerfile.j2only if the image differs: it starts with{% extends "<language>/Dockerfile.j2" %}and overrides only the blocks that change;services.py(optional): aservice_env(service, host)function, when the framework reads its database settings from its own variables;__init__.py: exposesframework = Framework(...).
- List it in the language's
frameworks=(...). Order sets the detection priority. - Add a sample project to
SAMPLE_BY_FRAMEWORK.
The contract tests (tests/languages/test_contract.py) then check that every sample is detected correctly. They also render the pipelines of both platforms for every declared package manager, lint tool and test runner, and validate each one (actionlint, GitLab's schema). quoll.toml validation, quoll ci detect, the prompts and dependabot pick up new languages and frameworks automatically.
A separate package can also ship a language or a framework without changing quoll:
# pyproject.toml of the plugin
[project.entry-points."quoll.languages"]
elixir = "quoll_elixir:language"
[project.entry-points."quoll.frameworks"]
remix = "quoll_remix:framework" # Framework(language="node", ...)
Requirements
- Python 3.9+
- A GitHub or GitLab repository (optional, for branch protection and secrets)
Metadata
Release files for quoll-cli 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| quoll_cli-0.2.0.tar.gz | 220.3 kB | With provenance | Details for quoll_cli-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| quoll_cli-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for quoll_cli-0.2.0-py3-none-any.whl |
Total release size: 454.3 kB
Release files / quoll_cli-0.2.0.tar.gz
| Download URL | quoll_cli-0.2.0.tar.gz |
|---|---|
| Size | 220.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
dd522fbb57f0ae35c02e9da71de4aee9702e09c109bba2a4243d1076499273d3
|
|
BLAKE2b-256 checksum How to use checksums |
59086960f065a6b8e6a238172a89d1ed5e51e19bbe0aeed0f97084c7276127a2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logRelease files / quoll_cli-0.2.0-py3-none-any.whl
| Download URL | quoll_cli-0.2.0-py3-none-any.whl |
|---|---|
| Size | 234.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7e17c271abcb30df6d0f012d57939f6843a8f3e737b42f39a37bb4eaddefef32
|
|
BLAKE2b-256 checksum How to use checksums |
7ad5eb2253dee2869c6db5992e2b7cd3a61ab7faec91bbfa6e4590c0ebb8ff86
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logSecurity for quoll-cli 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for quoll_cli-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.