CT-Automation

CT-Automation is the standalone CarrTech automation product. Its first automation engine is Ansible, and its first UI/client is the CT-Ops integration, but the product must be designed so it can later ship with its own dedicated UI and operate without CT-Ops.

The current repository starts as the product architecture, API contract, and agent task backlog. Implementation should happen here once the initial service scaffold is created.

Product Direction

CT-Automation owns:

• automation projects and Git sync
• inventories and inventory sources
• credentials and secret references
• job templates
• playbook execution
• event streams, artifacts, reports, and audit records
• schedules, approvals, RBAC, and policy

CT-Ops is one integrating client. CT-Ops may provide managed host inventory, launch automation, and show summaries or embedded views, but CT-Automation is the system of record for automation.

Important Documents

• Vision
• Architecture
• Service Stack ADR
• Security Model
• CT-Ops Integration Contract
• Inventory Model
• Run Reporting Model
• CT-Ops Job Wizard Plan
• CT-Ops Live Visual Log Plan
• MVP End-To-End Validation
• Schedules and Recurring Runs
• Approvals and Protected Templates
• Standalone UI Architecture
• API Contract
• Docker Hub Deployment
• Roadmap
• Agent Task Process
• Task Index

Agent Workflow

Agents should read AGENTS.md and tasks/README.md, claim exactly one task from tasks/backlog/, commit and push the claim, complete that task, then mark it complete with validation notes.

The backlog is intentionally split into small jobs so scheduled agents can pick up one task at a time without duplicating work.

Service Scaffold

CT-Automation is scaffolded as a Python 3.12 service with separate API and worker packages under src/ct_automation. The intended production stack is FastAPI, SQLAlchemy, Alembic, PostgreSQL, Ansible Runner, Pytest, Ruff, and a containerized runtime. Runtime dependencies are introduced by the task that first needs each concrete behavior.

Local smoke check:

PYTHONPATH=src python -m ct_automation smoke

Run the test harness:

python -m pip install -e ".[dev]"
python -m pytest

Run the dependency-free migration smoke check:

PYTHONPATH=src python -m ct_automation migrate-smoke

Compile the scaffold:

python -m compileall src

Build the container image:

docker build -t ct-automation:dev .

Run the container API:

docker run --rm -p 8080:8080 ct-automation:dev

Then open http://localhost:8080/healthz.

Container Publishing

Forgejo Actions publishes docker.io/carrtechdev/ct-automation from the Publish Docker Image workflow on pushes to main. The workflow publishes the repository version from pyproject.toml as a development tag, for example dev-0.1.0.

After testing that development image, run the Promote Docker Image workflow with the same version number to retag the exact same digest as the production tags, for example 0.1.0 and latest. Production deployments should use the versioned production tag, latest, or the digest behind that tag.

Required Forgejo Actions secrets:

• DOCKERHUB_USERNAME
• DOCKERHUB_TOKEN