Caret’s CI/CD strategy combines GitHub Actions for automated quality gates with Coolify’s branch-watching auto-deploy for frictionless production releases. Every change that reaches theDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/arrozet/caret/llms.txt
Use this file to discover all available pages before exploring further.
prod branch should have passed linting, type checking, unit tests, integration tests, and a successful Docker build — Coolify then picks up the commit and redeploys the production stack automatically without any manual intervention. The pipeline is designed around two branches: main for integration work and prod for production promotion.
GitHub Actions workflow files have not yet been checked into
.github/workflows. The pipeline design documented on this page is the intended architecture, but the actual YAML workflow files still need to be created. Adding these workflow files is a tracked next step. The Coolify auto-deploy side is operational — it redeploys on every push to prod.Branch Strategy
| Branch | Purpose |
|---|---|
main | Primary integration branch — day-to-day feature and fix work lands here |
prod | Production branch — Coolify watches this branch and redeploys on every push |
main (via pull request and review) → prod (via a promotion merge or direct push when ready for release).
Pipeline Stages
The full intended pipeline runs four sequential stages. Each stage must pass before the next begins.tsc --noEmit) for type safety# Example for a Node service (via Makefile)
make api-gateway-lint
make document-service-lint
make frontend-lint
All lint targets are available as
make <service>-lint and their auto-fix variants as make <service>-lint-fix.make frontend-test-unit
make api-gateway-test-unit
make auth-service-test-unit
make document-service-test-unit
make collab-service-test-unit
make ai-service-test-unit
Integration tests — exercise service boundaries and database interactions (require Supabase credentials):
make frontend-test-integration
make api-gateway-test-integration
make auth-service-test-integration
make document-service-test-integration
make collab-service-test-integration
make ai-service-test-integration
End-to-end tests (optional / gated): Playwright browser tests that exercise the full user journey through the running stack. E2E tests are optional in the pipeline and can be skipped for hotfix deployments.
Builds every service image to verify the Dockerfiles are correct and confirms the production compose file is syntactically valid and all required environment variables are declared:
# Validate the production compose file
docker compose -f docker-compose.prod.yml config
# Build all production images
docker compose -f docker-compose.prod.yml build
docker-compose.prod.yml.Secrets Management
Secrets are split into two categories depending on where they are consumed.GitHub Actions Secrets
Values that are only needed during CI — for example credentials used to build Docker images, publish artefacts, or trigger Coolify webhooks. Store these in Settings → Secrets and variables → Actions on the GitHub repository.
Coolify Environment Variables
Runtime secrets consumed by containers at startup — database URLs, API keys, JWT secrets. Store these in the Coolify project’s environment variable editor so they are injected at deploy time and never persist in the repository.
Tooling Reference
| Service | Package Manager | Linter | Type Checker | Test Runner |
|---|---|---|---|---|
frontend | Bun | ESLint | tsc | Vitest |
api-gateway | Bun | ESLint | tsc | Vitest |
auth-service | Bun | ESLint | tsc | Vitest |
document-service | Bun | ESLint | tsc | Vitest |
collab-service | Bun | ESLint | tsc | Vitest |
ai-service | uv | Ruff | Pyright | Pytest |
Package manager discipline is strict: use Bun for all Node.js services and uv for the Python AI service. Never use npm, yarn, pnpm, pip, poetry, or pipenv — even in CI workflow files.
Emergency Deployments
Next Steps
The following workflow files need to be created under.github/workflows/ to complete the CI/CD pipeline:
lint.yml
Run ESLint + tsc across all Node services and Ruff + Pyright for the AI service on every pull request targeting
main.build.yml
Build all Docker images and validate
docker-compose.prod.yml on every push to main and prod.test-unit.yml
Run unit tests for all six services in parallel on every pull request.
test-integration.yml
Run integration tests against a live Supabase test project on merges to
main.deploy.yml
Trigger a Coolify webhook (or push to
prod) after all other jobs pass to initiate the production deploy.e2e.yml
Optional Playwright end-to-end suite gated on the
prod branch to validate critical user journeys after deploy.