Organise your TeamCity server with projects and subprojects, create projects from VCS URLs, configure shared parameters and connections, and manage the project lifecycle
Every TeamCity server has a single Root Project at the top. All other projects descend from it. Projects can be nested to any depth to match your organisation's structure.
Settings defined at a higher level are inherited by all descendants:
The fastest way to create a project is from a repository URL — TeamCity auto-detects the build tool and creates starter build configurations.
https://github.com/yourorg/yourrepo.gitpom.xml, build.gradle, etc.), and suggests build configurations.TeamCity's auto-detection works well for Maven, Gradle, MSBuild, Ant, and Rake projects. It scans the root and one level deep for build files. For complex multi-module projects or custom build scripts, it's faster to create the project manually and add build steps by hand.
Every project has a settings page (Administration → <Project> → Edit Project Settings) with these tabs:
| Tab | What it configures |
|---|---|
| General Settings | Project name, description, project ID (used in REST API and DSL). The project ID cannot be changed after creation without breaking references. |
| VCS Roots | Repository connections shared across all build configs in this project. See Phase 5. |
| Parameters | Project-level configuration parameters, system properties, and environment variables inherited by all child configs. |
| Connections | OAuth/credentials for external services: GitHub, Bitbucket, Docker Registry, cloud providers. Referenced in VCS Roots and build features. |
| Build Configurations | List and manage all build configs inside this project. |
| Subprojects | List child projects. Create or move subprojects here. |
| Clean-up | How long to keep builds, artifacts, and statistics. |
| Versioned Settings | Sync project config to/from VCS (Kotlin DSL). See Phase 11. |
The project ID is auto-generated from the name (e.g., project name "Backend Services" → ID BackendServices). It is used in:
/app/rest/projects/id:BackendServicesproject("BackendServices") { ... }dep.BackendServices_UserService_Build.paramOnce a project is created, its ID appears in REST API URLs, Kotlin DSL, and parameter references across many build configs. Renaming the project changes the display name but NOT the ID. To change the ID you must edit the XML config directly — which can break references. Plan your naming conventions before creating projects.
Any value used by multiple build configs in a project should be a project parameter rather than duplicated in each config. Common examples:
env.NEXUS_URL — artifact repository URL used in all Maven buildsenv.DOCKER_REGISTRY — registry URL used in Docker push stepssystem.maven.settings.file — path to shared Maven settings.xmlenv.DEPLOY_TARGET — staging server hostnameGo to Administration → <Project> → Parameters and click Add new parameter. Set the kind (Configuration parameter / System property / Environment variable), name, and value.
A GitHub connection lets TeamCity authenticate with GitHub using OAuth rather than storing a personal access token in each VCS Root. To set up:
| Scenario | Use subproject? | Reason |
|---|---|---|
| Multiple microservices owned by same team | Yes | One parent project per team; one subproject per service. Shared team-level params live on parent. |
| Separate prod vs staging build configs | No | Use one project with multiple build configs (Build, Deploy-Staging, Deploy-Prod). |
| Different permission boundaries (team A vs team B) | Yes | Per-project permissions. Make team A admin of their subproject without affecting team B. |
| Monorepo with multiple apps | Yes (optional) | One subproject per app; shared VCS root on parent. Clean separation in UI. |
To create a subproject: go to Administration → <Parent Project> → Subprojects → Create subproject.
In the TeamCity REST API (covered in depth in Phase 14), projects are addressed by their ID or internal ID:
# List all projects
GET /app/rest/projects
# Get a specific project
GET /app/rest/projects/id:BackendServices
# Get by name
GET /app/rest/projects/name:Backend%20Services
# Get internal ID (needed for some operations)
GET /app/rest/projects/id:BackendServices
# Returns: {"id":"BackendServices","internalId":"project12", ...}The project ID is the human-readable string you set at creation. The internal ID is a server-assigned projectN string. Use the project ID in all your scripts — it's stable and readable.
Archiving a project stops all builds and triggers, hides it from the default project list, but retains all history, artifacts, and configuration. Good for repos that are deprecated but may need historical reference.
Go to Administration → <Project> → Actions → Archive project. To restore, find it in the archived projects list and click Dearchive.
Deletes the project, all subprojects, all build configurations, all build history, and all artifacts permanently. Cannot be undone (except from a server backup).
If other build configurations have artifact dependencies on the project you're deleting, those dependencies will break silently. TeamCity does not warn you about downstream artifact consumers. Audit artifact dependencies before deleting any project.
Go to Administration → <Build Config> → Actions → Copy build configuration. Optionally copy to a different project. Useful for creating a new service from an existing one — copy the template config and update the VCS Root and parameters.
Go to Administration → <Build Config> → Actions → Move to project. Moving updates the internal project ID prefix on the build config ID. All build history moves with it. Snapshot and artifact dependencies remain intact as long as the target project has access to the same VCS roots.
If you find yourself copying build configurations frequently, switch to build configuration templates (Phase 11). Templates propagate changes to all configs at once — a copy is a snapshot that immediately diverges.