doc/ci/migration/teamcity.md
{{< details >}}
{{< /details >}}
If you're migrating from TeamCity to GitLab CI/CD, you can create CI/CD pipelines that replicate and enhance your TeamCity workflows.
GitLab CI/CD and TeamCity are CI/CD tools with some similarities. Both GitLab and TeamCity:
Additionally, there are some important differences between the two:
TeamCity can be configured from the UI
or in the Teamcity Configuration file in the Kotlin DSL format.
A TeamCity build configuration is a set of instructions that defines how a software project should be built,
tested, and deployed. The configuration includes parameters and settings necessary for automating
the CI/CD process in TeamCity.
In GitLab, the equivalent of a TeamCity build configuration is the .gitlab-ci.yml file.
This file defines the CI/CD pipeline for a project, specifying the stages, jobs,
and commands needed to build, test, and deploy the project.
Many TeamCity features and concepts have equivalents in GitLab that offer the same functionality.
TeamCity uses build configurations, which consist of multiple build steps where you define commands or scripts to execute tasks such as compiling code, running tests, and packaging artifacts.
The following is an example of a TeamCity project configuration in a Kotlin DSL format that builds a Docker file and runs unit tests:
package _Self.buildTypes
import jetbrains.buildServer.configs.kotlin.*
import jetbrains.buildServer.configs.kotlin.buildFeatures.perfmon
import jetbrains.buildServer.configs.kotlin.buildSteps.dockerCommand
import jetbrains.buildServer.configs.kotlin.buildSteps.nodeJS
import jetbrains.buildServer.configs.kotlin.triggers.vcs
object BuildTest : BuildType({
name = "Build & Test"
vcs {
root(HttpsGitlabComRutshahCicdDemoGitRefsHeadsMain)
}
steps {
dockerCommand {
id = "DockerCommand"
commandType = build {
source = file {
path = "Dockerfile"
}
}
}
nodeJS {
id = "nodejs_runner"
workingDir = "app"
shellScript = """
npm install jest-teamcity --no-save
npm run test -- --reporters=jest-teamcity
""".trimIndent()
}
}
triggers {
vcs {
}
}
features {
perfmon {
}
}
})
In GitLab CI/CD, you define jobs with the tasks to execute as part of the pipeline. Each job can have one or more build steps defined in it.
The equivalent GitLab CI/CD .gitlab-ci.yml file for the previous example would be:
workflow:
rules:
- if: $CI_COMMIT_BRANCH != "main" || $CI_PIPELINE_SOURCE != "merge_request_event"
when: never
- when: always
stages:
- build
- test
build-job:
image: docker:20.10.16
stage: build
services:
- docker:20.10.16-dind
script:
- docker build -t cicd-demo:0.1 .
run_unit_tests:
image: node:17-alpine3.14
stage: test
before_script:
- cd app
- npm install
script:
- npm test
artifacts:
when: always
reports:
junit: app/junit.xml
TeamCity Triggers define conditions that initiate a build, including VCS changes, scheduled triggers, or builds triggered by other builds.
In GitLab CI/CD, pipelines can be triggered automatically for various events, like changes to branches or merge requests and new tags. Pipelines can also be triggered manually, using an API, or with scheduled pipelines. For more information, see CI/CD pipelines.
In TeamCity, you define build parameters and environment variables in the build configuration settings.
In GitLab, use the variables keyword to define CI/CD variables.
Use variables to reuse configuration data, have more dynamic configuration, or store important values.
Variables can be defined either globally or per job.
For example, a GitLab CI/CD .gitlab-ci.yml file that uses variables:
default:
image: alpine:latest
stages:
- greet
variables:
NAME: "Fern"
english:
stage: greet
variables:
GREETING: "Hello"
script:
- echo "$GREETING $NAME"
spanish:
stage: greet
variables:
GREETING: "Hola"
script:
- echo "$GREETING $NAME"
Build configurations in TeamCity allow you to define artifacts generated during the build process.
In GitLab, any job can use the artifacts keyword to define a set of artifacts to
be stored when a job completes. Artifacts are files that can be used in later jobs,
for testing or deployment.
For example, a GitLab CI/CD .gitlab-ci.yml file that uses artifacts:
stage:
- generate
- use
generate_cat:
stage: generate
script:
- touch cat.txt
- echo "meow" > cat.txt
artifacts:
paths:
- cat.txt
expire_in: 1 week
use_cat:
stage: use
script:
- cat cat.txt
The equivalent of TeamCity agents in GitLab are Runners.
In GitLab CI/CD, runners are the services that execute jobs. If you are using GitLab.com, you can use the instance runner fleet to run jobs without provisioning your own self-managed runners.
Some key details about runners:
tags keyword
for finer control, and associate runners with specific jobs. For example, you can use a tag for jobs that
require dedicated, more powerful, or specific hardware.Some functionality in TeamCity that is enabled through build features & plugins is supported in GitLab CI/CD natively with CI/CD keywords and features.
| TeamCity plugin | GitLab feature |
|---|---|
| Code coverage | Code coverage and Test coverage visualization |
| Unit Test Report | JUnit test report artifacts and Unit test reports |
| Notifications | Notification emails and Slack |
The following list of recommended steps was created after observing organizations that were able to quickly complete a migration to GitLab CI/CD.
Before starting a migration you should create a migration plan to make preparations for the migration.
For a migration from TeamCity, ask yourself the following questions in preparation:
Before doing any migration work, you should first:
.gitlab-ci.yml file in each project.If you have questions that are not answered here, the GitLab community forum can be a great resource.