# Config versioning and migration framework (https://jackin.tailrocks.com/roadmap/config-versioning-migration/)



**Status**: Partially implemented — Phase 1 (config file versioning) and Phase 2 (role manifest versioning) shipped; Phase 3 (`--pr` auto-migration) and Phase 4 (Renovate-style migration GitHub Action) remain open (Configuration ergonomics)

## Shipped facts [#shipped-facts]

`config.toml` and per-workspace files under `~/.config/jackin/workspaces/<name>.toml` carry a top-level `version` field (`CURRENT_CONFIG_VERSION` / `CURRENT_WORKSPACE_VERSION`, currently `v1alpha8` in <RepoFile path="crates/jackin-config/src/versions.rs">crates/jackin-config/src/versions.rs</RepoFile>). `AppConfig::load_or_init` (<RepoFile path="crates/jackin-config/src/app_config/persist.rs">crates/jackin-config/src/app\_config/persist.rs</RepoFile>) reads the raw TOML, extracts `version` (missing = legacy), and walks the migration registry in <RepoFile path="crates/jackin-config/src/migrations.rs">crates/jackin-config/src/migrations.rs</RepoFile> — a compile-time slice of `toml_edit`-based transform functions, one per version step — before deserializing into typed structs. Migrated files are rewritten atomically (`atomic_write`) and one line is printed to stderr. A file stamped newer than the binary's current version errors rather than silently misbehaving. This is fully automatic; operators do nothing.

`jackin.role.toml` carries the same `version` field (`CURRENT_MANIFEST_VERSION`, currently `v1alpha6` in <RepoFile path="crates/jackin-core/src/constants.rs">crates/jackin-core/src/constants.rs</RepoFile>). Because role manifests live in repos jackin❯ does not own, migration is explicit rather than automatic: `jackin role migrate <role-repo-path>` (a subcommand of the main `jackin` binary, <RepoFile path="crates/jackin/src/cli/role.rs">crates/jackin/src/cli/role.rs</RepoFile>) and the standalone `jackin-role migrate <role-repo-path>` binary (<RepoFile path="crates/jackin/src/bin/role.rs">crates/jackin/src/bin/role.rs</RepoFile>, same `RoleCommand` enum) both apply the migration chain and write the result back to a local clone for the author to review, commit, and push. An older-stamped manifest that uses a feature newer than its declared version is rejected with a migrate hint; a manifest newer than the binary understands is rejected with an "upgrade jackin" error.

Full version history, per-file current versions, and the field-level migration tables live in [Schema Versions](/reference/runtime/schema-versions/) — that page is the canonical, continuously-updated record and should not be duplicated here. [Configuration File](/reference/runtime/configuration/) covers the `version` field from the config-schema side.

## Remaining work [#remaining-work]

1. **Phase 3 — `--pr` auto-migration.** No `--pr` flag exists on `jackin role migrate` today. Add an opt-in path that, after writing the migrated manifest, opens a branch + PR in the role repo via `gh` (gated on `gh` auth and GitHub-remote detection), so the maintainer and operators can send migration PRs to role repos without a local checkout.
2. **Phase 4 — Renovate-style migration GitHub Action.** Role repos already use the `jackin-project/jackin-role-action` reusable workflow for validation; extending it with a scheduled `migrate` mode (open PR when a repo's manifest is behind, close/rebase as needed) would close the gap for role authors who never run `jackin role migrate` by hand. Deployment shape (hosted app vs. self-hosted workflow + PAT), target-repo discovery, and rebase/conflict handling are still open design questions — see the linked research page for the design proposal this would build on.

## Related work [#related-work]

* Research: [Renovate-style role-manifest migration automation](/reference/research/runtime/config-versioning-migration-design/) — Phase 3/4 design proposal, prior-art comparison to Renovate, and open design questions for the CI automation.
* [Schema Versions](/reference/runtime/schema-versions/) — canonical version history and migration tables.
* [Configuration File](/reference/runtime/configuration/) — `version` field and config schema reference.
* [Agent version pinning](/roadmap/reproducibility-pinning/) — pinning roles to tagged versions implies a version relationship between the jackin binary and the role manifest schema.