VCS triggers with quiet periods and branch filters, Schedule triggers with cron expressions, Finish Build and Retry triggers, trigger rules for fine-grained control, and manual builds
| Trigger Type | Fires when | Common use |
|---|---|---|
| VCS Trigger | Changes detected in VCS root (commit, PR) | Build on every push — the most common trigger |
| Schedule Trigger | Cron-defined time schedule | Nightly full builds, weekly integration tests |
| Finish Build Trigger | Another build configuration finishes | Chain: "start Deploy when Build passes" |
| Retry Build Trigger | A build fails | Auto-retry flaky test builds once or twice |
| Maven Artifact | New snapshot artifact published to Maven repo | Trigger downstream when library snapshot changes |
| NuGet Dependency | New NuGet package version available | .NET: trigger when dependency package updates |
Add triggers via Build Configuration → Triggers → Add new trigger. Multiple triggers can be active simultaneously.
Fires when TeamCity detects new commits in the VCS Root. This is the primary CI trigger — every push starts a build.
The quiet period prevents TeamCity from starting a build immediately on the first commit. It waits until no new commits arrive for N seconds, then starts one build covering all recent commits. This avoids a flood of builds when a developer pushes multiple commits in quick succession.
Quiet period: 60 seconds
# TeamCity waits 60s after the last commit before queuing the build
# If another commit arrives within 60s, the timer resets
# Result: one build per "burst" of commitsUse a 30–60 second quiet period. Zero quiet period means every individual commit triggers a build — fine for small teams where developers push single commits. For active repos with rebase workflows or GitHub merge queues, 60 seconds reduces build churn significantly.
With Trigger a build on each check-in in all branches enabled, every branch that matches the VCS Root's branch specification gets its own build when new commits arrive. Without this, only the default branch triggers builds.
| Setting | Behaviour |
|---|---|
| Per-branch triggering OFF | Only commits to the default branch trigger builds. Feature branch commits are ignored by this trigger. |
| Per-branch triggering ON | Commits to any branch matching the VCS Root branch spec trigger a build. Each branch gets its own build in the Branches list. |
Branch filters restrict the VCS trigger to specific branches — even if the VCS Root monitors more branches. This lets you have different trigger behaviour on different branches.
# Branch filter syntax (same +/- pattern as VCS Root branch spec)
# Applied AFTER the VCS Root branch spec
# Only trigger on main and develop branches
+:refs/heads/main
+:refs/heads/develop
# Trigger on all branches except experimental
+:refs/heads/*
-:refs/heads/experimental
# Only trigger on branches matching a pattern
+:refs/heads/release/*
# Trigger on all branches and PRs
+:refs/heads/*
+:refs/pull/*/headThe VCS Root branch specification determines which branches TeamCity monitors. The VCS Trigger branch filter determines which of those branches trigger a build. A branch can be in the spec (visible in build history) but excluded from the trigger (won't start builds automatically). Both must be configured intentionally.
Trigger rules provide fine-grained control over which commits trigger a build, based on file paths modified or commit message content.
# +/- patterns on file paths (relative to VCS root checkout)
# Lines starting with + include, lines starting with - exclude
# Only trigger if src/ or tests/ changed (ignore docs/README changes)
+:src/**
+:tests/**
-:docs/**
-:README.md
# Monorepo: only trigger if backend/ changed
+:backend/**
-:**# Trigger only on commits with [build] in message
+:comment=\[build\].*
# Skip builds for commits with [skip ci] or [ci skip]
-:comment=.*\[skip ci\].*
-:comment=.*\[ci skip\].*Add a trigger rule -:comment=.*\[skip ci\].* to support the common convention of skipping CI on documentation-only commits. Developers add [skip ci] to their commit message, and TeamCity ignores it. This is much cleaner than branch-based exclusions for occasional skips.
Runs a build on a time-based schedule, regardless of whether there are new commits. Uses a Quartz-style cron expression.
# Format: seconds minutes hours day-of-month month day-of-week [year]
# Field values: * = any, ? = don't care, / = increment, L = last, W = weekday
# Examples:
0 0 2 * * ? # Every day at 02:00:00
0 0 2 ? * MON-FRI # Weekdays at 02:00:00
0 30 9 ? * MON # Every Monday at 09:30
0 0 */4 * * ? # Every 4 hours
0 0 0 1 * ? # First day of every month at midnight| Cron Expression | Fires |
|---|---|
| 0 0 2 * * ? | Every day at 2:00 AM |
| 0 0 2 ? * MON-FRI | Weekdays at 2:00 AM (Mon–Fri) |
| 0 0 0 ? * SUN | Every Sunday midnight |
| 0 0/30 * * * ? | Every 30 minutes |
| 0 0 8-17 ? * MON-FRI | Every hour from 8 AM to 5 PM on weekdays |
| Option | Description |
|---|---|
| Trigger only if there are pending changes | Skip the scheduled build if the last build already covered all commits. Saves resources when main is quiet overnight. |
| Trigger on all branches matching spec | Fire scheduled builds on all branches, not just the default branch. |
| With specific parameters | Inject custom parameters into scheduled builds (e.g., -Pfull-test-suite=true for nightly full runs). |
| Timezone | Interpret cron expression in a specific timezone (default: server timezone). |
Fires when a specified build configuration finishes. Used to chain builds: start the deploy when the test build passes. Unlike snapshot dependencies (Phase 9), the Finish Build trigger does not enforce the same source snapshot.
Use a Finish Build Trigger when you want one build to start another after it finishes, but the builds can use different source revisions (e.g., a nightly deploy that takes whatever the last successful build produced). Use a Snapshot Dependency (Phase 9) when you need to guarantee both builds use exactly the same commit — critical for deterministic release pipelines.
Automatically re-queues a failed build once or multiple times. Useful for builds that fail due to intermittent infrastructure issues (flaky network, resource contention) rather than code problems.
| Setting | Description |
|---|---|
| Retry attempts | How many times to retry (1–5). Each retry is a separate build. |
| Delay (seconds) | Wait time before the retry build is queued. Default 0. |
| Move build to the queue top | Put the retry build at the front of the queue so it runs before new pending builds. |
Retry triggers can mask real test failures if they cause a broken build to "pass" on the second attempt due to flaky tests. Keep retry counts low (1–2) and monitor the builds that trigger retries. If a build retries more than once a week, fix the root cause rather than masking it with retries.
A Personal Build is a build triggered by a developer to test their local uncommitted changes against the CI infrastructure, without pushing to VCS. Requires the TeamCity IDE plugin (IntelliJ, Eclipse, VS).
Workflow:
Any build can be run manually from the TeamCity UI with custom parameters — useful for deployment builds where you want to specify a version or environment.
# In build config Parameters, set:
Name: deploy.environment
Kind: Configuration parameter
Value: (leave blank — empty = prompt on manual run)
Display: prompt
Label: Deployment Environment
Description: Choose: staging or productionWhen a developer clicks Run, they see a field for "Deployment Environment" and must fill it in before the build starts.