ado-to-github-teams

imageCI imageLicense: MIT

ado-to-github-teams migrates Azure DevOps project teams and their members to a GitHub organization. It resolves Microsoft Entra identities to GitHub Enterprise Managed Users, previews the proposed changes, creates approved teams and memberships, and produces a migration report.

Important

This project is pre-release. Pin the version you evaluate and test against a non-production organization first.

What it does

• Maps Azure DevOps teams to GitHub organization teams.
• Matches Azure DevOps and Microsoft Entra identities to GitHub users.
• Supports flat team migration or an explicit organization-unit/project/repository team hierarchy.
• Exports content-addressed plans for guarded patches and explicit three-way collaboration.
• Refuses GitHub writes unless --apply is provided and the proposed changes are approved.
• Keeps interrupted migrations resumable and records outcomes in a Markdown report.

Try it safely

Install the CLI from npm, then choose a starting command by task:

npm install --global @msft-tkendrick/a2g@preview
a2g --help

That is the complete consumer install path: one install command and one verification command. A missing npm preview tag is a blocked release, not a reason to make consumers clone, bootstrap, build, link, or otherwise prepare the source repository.

Durable workflows run locally by default. Before activating Azure Durable Functions on deployed hosts, run a2g world; the Azure deployment preflight is recorded only after sign-in finds an enabled subscription and you choose it. Tagged prereleases also include an Azure Functions source deployment artifact; no other cloud deployment target is supported.

Or open the bundled interactive sandbox:

a2g sandbox

The sandbox mounts one interactive terminal surface that stays visible until you explicitly exit, so you can browse, configure, and run multiple documented scenarios in a single session. ↑/↓ move the selection, Enter opens the migration configuration for the highlighted scenario, g shows the scenario contracts, r reopens the last run result, and q or Ctrl+C exits. You supply every migration input yourself in that form — the Azure DevOps organization and project to migrate from, the GitHub organization to migrate to, the team name mapping, dry-run or apply, the concurrency, and an optional report path. Nothing is filled in for you and nothing runs until you confirm the "Start migration" row, and the alternate screen is entered once for the session rather than per scenario. The migration, approval, reporting, recovery-guidance, and terminal-dashboard interfaces are the real product surfaces; only Azure DevOps, Microsoft Entra ID, and GitHub service boundaries use predefined responses. Run a2g sandbox --help for the scenario contracts. The sandbox cannot write to providers.

Contributor quick start

New to the repository? This is the shortest path from a fresh clone to a running local change. For the full contributor policy, see CONTRIBUTING.md and AGENTS.md.

Prerequisites

• Node.js 22.18 or later and earlier than Node.js 26 (Node.js 22 is used in CI).
• Git 2.31 or later with worktree support.

Shortest path to a running change

From an existing clone or app-owned worktree, run:

npm run setup
npm run dev -- --sandbox happy-path

npm run setup pins pnpm internally, installs the committed lockfile, installs hooks, and bootstraps ignored local Squad state. It does not require a global pnpm or Corepack installation. The sandbox command mounts an interactive surface with happy-path preselected; it does not run until you open its configuration form with Enter, type in the source, target, and mapping yourself, and confirm the "Start migration" row. It stays visible until you press q, Esc, or Ctrl+C. Only ADO, Entra, and GitHub provider Layers are synthetic, so the interactive configuration, progress, and completion flow is the same product surface without credentials or provider writes.

Development loop

npm run dev runs the TypeScript CLI directly with tsx; no build is required to iterate:

npm run dev -- --list-sandbox-scenarios
npm run dev -- sandbox
npm run dev -- --sandbox happy-path
npm run dev -- migrate --sandbox happy-path

Top-level --sandbox forms always mount the interactive surface; an optional scenario only preselects a list entry and the execution mode its fixtures were recorded in. Use the explicit migrate --sandbox <scenario> form for one-shot automation and focused reproduction.

Validation — focused vs. full

Reach for the smallest command that covers what changed while iterating:

• npm run format:check — Prettier check
• npm run lint — ESLint
• npm run typecheck — TypeScript, no emit
• npm run test:unit — deterministic unit tests

The only baseline pre-merge command is npm run check (secrets, Squad drift, formatting, lint, type checking, build, unit, contract, integration, and package smoke). Run npm run test:bdd only when migration scenarios, Gherkin, or TUI behavior changes. npm test is a convenience command, not an additional required gate.

Debugging & troubleshooting

