devx/docs/user/getting-started.md

Getting Started with devx

This guide walks you through installing devx, configuring it for your project, and setting up a complete CI/CD pipeline.

Prerequisites

• Python 3.12+
• A Gitea instance with Actions enabled
• A Gitea API token with repo, workflow, and organization scopes
• (Optional) Vikunja API token for task tracking integration

Installation

devx is published to the Gitea PyPI registry. Configure pip to use it:

# Configure Gitea PyPI registry
pip config set global.extra-index-url https://git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple

# Install devx
pip install devx

Or install from source:

git clone https://git.oblachno.oblachno.fyi/oblachno-oss/devx.git
cd devx
make setup

Quick Start

1. Configure environment variables

Create a .env file in your project root:

CI_GITEA_TOKEN=your_gitea_api_token
VIKUNJA_TOKEN=your_vikunja_api_token  # optional

2. Add devx to your project

Add devx to your pyproject.toml:

[project]
dependencies = [
    "devx>=0.49.5",
]

[project.optional-dependencies]
dev = [
    "devx>=0.49.5",
]

3. Set up the Makefile

devx provides a shared Makefile fragment. Add this to your Makefile:

include devx.mak

Run devx tools setup to install all development tools (actionlint, git-cliff, tea CLI, etc.) and configure pre-commit hooks.

4. Create the docs structure

devx expects a docs/ directory with at minimum:

docs/
├── index.md          # Documentation home page
├── mapping.json      # Wiki page title mappings
├── user/             # User-facing documentation
│   └── cli-commands.md
└── tech/             # Technical documentation
    ├── architecture.md
    └── ci-cd-workflow.md

Example docs/mapping.json:

{
  "index.md": "Home",
  "user/cli-commands.md": "CLI-Commands",
  "tech/architecture.md": "Architecture",
  "tech/ci-cd-workflow.md": "CI-CD-Workflow"
}

5. Set up CI workflows

Create .gitea/workflows/ci.yml and .gitea/workflows/post-merge.yml in your project. See the CI/CD Workflow guide for details.

6. Configure release settings

Add a cliff.toml for git-cliff-based versioning:

devx tools generate-cliff-config

Add [tool.devx] section to pyproject.toml for project-specific config:

[tool.devx]
# Vikunja project ID for task tracking
vikunja_project_id = 6

[tool.devx.classify]
# File patterns that are infrastructure (no release needed)
infrastructure = [
    ".gitea/**",
    "docs/**",
    "tests/**",
    "AGENTS.md",
    "README.md",
    "CHANGELOG.md",
]

Available Tools

CI/CD Automation (devx.ci.*)

• devx.ci.release — Automated semver versioning and tagging
• devx.ci.publish — Package publishing to Gitea PyPI registry
• devx.ci.auto_merge — Squash-merge automation with task ID validation
• devx.ci.pr_review — Automated PR review with inline comments
• devx.ci.classify_changes — User-facing vs workflow-only change detection
• devx.ci.sync_wiki — Push docs/ to Gitea wiki
• devx.ci.doc_coverage — Documentation coverage checker
• devx.ci.lint_docs — Documentation linter (structure, links, headings)
• devx.ci.check_translations — i18n translation completeness checker
• devx.ci.notify_failure — Create Gitea issues on CI failures
• devx.ci.distribute_files — Parallel test file distribution
• devx.ci.distribute_items — Parallel item distribution across runners
• devx.ci.discover_runners — Dynamic runner discovery via Gitea API

Development Tools (devx.tools.*)

• devx.tools.setup — Environment setup (venv, deps, hooks, tools)
• devx.tools.install_tools — Install CI/CD tools (actionlint, git-cliff, tea)
• devx.tools.create_task — Create Vikunja tasks
• devx.tools.create_pr — Create Gitea PRs with task ID in title
• devx.tools.configure_repo — Configure branch protection and labels
• devx.tools.generate_badges — Generate quality badge SVGs
• devx.tools.check_test_speed — Enforce test execution speed limits

Next Steps

• Read the CLI Commands reference for all available commands
• Read the Architecture guide to understand internals
• Read the CI/CD Workflow guide for pipeline details