Public Access
176 lines
8.3 KiB
Markdown
176 lines
8.3 KiB
Markdown
# 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).
|
|
|
|
[](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
|
|
[](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/src/branch/master/LICENSE)
|
|
[](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
|
|
[](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
|
|
[](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/wiki)
|
|
[](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
|
|
[](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/releases)
|
|
[](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
|