devx/docs/tech/ci-cd-workflow.md

CI/CD Workflow

devx uses Gitea Actions for CI/CD automation. The workflow replicates GRM's automated pipeline but without molecule tests.

Workflows

CI (ci.yml)

Runs on pull requests. Jobs:

1. quality — lint (ruff, pyright, bandit, actionlint), unit tests with 100% coverage, test speed check, doc coverage, translation check, dependency scan
2. detect-changes — classify changes as user-facing or workflow-only
3. release-dry-run — dry-run the release script (only if user-facing changes)
4. pr-review — automated PR review
5. auto-merge — squash-merge PR when all checks pass

Post-merge (post-merge.yml)

Runs on every push to master. Jobs:

1. detect-type — check if commit is a release commit
2. validate-commit-msg — validate conventional commit format
3. release — calculate next version, update changelog, tag, push
4. sync-wiki — sync docs to Gitea wiki
5. badges — generate and push quality badges
6. vikunja — mark Vikunja task as done
7. configure-repo — ensure branch protection and labels

Publish (publish.yml)

Runs on tag pushes (v*). Builds the package, publishes to Gitea PyPI registry, and creates a Gitea release.

CI Scripts

auto_merge.py

Auto-merge PR when all CI checks pass. Reads task ID from .taskid, validates PR title format, checks Vikunja task exists, squash-merges with DEVX-N <conventional commit> title.

release.py

Automated release using git-cliff. Calculates next semver version from conventional commits, updates __version__ in __init__.py, updates CHANGELOG.md, runs lint and tests, commits with release: vX.Y.Z [skip ci], creates annotated tag, pushes.

publish.py

Builds package with python -m build, publishes to Gitea PyPI registry via twine, creates Gitea release with git-cliff-generated notes.

pr_review.py

Automated PR review. Checks architecture compliance, best practices, security, i18n, resource management, documentation, test coverage, and commit conventions. Posts inline comments and structured review.

notify_failure.py

Creates a Gitea issue when a CI workflow fails. Uses tea CLI for issue creation with failure labels.

post_merge.py

Updates Vikunja task after a merge to master. Extracts task ID from commit message, marks task as done, posts a comment with the merge SHA.

classify_changes.py

Classifies git changes as user-facing or workflow-only. Used to skip releases for infrastructure-only changes. Patterns are configurable.

discover_runners.py

Discovers available Gitea Actions runners at repo, org, and instance levels. Generates a dynamic matrix for parallel job distribution.

detect_release_commit.py

Detects whether the latest git commit is a release commit. Writes is-release=true or is-release=false to GitHub output.

push_badges.py

Generates SVG badge files from project metrics (tests, coverage, quality, version). Pushes to badges branch and updates README with cache-busting commit SHA URLs.

distribute_molecule.py

Distributes molecule (scenario, platform) pairs across N parallel runners. Discovers scenarios under ansible/roles/*/molecule/.

molecule_ci_guard.py

Runs molecule tests sequentially while polling Gitea for other runner failures. Aborts if another runner fails the same job.

validate_commit_msg.py

Validates commit messages. On feature branches: conventional commits only (no DEVX-N prefix). On master: must have DEVX-N prefix from auto-merge.