oblachno-oss/devx

Public Access

Fork 0

Files

T

gitea-actions-bot cb126e83da chore: update badge URLs to commit 37543185 [skip ci]

2026-07-08 19:31:39 +00:00

8.3 KiB

Raw Blame History

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 project to be reusable across all oblachno-oss repositories.

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

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)

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:

[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:

[project]
dependencies = [
    "devx>=0.38.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.38.0" or "devx>=0.38.0,<0.39".

Optional extras

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 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 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 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 for the full configuration reference, PR workflow, and project conventions.

Wiki pages

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

License

GPL-3.0

8.3 KiB Raw Blame History