• Run a single test file: npm exec -- vitest run test/unit/experience/dev-experience.test.ts.
• Suppress the interactive terminal dashboard: set NO_TUI=1 (or pass --no-tui) for stable line-oriented output when diagnosing behavior.
• Check Squad install health: npm run squad:doctor reports missing components or version drift before Squad-related tasks silently misbehave.
• npm run setup fails on a fresh clone: the lockfile has drifted from package.json. Do not hand-edit pnpm-lock.yaml; re-run npm run setup in an isolated worktree, commit the regenerated lockfile, and investigate the dependency change that caused the drift.
• Environment validation fails: run npm run secrets:check to validate .env.schema and scan for plaintext leakage before pushing.

Architecture / repo map

• src/ — active migration CLI, Effect services, adapters, TUI, and the shared experience module.
• test/ — Vitest unit, contract, integration, and Cucumber BDD suites.
• scripts/ — repository automation entry points (persona experiments, Squad bootstrap, BDD runner, TUI evidence).
• skills/ — Agent Skills for ado-to-github-teams, optimize-ux, and optimize-dx.
• apps/cli/ — compatibility package shell exercised only by package smoke. Most contributors change the active root CLI and do not need to work in this directory.
• sandbox/ — synthetic scenario catalog for --sandbox runs.

See Architecture for boundaries, safety model, and topology.

Contribution & agent guidance

• CONTRIBUTING.md — full contributor policy, common commands table, hook enforcement, and validation gates.
• AGENTS.md — non-negotiable engineering policy for human and autonomous agents.
• skills/optimize-dx/SKILL.md — qualitatively critique the full contributor-to-consumer CLI journey against nine pain categories, implement one bounded surface change, execute its command or public artifact contract, and refresh the affected documentation. Rotate the runner across all 15 areas with npm run optimize:dx (defaults to 15 iterations) or, for a narrower pass, npm run optimize:dx -- --iterations 3 (any integer from 1 through 20).

Migrate teams

1. Start the worker and authenticate.

2. Generate a dry-run report:

   a2g migrate --ado-org https://dev.azure.com/contoso --ado-project Platform --github-org contoso --foreground
   

   The equivalent task-shaped scope aliases are --source-org, --source-project, and --target-org. Use migrate --help to see scope, execution, recovery, presentation, topology, worker, and sandbox flags in separate groups.

3. Review every proposed team, membership, skipped identity, and warning in the report.

4. Run the same command with --apply, then approve the exact changes shown by the CLI:

   a2g migrate --ado-org https://dev.azure.com/contoso --ado-project Platform --github-org contoso --apply --foreground
   

Dry run is always the default. Reports and migration state can contain organization and identity data; keep them private.

Interactive terminal dashboard

Interactive sandbox runs and migrate --foreground use a responsive full-screen terminal dashboard when stdout is a TTY. It presents the safety mode, scope, run ID, current and queued stages, elapsed time, live activity, and next event in one stable frame. The renderer caps animation at 12 frames per second, redraws atomically in the terminal's alternate screen, and recomposes after resize without leaving partial or stale lines.

Use --no-tui or NO_TUI=1 for stable line-oriented output. REDUCE_MOTION=1 keeps the dashboard but replaces animation with a static progress marker. Non-TTY output, CI, TERM=dumb, and SCREEN_READER=1 automatically use the line-oriented path so automation and assistive technology do not receive cursor-control sequences.

The executable TUI scenarios, advanced terminal and designer personas, and latest committed production-renderer screenshots and GIF are documented in TUI experience. TUI pull requests must refresh that evidence with npm run tui:evidence and embed it in the pull request body.

GitHub Copilot Squad

The repository's eleven research personas — ten CLI operators and one repository contributor — are also an SDK-first Squad for GitHub Copilot. squad.config.ts is the typed source of truth and imports the same PERSONA_DEFINITIONS used by the experiment harness. Scribe, Ralph, Rai, and Fact Checker add redacted memory, read-first triage, safety review, and independent verification.

Install dependencies, create ignored local Squad state, verify generated assets, and start the pinned SDK runtime:

npm run setup
npm run squad:check
npm run squad:copilot

Address a persona directly, or describe the task for deterministic routing. The runtime enforces per-agent tool allowlists, canonical write paths, redacted and approval-gated permission requests, clarification limits, and reviewer lockouts. These development controls supplement, but never replace, the migration CLI's Effect services, dry-run, approval, checkpoint, idempotency, and retry invariants.

Squad 0.11.0 is alpha software and is pinned exactly. Mutable decisions, histories, casting state, templates, sessions, and logs are ignored because they may contain operational context. Only static configuration and generated definitions are committed. Use npm run squad:doctor for installation diagnostics, npm run squad:status for resolution details, and npm run squad:nap to preview context compaction.

Documentation

Open a GitHub issue for reproducible bugs or feature requests. Do not include credentials, tenant identifiers, personal data, reports, or migration state.

License

Licensed under the MIT License.