Visit djangoplay.org ↗
gitaiflow / Deployment / Local Development Setup
DocsgitaiflowDeploymentLocal Development Setup

Local Development Setup

gitaiflow requires Python 3.11+ and native compilation toolchains (gcc/clang, patchelf, zstandard) if you intend to compile the binary locally.

2 min readApplies to v1.1.3
On this page ▾
  1. 1. Environment Setup
  2. 2. Test Suite Execution
  3. 3. Linting
  4. 4. Local Native Compilation (macOS ARM64)
  5. 5. Cleaning Build Artifacts
  6. Repository Layout

1. Environment Setup

bash
git clone https://gitlab.com/clizero/gitaiflow.git
cd gitaiflow

python3 -m venv .venv
source .venv/bin/activate

pip install -e .[dev]
pip install -U nuitka zstandard

Or via the Makefile:

bash
make install

2. Test Suite Execution

bash
python3 -m pytest tests/ -v

Or:

bash
make test

Tests import the package directly from the checkout (pythonpath = ["."] in pyproject.toml). Filesystem-sensitive tests (usage log, telemetry consent) always isolate HOME to a temporary directory rather than touching the developer's real ~/.gitaiflow.

For the full deterministic regression suite (date parsing, version resolution, commit parsing, diff helpers, artifacts, JSON/Markdown output, usage logging, changelog bucketing/validation/rendering/merging) or telemetry consent tests specifically, see the internal regression-suite docs (not published here).

3. Linting

bash
ruff check .

Or:

bash
make lint
make format   # ruff check . --fix

4. Local Native Compilation (macOS ARM64)

bash
chmod +x scripts/install/compile.sh
./scripts/install/compile.sh

Or invoke Nuitka manually:

bash
PYTHONPATH=. python3 -m nuitka \
  --standalone \
  --onefile \
  --remove-output \
  --assume-yes-for-downloads \
  --include-package=gitaiflow \
  --include-package-data=gitaiflow \
  --include-package=httpx \
  --include-package-data=certifi \
  --output-dir=bin \
  --output-filename=gitaiflow \
  gitaiflow/generate_summary.py

chmod +x bin/gitaiflow
./bin/gitaiflow --version

Or via Makefile:

bash
make compile
# copies bin/gitaiflow -> installers/gitaiflow-darwin-arm64

5. Cleaning Build Artifacts

bash
make clean

Removes build/, dist/, bin/, *.egg-info, .cache/, *.build, *.dist, and every file under installers/.

Repository Layout

Two independent things ship from this one repository: the gitaiflow binary (what end users install), and the telemetry receiver (a small internal service you run separately, not part of the binary). They share a repo and a CI pipeline but nothing else at runtime.

text
gitaiflow/                        (repo root)
├── gitaiflow/                     <- source package compiled into the binary
│   ├── config/
│   ├── 
│   ├── prompts/
│   ├── templates/
│   └── generate_summary.py        <- entry point
├── telemetry_server/               <- standalone Flask receiver, deployed separately
│   ├── app.py                        to its own host (internal runbook, not published here)
│   └── requirements.txt
├── scripts/
│   ├── install/
│   │   ├── compile.sh
│   │   ├── install.sh
│   │   └── install.ps1
│   ├── r2/
│   │   ├── gitai_manifest.json
│   │   ├── gitai_r2.sh
│   │   └── generate_gitai_manifest.py
│   └── release/
│       └── registry_update.sh
├── tests/
├── Makefile
├── pyproject.toml
└── README.md

For the architecture behind the gitaiflow/ package, see ../architecture/gitaiflow.md.