oblachno-oss/devx
Public Access
2
0
Fork 0
Code Issues 36 Pull Requests Actions Packages Projects Releases 2 Wiki Activity

Sync wiki from docs/ [skip ci]

Devin CI
2026-08-09 09:39:15 +00:00
parent 97c79e18d4
commit af025e2b25
4 changed files with 121 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Architecture.md
+6 -6
@@ -86,11 +86,11 @@ overridden via environment variables with the `DEVX_` prefix. Provides:
- `GITEA_API_URL` / `VIKUNJA_API_URL` — API endpoints - `GITEA_API_URL` / `VIKUNJA_API_URL` — API endpoints
- `REPO_OWNER` — repository owner (must be set per-project) - `REPO_OWNER` — repository owner (must be set per-project)
- `TASK_PREFIX` / `TASK_ID_RE` — task ID prefix and regex (for example, `DEVX-N`) - `TASK_PREFIX` / `TASK_ID_RE` — task ID prefix and regular expression (for example, `DEVX-N`)
- `VIKUNJA_PROJECT_ID` — Vikunja project for task tracking - `VIKUNJA_PROJECT_ID` — Vikunja project for task tracking
- `DEFAULT_TIMEOUT`, `DEFAULT_PER_PAGE` — HTTP client defaults - `DEFAULT_TIMEOUT`, `DEFAULT_PER_PAGE` — HTTP client defaults
- `MAX_RETRIES`, `RETRY_BACKOFF_BASE`, `RETRY_STATUS_CODES` — retry config - `MAX_RETRIES`, `RETRY_BACKOFF_BASE`, `RETRY_STATUS_CODES` — retry config
- `CONVENTIONAL_RE` — conventional commit format regex - `CONVENTIONAL_RE` — conventional commit format regular expression
### `exceptions.py` ### `exceptions.py`
@@ -108,7 +108,7 @@ wraps user-facing strings for translation.
Projects can extend translations by setting `DEVX_TRANSLATIONS_PATH` to a Projects can extend translations by setting `DEVX_TRANSLATIONS_PATH` to a
custom JSON file. Keys from the project's file are merged on top of devx's custom JSON file. Keys from the project's file are merged on top of devx's
built-in translations, allowing projects to override or add keys without built-in translations, allowing projects to override, or add keys without
modifying the package. modifying the package.
### `api_clients.py` ### `api_clients.py`
@@ -170,7 +170,7 @@ from `devx.api_clients`, `devx.config`, `devx.gitea_cli`, and `devx.i18n`.
Automated release using git-cliff. Calculates the next semver version from Automated release using git-cliff. Calculates the next semver version from
conventional commits since the last tag, updates `__version__` in conventional commits since the last tag, updates `__version__` in
`__init__.py` and `CHANGELOG.md`, runs lint and tests to verify the release `__init__.py` and `CHANGELOG.md`, runs lint, and tests to verify the release
is healthy, commits with `release: vX.Y.Z [skip ci]`, creates an annotated is healthy, commits with `release: vX.Y.Z [skip ci]`, creates an annotated
tag, and pushes both to master. tag, and pushes both to master.
@@ -287,7 +287,7 @@ Click commands from `cli.py` and verifies each has documentation in
### `discover_runners.py` ### `discover_runners.py`
Discovers available Gitea Actions runners at three levels: repository, Discovers available Gitea Actions runners at three levels: repository,
organization, and instance (admin). Falls back to the `MOLECULE_RUNNERS` repo organization, and instance (administrator). Falls back to the `MOLECULE_RUNNERS` repo
variable or `DEFAULT_MAX_RUNNERS` (3). Outputs runner count or a JSON index variable or `DEFAULT_MAX_RUNNERS` (3). Outputs runner count or a JSON index
array for use as a dynamic matrix in Gitea Actions. array for use as a dynamic matrix in Gitea Actions.
@@ -329,7 +329,7 @@ Supports `--tool` to install specific tools and `--list` to show status.
Runs unit tests and enforces execution-time budgets. Two quality gates: Runs unit tests and enforces execution-time budgets. Two quality gates:
total suite time must not exceed `--max-seconds` (default: 10s), and no total suite time must not exceed `--max-seconds` (default: 10s), and no
individual test may exceed `--max-single-seconds` (default: 0.5s, 0 to individual test may exceed `--max-single-seconds` (default: 0.5s, 0 to
disable). Runs `make test-unit` with `PYTEST_ADDOPTS=--durations=0`. off). Runs `make test-unit` with `PYTEST_ADDOPTS=--durations=0`.
### `check_test_isolation.py` ### `check_test_isolation.py`
CLI-Commands.-.md
+104 -4
@@ -85,7 +85,7 @@ devx ci detect-release-commit
Discover available Gitea Actions runners for dynamic job distribution. Discover available Gitea Actions runners for dynamic job distribution.
Queries the Gitea API for registered runners at repository, organization, and Queries the Gitea API for registered runners at repository, organization, and
instance (admin) levels. Falls back to `MOLECULE_RUNNERS` repo variable or instance (administrator) levels. Falls back to `MOLECULE_RUNNERS` repo variable or
`DEFAULT_MAX_RUNNERS` (3). `DEFAULT_MAX_RUNNERS` (3).
```bash ```bash
@@ -315,6 +315,56 @@ devx ci validate-commit-msg commit-msg.txt --branch master
Options: Options:
- `--branch <branch>` — override branch detection (for CI use) - `--branch <branch>` — override branch detection (for CI use)
### `devx ci cancel-superseded-runs`
Cancel in-flight CI runs for the same PR branch when a new push triggers
a new run. Uses the Gitea Actions API to list running pull_request runs
and cancel those with a lower run ID on the same branch.
```bash
devx ci cancel-superseded-runs \
--repo "$REPOSITORY" \
--current-run-id "$GITHUB_RUN_ID" \
--head-branch "$HEAD_REF"
```
Options:
- `--repo <owner/repo>` — repository (required)
- `--current-run-id <id>` — current run ID, not cancelled (required)
- `--head-branch <branch>` — PR head branch name (required)
- `--dry-run` — list superseded runs without cancelling
- `--base-url <url>` — Gitea base URL (default: `GITEA_API_URL` env var)
### `devx ci check-workflow-artifact-deps`
Verify that workflow jobs downloading artifacts depend on the uploading
job. Prevents the class of bug where a download job runs in parallel
with the upload job and fails because the artifact isn't available yet.
```bash
devx ci check-workflow-artifact-deps
devx ci check-workflow-artifact-deps --workflow .gitea/workflows/ci.yml
```
Options:
- `--workflow <path>` — check a specific workflow file
- `--workflows-dir <path>` — override workflows directory
### `devx ci check-workflow-tofu-init`
Verify that workflow jobs using tofu state (tofu output/plan/apply or
scripts that call them) have a tofu-init step in the same job.
```bash
devx ci check-workflow-tofu-init
devx ci check-workflow-tofu-init --workflow .gitea/workflows/deploy.yml
```
Options:
- `--workflow <path>` — check a specific workflow file
- `--workflows-dir <path>` — override workflows directory
- `--state-script <name>` — add a script that uses tofu state (repeatable)
## Tools Commands ## Tools Commands
### `devx tools check-test-speed` ### `devx tools check-test-speed`
@@ -323,7 +373,7 @@ Run unit tests and enforce execution-time budgets. Two quality gates:
- **Total suite time** must not exceed `--max-seconds` (default: 10s) - **Total suite time** must not exceed `--max-seconds` (default: 10s)
- **Per-test time** — no individual test may exceed `--max-single-seconds` - **Per-test time** — no individual test may exceed `--max-single-seconds`
(default: 0.5s, 0 to disable) (default: 0.5s, 0 to turn off)
Runs `make test-unit` with `PYTEST_ADDOPTS=--durations=0` so pytest emits Runs `make test-unit` with `PYTEST_ADDOPTS=--durations=0` so pytest emits
per-test timing lines. per-test timing lines.
@@ -369,7 +419,7 @@ devx tools check-test-isolation --src-dir src/
Pytest plugin options (automatic when devx is installed): Pytest plugin options (automatic when devx is installed):
- `--no-test-isolation` — disable static analysis and runtime subprocess audit - `--no-test-isolation` — turn off static analysis and runtime subprocess audit
- `--test-isolation-max-loop N` — max iterations per loop (default: 100) - `--test-isolation-max-loop N` — max iterations per loop (default: 100)
### `devx tools configure-repo` ### `devx tools configure-repo`
@@ -414,7 +464,7 @@ devx tools generate-cliff-config --prefix GRM --force # overwrite existing
Options: Options:
- `--prefix <prefix>` — task ID prefix (default: `DEVX_TASK_PREFIX` env var - `--prefix <prefix>` — task ID prefix (default: `DEVX_TASK_PREFIX` env var
or `DEVX`) or `DEVX`)
- `--output <file>` — output file path (default: `cliff.toml`) - `--output <file>` — output path (default: `cliff.toml`)
- `--force` — overwrite existing file - `--force` — overwrite existing file
### `devx tools install-checkmake` ### `devx tools install-checkmake`
@@ -488,6 +538,56 @@ devx tools pr-rebase # auto-detect PR from current branch
Options (pass after `--`): Options (pass after `--`):
- `--pr <N>` — PR number (auto-detected from current branch if omitted) - `--pr <N>` — PR number (auto-detected from current branch if omitted)
### `devx tools check-docker-init`
Check that Docker Compose services with healthchecks have `init: true`.
Without `init: true`, CMD-SHELL healthchecks spawn child processes that
become zombies when PID 1 doesn't reap them.
```bash
devx tools check-docker-init
devx tools check-docker-init --path path/to/docker-compose.yml.j2
```
Options:
- `--path <path>` — check a specific file or directory
- `--templates-dir <path>` — override templates directory (default: `ansible/roles/`)
### `devx tools check-ansible-set-fact-to-json`
Check that Ansible `set_fact` tasks don't misuse `| to_json`. Using
`to_json` in `set_fact` converts native Python types to JSON strings,
causing iteration bugs (for example, iterating over characters instead
of list items).
```bash
devx tools check-ansible-set-fact-to-json
devx tools check-ansible-set-fact-to-json --path path/to/playbook.yml
```
Options:
- `--path <path>` — check a specific file or directory
- `--ansible-dir <path>` — override ansible directories (repeatable)
### `devx tools check-alert-rules`
Validate rendered Prometheus alert rules with `promtool check rules`.
Renders a Jinja2 template with test values and validates the output.
Skips (exits 0) if promtool is not on PATH.
```bash
devx tools check-alert-rules \
--template-path ansible/roles/observability/templates
devx tools check-alert-rules \
--template-path ansible/roles/observability/templates \
--var grafana_base_url=https://grafana.example.com
```
Options:
- `--template-path <path>` — path to templates directory (required)
- `--template-name <name>` — template filename (default: `alert-rules.yml.j2`)
- `--var key=value` — template variables (repeatable)
## Molecule Commands ## Molecule Commands
Molecule commands require the `molecule` extra (`pip install devx[molecule]`). Molecule commands require the `molecule` extra (`pip install devx[molecule]`).
Getting-Started.-.md
+2 -2
@@ -48,12 +48,12 @@ Add devx to your `pyproject.toml`:
```toml ```toml
[project] [project]
dependencies = [ dependencies = [
"devx>=0.48.2", "devx>=0.49.0",
] ]
[project.optional-dependencies] [project.optional-dependencies]
dev = [ dev = [
"devx>=0.48.2", "devx>=0.49.0",
] ]
``` ```
Home.md
+9 -9
@@ -8,16 +8,16 @@ parallel test distribution, and more into a single installable package.
It was extracted from the [GRM](https://git.oblachno.oblachno.fyi/oblachno-oss/grm) It was extracted from the [GRM](https://git.oblachno.oblachno.fyi/oblachno-oss/grm)
project to be reusable across all oblachno-oss repositories. project to be reusable across all oblachno-oss repositories.
> An open-source project from **Oblachno** (облачно means *cloudy* in Bulgarian). > 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) [![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) [![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/3ae96e9fe24eb247be074f92e4a9153033dc1ed7/coverage.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions) [![Coverage](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/8c02351c3190af51b1dfe545a7abbec665c51559/coverage.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
[![Tests](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/3ae96e9fe24eb247be074f92e4a9153033dc1ed7/tests.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions) [![Tests](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/8c02351c3190af51b1dfe545a7abbec665c51559/tests.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
[![Docs](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/3ae96e9fe24eb247be074f92e4a9153033dc1ed7/docs.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/wiki) [![Docs](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/8c02351c3190af51b1dfe545a7abbec665c51559/docs.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/wiki)
[![Code Quality](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/3ae96e9fe24eb247be074f92e4a9153033dc1ed7/quality.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions) [![Code Quality](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/8c02351c3190af51b1dfe545a7abbec665c51559/quality.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
[![Version](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/3ae96e9fe24eb247be074f92e4a9153033dc1ed7/version.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/releases) [![Version](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/8c02351c3190af51b1dfe545a7abbec665c51559/version.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/releases)
[![Python](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/3ae96e9fe24eb247be074f92e4a9153033dc1ed7/python.svg)](https://www.python.org/downloads/) [![Python](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/8c02351c3190af51b1dfe545a7abbec665c51559/python.svg)](https://www.python.org/downloads/)
## Overview ## Overview
@@ -74,14 +74,14 @@ Add devx to your `pyproject.toml` dependencies and configure the registry:
```toml ```toml
[project] [project]
dependencies = [ dependencies = [
"devx>=0.48.2", "devx>=0.49.0",
] ]
[tool.pip] [tool.pip]
extra-index-url = "https://git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple" extra-index-url = "https://git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple"
``` ```
Pin a specific version if needed: `"devx==0.48.2"` or `"devx>=0.48.2,<0.49"`. Pin a specific version if needed: `"devx==0.49.0"` or `"devx>=0.49.0,<0.50"`.
### Optional extras ### Optional extras