VCS Roots & GitHub Integration

A VCS Root defines the connection from TeamCity to a version control repository. One VCS Root per repository — it is shared across all build configurations in the same project or subprojects.

A VCS Root captures:

• Repository URL
• Authentication credentials
• Branch specification (which branches to watch)
• Checkout rules (which paths in the repo to check out)
• Fetch interval (how often to poll for changes)

1. Go to Administration → <Project> → VCS Roots → Create VCS root.
2. Select Git as the VCS type.
3. Fill in the fields:

Click Test connection before saving. TeamCity will try to fetch the repository. A green result confirms credentials work. A red result shows the exact error (auth failure, URL not found, etc.).

Personal Access Token setup

1. In GitHub: Settings → Developer settings → Personal access tokens → Generate new token.
2. Required scopes for TeamCity: repo (full control of private repositories) OR for public repos: public_repo. For Commit Status Publisher: repo:status is sufficient if you only need status updates, but repo is needed to read PR info.
3. Copy the token (shown only once).
4. In TeamCity VCS Root: Authentication method = Password. Username = your GitHub username. Password = the token.

SSH key pair setup

# Generate an ED25519 key pair (no passphrase for CI)
ssh-keygen -t ed25519 -C "teamcity@yourcompany.com" -f ~/.ssh/teamcity_rsa -N ""

# Output: teamcity_rsa (private) + teamcity_rsa.pub (public)

1. Add teamcity_rsa.pub content to GitHub: Repo → Settings → Deploy keys → Add deploy key. Enable "Allow write access" only if TeamCity needs to push (e.g., tagging). Read-only for CI is safer.
2. In TeamCity VCS Root: Fetch URL = git@github.com:yourorg/yourrepo.git. Authentication = Uploaded Key. Upload the private key (teamcity_rsa).
3. Or use Default Private Key if you've placed the key in the TeamCity server's ~/.ssh/ directory.

The branch specification tells TeamCity which branches (and PRs) to monitor for changes. It uses a +/- include/exclude pattern syntax matching against full Git ref names.

Pattern syntax

+|-:ref_pattern [=> display_name]

• +: — include this ref pattern (watch for changes, build on match)
• -: — exclude this ref pattern (ignore)
• * — wildcard matching any single path segment
• ** — wildcard matching any number of path segments
• => display_name — optional short name shown in TeamCity UI

Common patterns

Typical production branch spec

+:refs/heads/*
+:refs/pull/*/head

This watches all branches AND all pull requests. It's the most common setup for a team that wants branch builds and PR builds from one build configuration.

Checkout rules filter which paths in the repository are checked out on the agent. Useful for monorepos where different services live in subdirectories and you only want to check out one service at a time.

# Syntax: +|-:source_path [=> target_path]

# Only check out the backend/ directory (maps it to root)
+:backend => .

# Only check out specific service
+:services/user-service => .
+:shared/common-lib => common-lib

# Exclude generated files (rarely needed — use .gitignore instead)
-:target
-:node_modules

The Commit Status Publisher build feature posts build results back to GitHub as commit statuses. This shows a ✓ or ✗ check on each commit and on pull requests — the most visible integration point between TeamCity and GitHub.

Setup

1. In the build configuration, go to Build Features → Add build feature → Commit status publisher.
2. Publisher: select GitHub.
3. GitHub URL: https://api.github.com (for GitHub.com) or https://your-github-enterprise/api/v3.
4. Authentication: select your GitHub connection or enter a Personal Access Token directly.
5. Token scopes needed: repo:status (minimum) or repo (full).
6. Save.

Multiple statuses (build chains)

If you have a build chain (Build → Test → Deploy), add the Commit Status Publisher to each build configuration. GitHub will show separate status checks for each stage, giving developers granular visibility into which stage failed.

The Pull Request build feature (introduced in TeamCity 2017.2) automatically detects GitHub pull requests and enriches builds with PR metadata. Combined with +:refs/pull/*/head in the branch spec, it enables full PR CI workflow.

Setup

1. Add build feature: Pull requests.
2. VCS hosting type: GitHub.
3. Authentication: GitHub connection or PAT.
4. Filter by target branch (optional): e.g., only build PRs targeting main.
5. Filter by author (optional): only build PRs from org members.

Available PR parameters

When a PR build runs, TeamCity exposes these parameters:

# Use PR parameters in build steps
echo "Building PR #%teamcity.pullRequest.number%: %teamcity.pullRequest.title%"
echo "From %teamcity.pullRequest.source.branch% into %teamcity.pullRequest.target.branch%"

By default, TeamCity polls GitHub every 60 seconds for changes. Webhooks replace polling with a push notification — GitHub sends a POST to TeamCity the instant a push happens, reducing the trigger latency from up to 60 seconds to under 5 seconds.

Setting up the webhook

1. In GitHub: go to Repo → Settings → Webhooks → Add webhook.
2. Payload URL: http://YOUR_TC_SERVER:8111/app/rest/vcs-root-instances/checkingForChanges
   Or for HTTPS: https://ci.yourcompany.com/app/rest/vcs-root-instances/checkingForChanges
3. Content type: application/json
4. Secret: leave blank (or set a shared secret for validation)
5. Which events: select Just the push event (and optionally Pull requests).
6. Click Add webhook.

Verification

After adding the webhook, push a commit to GitHub. TeamCity should queue a build within seconds. In GitHub, the webhook shows a green ✓ delivery in the Recent Deliveries section.

Deploy keys are SSH keys attached to a specific repository (not a user account). They are the most secure authentication method for CI systems because:

• Access is limited to one repository
• Read-only by default (write access is optional)
• Revocable without affecting user accounts
• No user credentials in TeamCity's config

# 1. Generate a dedicated key pair for this repository
ssh-keygen -t ed25519 -C "teamcity-deploy-key-myrepo" \
  -f ~/.ssh/myrepo_deploy_key -N ""

# 2. Add public key to GitHub (repo-level)
cat ~/.ssh/myrepo_deploy_key.pub
# Copy output → GitHub Repo → Settings → Deploy keys → Add deploy key
# Title: TeamCity CI
# Key: (paste public key)
# Allow write access: unchecked (unless TC needs to push tags)

# 3. In TeamCity:
# Administration → <Project> → SSH keys → Upload SSH key
# Upload: myrepo_deploy_key (private key, no .pub)

# 4. In VCS Root:
# Authentication method: Uploaded Key
# Uploaded key: myrepo_deploy_key
# Passphrase: (leave blank — CI keys should not have passphrases)

TeamCity can automatically create a Git tag (label) on every successful build. This gives you a permanent reference to the exact commit that produced a passing build.

1. In the build configuration, go to Version Control Settings → Labeling > Label successful builds.
2. Set the label pattern: build-%system.build.number% or release-%build.number%.
3. Branch filter (optional): only label builds on main.

VCS fetch log

To see detailed fetch output: in the build log, look for the Checkout step. Or go to Administration → Diagnostics → VCS Status to see all VCS root fetch statuses and errors.