migrate-to-teamcity

Migrate to TeamCity

Quick Start

teamcity migrate                    # detect + convert + write .tc.yml files
teamcity migrate --dry-run --json   # preview as structured JSON
teamcity pipeline validate f.tc.yml # schema check
teamcity project vcs create --url <repo-url> --auth anonymous -p ProjectId  # create VCS root first
teamcity pipeline create name -p ProjectId -f f.tc.yml --vcs-root <VcsRootId>
teamcity run start PipelineId --watch

Run teamcity migrate from the repo root -- detection scans .github/workflows/ and bamboo-specs/ relative to the current directory.

Reading the report

• Needs review -- problems inside the generated YAML: TODO stubs, dropped steps, reusable-workflow placeholders. Fix these in the file before creating the pipeline.
• Manual setup needed -- work the converter cannot do. Sort each item onto one of two sides: YAML edits (secrets, matrix expansion, expression runs-on, container:/services:) go before pipeline create; server-side configuration (connections, if:-derived branch filters, triggers, notifications) comes after. The checklist below orders them.
• Exit code 1 means at least one source failed to convert or one generated file failed schema validation -- files that converted cleanly are still written. Read the per-file ✓/⚠/✗ lines instead of treating exit 1 as total failure.
• --json prints {"sources": [...], "results": [...]} to stdout; each result carries outputFile, yaml, needsReview, manualSetup, and validationError.

Gotchas

• Always type: script for ./gradlew and ./mvnw. TC's type: gradle/type: maven runners use the agent's version, not the project's. This causes real build failures.
• Schema valid does not mean pipeline works. Migration is not done until builds pass.
• Private repos: use a GitHub App connection, not a PAT. Start with teamcity project connection create github-app -p <project> -- its output prints the authorize, App-install, and vcs create follow-up commands. That flow opens a browser; in headless runs pass existing App credentials (--no-manifest --app-id <id> --client-id <id> --private-key-file <pem> --stdin, client secret piped to stdin) or use SSH deploy keys (teamcity project ssh upload with a [email protected]: URL). Public repos: --auth anonymous.
• Secrets, triggers, and branch filters are always manual. The converter flags them but cannot create them -- the checklist below covers each.
• VCS root must exist before pipeline create. teamcity pipeline create takes --vcs-root <id>, not a URL. Create it first with teamcity project vcs create.
• Default branch defaults to main. Pass --branch refs/heads/master to teamcity project vcs create if the repo uses master.
• Unknown actions/tasks become stubs. Read the action's source, write an equivalent shell script. Most actions are thin CLI wrappers. See mappings.