Migrate repository workflows

Inspect workflow changes and create an idempotent migration pull request.

Preview a single workflow

To see how Vectis would rewrite one workflow file without connecting anything, map its labels yourself:

vectis migration preview .github/workflows/test.yml --map ubuntu-24.04-arm=vectis-ubuntu --wait --json

The result contains changed, the proposed YAML as source, and findings for jobs it left alone. Only selected label scalars change; quoting, comments, whitespace and line endings remain intact. Scalars that cannot be safely replaced require manual review. Nothing is written.

The optional jobs summary lists each job with job, changed, reasons for retained runner selections, and static needs dependencies. A matrix job can have changed: true while some selections stay unchanged. Dynamic or aliased dependencies omit needs; an empty array means no dependencies. Workflow-level rejections may omit the summary. Repository analysis includes the same summary in each workflow file.

Migrate a connected repository

Connect a personal or organization repository to a prepared ARM64 environment first. Repository migration currently uses the paired machine’s verified GitHub account and App installation. Public repositories must require GitHub approval for all external contributors before publication. Organization repositories require current repository administrator access for the verified GitHub identity.

Private repositories must disable fork pull request workflows or require approval for those workflows before publication.

vectis repository list --json
vectis migration analyze <binding-id> --wait --json

Analysis reads workflow files from the default branch at a pinned commit. Its operation result contains a previewId, the original and proposed YAML, per-job findings, and whether the environment has successful runner evidence. The cloud retains the preview for 24 hours. The app offers Analyze workflow migration in a connection’s menu under Repositories and shows the result in Overview. MCP accepts the same migration.analyze command.

Review the proposed changes before creating the PR:

vectis migration publish <preview-id> --wait --json

Publication requires an observed successful GitHub job and completed runner cleanup on the same binding and environment revision. Image metadata or configuration changes invalidate earlier evidence and previews. This revision check detects changes to the prepared image; it is not a substitute for source image checksum verification. Complete another test job after replacing an image, then analyze again.

The publisher checks the repository ID, current default branch and pinned base commit. It writes only changed workflow files on vectis/migrate-workflows, preserving the rest of the tree. It opens a regular PR and never merges it. The App needs Contents, Workflows and Pull requests write permissions for publication; analysis uses a separate read-only token.

Repeated requests return the existing PR, including a closed one, instead of recreating rejected changes. An interrupted request can be retried with the same preview after inspecting the branch and PR. A conflicting migration branch is left untouched. A moved default branch requires a fresh analysis.

Analysis maps ubuntu-24.04-arm, windows-11-arm, macos-27, macos-26 and macos-latest to the matching environment. x64 labels such as ubuntu-latest are reported as findings, not rewritten. Static scalar selections and simple static matrices are supported. Dynamic expressions, expanded matrices, reusable workflows, aliased events and privileged event patterns require manual review. x64 labels never imply ARM64 compatibility. Check toolchain versions and action compatibility in the PR even when the runner architecture matches.

Review findings can coexist with safe changes: unsupported jobs keep their original runners. An empty migration cannot be published. To withdraw a proposal, close its PR without merging. After merging, revert the migration commit through normal GitHub review to restore the previous workflow. Automated PR closure and revert creation are not exposed by Vectis yet.