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

```bash
# 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:

```bash
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:

```bash
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`:

```toml
[project]
dependencies = [
    "devx>=0.50.2",
]

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

### 3. Set up the Makefile

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

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

```text
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`:

```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](../tech/ci-cd-workflow.md) for details.

### 6. Configure release settings

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

```bash
devx tools generate-cliff-config
```

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

```toml
[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](cli-commands.md) for all available commands
- Read the [Architecture guide](../tech/architecture.md) to understand internals
- Read the [CI/CD Workflow guide](../tech/ci-cd-workflow.md) for pipeline details