# Bitrix Sprint Migration

> Covers Bitrix module sprint.migration — Version migrations, HelperManager (Iblock/Hlblock/Option/Agent/…), builders (run), CLI migrate.php (add/ls/up/down/redo/mark), configs migrations.*.php, restartable batches, exchange dirs. Use when creating or applying DB/schema/content migrations, exporting iblock/HL/options via builders, or debugging migration state. Key terms — sprint.migration, Version, up/down, HelperManager, saveIblock, saveHlblock, migrate.php, version builders, migration_dir.

- Skill: `bxmaximum/bitrix-sprint-migration` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add bxmaximum/bitrix-sprint-migration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bxmaximum/bitrix-sprint-migration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: bxmaximum (https://skillmd.com/u/bxmaximum)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bxmaximum/bitrix-sprint-migration

---


# Bitrix sprint.migration

Module **`sprint.migration`** (Composer: `andreyryabin/sprint.migration`) stores
schema/content changes as PHP classes under VCS and applies them on each copy
of the project via CLI or admin UI.

Install location (either is valid; resolve before calling CLI):

| Path | Typical when |
| --- | --- |
| `/local/modules/sprint.migration/` | Composer / marketplace into `local` |
| `/bitrix/modules/sprint.migration/` | Marketplace / copy into kernel modules |

Below, **`{module}`** means that resolved directory. Do **not** edit module
source. Write only migration files and optional configs (usually under
`php_interface/`).

Progressive disclosure: open **only** the rule files that match the task.

## How to use

1. Confirm the module is installed (`Loader::includeModule('sprint.migration')`).
2. Identify the layer (CLI/config vs writing a Version vs helpers/builders).
3. Open the matching `rules/*.md` below.
4. Prefer helpers/`save*` APIs over raw Bitrix API when they cover the entity.
5. For domain ORM/data updates without builders — use D7/`Result` inside `up()`,
   still as a `Version` class.

Official wiki: https://github.com/andreyryabin/sprint.migration/wiki

## Defaults (override via `migrations.*.php` / module options)

| Item | Default |
| --- | --- |
| Migration dir | `{local\|bitrix}/php_interface/migrations` (`local` wins if present) |
| Versions table | `sprint_migration_versions` |
| Class prefix | `Version` + timestamp `YmdHis` (name must contain a valid timestamp) |
| Extend class | `Sprint\Migration\Version` |
| CLI entry | `php {module}/tools/migrate.php` |
| Extra configs | `{local\|bitrix}/php_interface/migrations.<name>.php` → dir `migrations.<name>`, table `sprint_migration_<name>` |

## Choose a rule file

### When to read `rules/cli-config.md`

Read when the task involves:

- Running CLI (`add`, `ls`, `up`, `down`, `redo`, `mark`, `run`, `config`)
- Naming versions / timestamps
- Multiple configs (`--config`, `migrations.*.php`)
- Admin UI vs console auth user

### When to read `rules/writing.md`

Read when the task involves:

- Authoring `Version` (`up` / `down`)
- Idempotent `save*` vs `add*IfNotExists`
- Output (`outSuccess` / `outError`), return `false` on failure
- Dependencies (`checkRequiredVersions`)
- Restartable long migrations
- Exchange files / large data sets
- Hand-written data migrations (ORM / SQL)

### When to read `rules/helpers-builders.md`

Read when the task involves:

- Choosing a Helper (`Iblock()`, `Hlblock()`, …)
- Choosing a Builder (`run IblockBuilder`, …)
- Export-from-admin → commit generated PHP

### When to read `rules/checklist.md`

Read before finishing or reviewing a migration change:

- Safety / anti-patterns
- Apply / verify checklist

## Related skills

| Need | Skill |
| --- | --- |
| Iblock domain model | `bitrix-iblocks` |
| Highloadblock CRUD | `bitrix-highloadblock` |
| Raw SQL / DDL outside helpers | `bitrix-database` |
| Module install SQL (not sprint) | `bitrix-modules` |
| Agents registration | `bitrix-background-jobs` |
| Options / storage choice | `bitrix-storage` |

## Checklist

- [ ] Opened only the rule file(s) needed for this task.
- [ ] Migration files live under the configured `migration_dir` (not in the module).
- [ ] Did not modify sprint.migration module source.
- [ ] Applied `up` on a local/dev copy when verifying the change.