# devx — Reusable Development & CI/CD Tools

A Python package providing reusable development and CI/CD automation tools for
oblachno-oss projects. devx consolidates release management, PR automation,
wiki sync, badge generation, translation checks, documentation coverage,
parallel test distribution, and more into a single installable package.

It was extracted from the [GRM](https://git.oblachno.oblachno.fyi/oblachno-oss/grm)
project to be reusable across all oblachno-oss repositories.

> An open-source project from **Oblachno** (облачно means *cloudy* in Bulgarian).

[![CI](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions/workflows/ci.yml/badge.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
[![License: GPL-3.0](https://img.shields.io/badge/license-GPL--3.0-blue)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/src/branch/master/LICENSE)
[![Coverage](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/8359580812bc8c105f6567033253cb9eb7249913/coverage.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
[![Tests](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/8359580812bc8c105f6567033253cb9eb7249913/tests.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
[![Docs](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/8359580812bc8c105f6567033253cb9eb7249913/docs.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/wiki)
[![Code Quality](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/8359580812bc8c105f6567033253cb9eb7249913/quality.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
[![Version](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/8359580812bc8c105f6567033253cb9eb7249913/version.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/releases)
[![Python](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/8359580812bc8c105f6567033253cb9eb7249913/python.svg)](https://www.python.org/downloads/)

## Overview

devx provides a complete, opinionated CI/CD pipeline for any project hosted on
a Gitea instance with Gitea Actions. Install the package, declare configuration
via environment variables and `pyproject.toml`, and inherit:

- **Automated releases** — git-cliff-driven semver versioning, changelog
  generation, tagging, and publishing to a Gitea PyPI registry.
- **PR automation** — squash-merge with task ID validation, automated PR
  review with inline comments, and conventional commit enforcement.
- **Smart change classification** — user-facing vs workflow-only change
  detection so infrastructure-only changes skip releases.
- **Documentation sync** — push `docs/` markdown to the Gitea wiki with
  integrity verification.
- **Quality badges** — self-contained SVG badges for coverage, tests, docs,
  quality, version, and Python version.
- **Translation checks** — validate i18n keys against source code, detect
  dead keys and missing languages.
- **Parallel test distribution** — split test files or molecule scenarios
  across CI runners with cross-runner fail-fast.
- **Developer tools** — environment setup, CI tool installation, test speed
  enforcement, repository configuration.
- **i18n** — built-in translations for English, Bulgarian, German, Russian,
  Chinese, and Polish; projects can extend with their own keys.

## Installation

devx is published to the Gitea PyPI registry at
`https://git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple`.
The registry is publicly readable — no authentication required to install.

### Quick install (one-off)

```bash
pip install devx --index-url https://git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple
```

### Persistent configuration (recommended)

Add the registry to `~/.pip/pip.conf`:

```ini
[global]
extra-index-url = https://git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple
```

Then `pip install devx` works without specifying `--index-url`.

### As a dependency in another project

Add devx to your `pyproject.toml` dependencies and configure the registry:

```toml
[project]
dependencies = [
    "devx>=0.27.0",
]

[tool.pip]
extra-index-url = "https://git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple"
```

Pin a specific version if needed: `"devx==0.27.0"` or `"devx>=0.27.0,<0.28"`.

### Optional extras

```bash
pip install "devx[ci,lint]"      # CI runners and linting (pytest, ruff, pyright, bandit, build, twine)
pip install "devx[molecule]"     # Molecule testing for Ansible projects
pip install "devx[dev]"          # Full local development (ci + lint + build + twine)
```

## Architecture

devx is a self-contained Python package under `src/devx/`:

- **Core modules** — `config.py`, `exceptions.py`, `i18n.py`, `api_clients.py`,
  `gitea_cli.py`, `cli.py`, `opentofu.py`
- **CI automation** (`devx.ci`) — release, publish, auto_merge, pr_review,
  classify_changes, sync_wiki, push_badges, check_translations, doc_coverage,
  validate_commit_msg, detect_release_commit, notify_failure, post_merge,
  discover_runners, distribute_files, integration_guard
- **Dev tools** (`devx.tools`) — setup, install_tools, check_test_speed,
  configure_repo, generate_badges, generate_cliff_config, install_checkmake
- **Molecule tools** (`devx.molecule`) — Optional, for projects with Ansible
  roles: distribute_molecule, molecule_ci_guard, molecule_all, discover_runners,
  start_docker, platforms

See [Architecture](Architecture) for the full package structure, module
descriptions, design principles, and data flow diagrams.

## CI/CD pipeline

devx uses Gitea Actions with three workflows:

- **CI** (`ci.yml`) — runs on pull requests: quality checks, change detection,
  release dry-run, automated PR review, and auto-merge.
- **Post-merge** (`post-merge.yml`) — runs on every push to master: release
  versioning, wiki sync, badge generation, Vikunja task updates, and repo
  configuration.
- **Publish** (`publish.yml`) — runs on tag pushes: builds the package,
  publishes to the Gitea PyPI registry, and creates a Gitea release.

See [CI/CD Workflow](CI-CD-Workflow) for the full pipeline documentation,
including the post-merge job graph, release process, badge generation, and
wiki sync details.

## CLI commands

devx provides a `devx` CLI with three command groups:

- `devx ci <command>` — CI/CD automation (17 commands)
- `devx tools <command>` — Developer tools (9 commands)
- `devx molecule <command>` — Molecule testing (4 commands, optional)

See [CLI Commands](CLI-Commands) for full command documentation with examples.

## Configuration

devx reads configuration from `DEVX_*` environment variables with `.env` file
fallback. Key variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `DEVX_GITEA_API_URL` | `https://git.oblachno.oblachno.fyi/api/v1` | Gitea API base URL |
| `DEVX_VIKUNJA_API_URL` | `https://work.oblachno.oblachno.fyi/api/v1` | Vikunja API base URL |
| `DEVX_REPO_OWNER` | **(must be set)** | Repository owner |
| `DEVX_REPO_NAME` | **(must be set)** | Repository name |
| `DEVX_TASK_PREFIX` | `DEVX` | Task ID prefix (GRM, OBL-INFRA, etc.) |
| `DEVX_LANG` | `en` | Language for i18n (en, bg, de, ru, zh, pl) |
| `CI_GITEA_TOKEN` | — | Gitea API token |
| `VIKUNJA_TOKEN` | — | Vikunja API token |

See [AGENTS.md](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/src/branch/master/AGENTS.md)
for the full configuration reference, PR workflow, and project conventions.

## Wiki pages

- [Home](Home) — This page
- [Getting Started](Getting-Started) — Installation, configuration, and quick start guide
- [CLI Commands](CLI-Commands) — Full CLI command documentation with examples
- [Architecture](Architecture) — Package structure, module descriptions, design principles
- [CI/CD Workflow](CI-CD-Workflow) — Pipeline documentation, workflows, and CI scripts

## Links

- **Source**: [https://git.oblachno.oblachno.fyi/oblachno-oss/devx](https://git.oblachno.oblachno.fyi/oblachno-oss/devx)
- **Releases**: [https://git.oblachno.oblachno.fyi/oblachno-oss/devx/releases](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/releases)
- **Actions**: [https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
- **GRM (origin project)**: [https://git.oblachno.oblachno.fyi/oblachno-oss/grm](https://git.oblachno.oblachno.fyi/oblachno-oss/grm)

## License

GPL-3.0