Warning
The product is in closed beta and not open to the public.
VisionByte VCS Plugin User Guide¶
Use the VisionByte VCS Plugin to check out source code, review changes, and build selected branches with TeamCity. Checkout can run on the server or directly on build agents.
This guide covers version 0.1.0.0. See the Release Notes for the release summary.
Requirements¶
TeamCity: 2026.2.1.
Java: A 64-bit Java 21 runtime on the server and agents.
Platforms: Windows x64, Linux x86_64 with glibc or musl, or macOS on Apple Silicon (arm64). Use an ARM64 Java runtime on Apple Silicon.
Repository access: The server must reach the repository over HTTP or HTTPS. Agent checkout also requires direct access from the agent. Private repositories require an account with read and clone permissions.
A separate VisionByte command-line installation is not required.
Installation¶
Obtain the
visionbyte-teamcity.zippackage.Wait for active builds to finish, then upload the ZIP through Administration → Plugins. Alternatively, place it in
<TeamCity Data Directory>/plugins.Restart the TeamCity server.
Wait for agents to receive the update and reconnect. Restart agent JVMs after upgrading the plugin, and confirm that they are online.
In project settings, confirm that VisionByte is available when creating a VCS root.
Back up the installed package and TeamCity configuration before upgrading.
Credentials¶
Enter Username and Password in the VCS root. Leave both empty for anonymous access. A password without a username is rejected. Do not embed credentials in the repository URL.
The password is stored securely by TeamCity. When a username is configured, that account must authenticate and have read and clone permissions, even when the repository also permits anonymous access.
Quick Start¶
Create or open a TeamCity project and enter its settings.
Open VCS Roots → Create VCS root and select VisionByte under Type of VCS.
Enter a root name and ID, a URL such as
https://code.example.com/project, the default branch, and any required credentials. The initial branch istrunk; replace it if your repository uses another default branch.Select Test connection, then save the root.
Attach the root under the build configuration’s Version Control → Attach VCS root settings.
Choose the checkout mode, add build steps, and run a manual build.
Review Build Log and Changes, and confirm that the expected source version was checked out.
Test connection checks repository access and clone permissions. The first build also checks that the configured branch is available and that the selected server or agent can complete the checkout.
Repository Configuration¶
Field |
Default |
Description |
|---|---|---|
Repository URL |
Required |
HTTP/HTTPS repository address without embedded credentials or a URL fragment. |
Default branch |
|
The repository’s main branch. It is always monitored. |
Branch specification |
Empty |
Rules selecting additional branches. Empty monitors only the default. |
Username |
Empty |
Repository account. Leave empty for anonymous access. |
Password |
Empty |
Password for the configured account. |
Minimum polling interval |
Server setting |
TeamCity’s schedule for checking repository changes. |
Use the actual VisionByte repository URL. Do not add a Git or Subversion prefix.
Branches and Automatic Builds¶
Enter real VisionByte branch names without Git’s refs/heads/ prefix.
To build additional branches, set Branch specification, for example:
+:(feature/*)
+:(release/*)
-:feature/wip-*
Add a VCS Trigger under the build configuration’s Triggers settings and allow the intended logical branches in its branch filter. A branch specification alone does not create a trigger.
Run an initial manual build, then check that a later source change appears under Changes and starts the expected build. Each build uses the version selected by TeamCity, even if the branch changes while the build is queued.
Checkout Modes¶
Choose the mode under the build configuration’s Version Control settings.
TeamCity setting |
When to use it |
|---|---|
Always check out files on agent |
The agent downloads source directly. Use this when the agent has repository access and runs on a supported platform. |
Always check out files on server |
The server retrieves source and sends the selected files to the agent. Use this when repository access should be handled by the server. |
Whole-repository agent checkout creates a VisionByte workspace that build scripts can use with workspace commands. Directory selection provides only the selected source files. VisionByte workspace commands require whole-repository agent checkout. Selecting fewer files does not necessarily reduce the repository download size.
File content, encodings, and line endings are preserved. Executable permissions are applied on platforms that support them.
Checkout Rules¶
Use directory rules to include, exclude, or map source paths, for example:
+:src/module-a=>sources/module-a
+:lib/common=>sources/common
-:src/module-a/generated
These rules work with both server and agent checkout. Agent rules do not support wildcards, single-file remapping, absolute targets, or destinations outside the checkout directory.
For multiple roots, use separate destination folders, such as repo-a and
repo-b. Keep each root’s mappings under its own folder, and avoid overlapping
or nested destinations belonging to different roots.
Use Enforce clean checkout after changing directory-selection rules, switching checkout modes, or changing the managed destination. Preserve any required build outputs before cleaning.
Build Revisions and Changes¶
Open Changes to review commit authors, descriptions, and affected files. TeamCity can retrieve the before and after content of a change. File-content views are limited to 64 MiB per file.
Build Log reports the complete UUID checked out on the agent. Build scripts can use TeamCity’s root-specific version parameter, replacing the example with the attached root’s external ID:
%build.vcs.number.MyProject_VisionByte%
Repository Browsing¶
Repository file and directory pickers display the configured default branch. Branch specification does not change the branch used by the picker. Symbolic links may appear in the picker even when the selected checkout mode cannot create them.
If directory expansion is slow, check the connection to the repository server and its response time.
Workspace Cleanup¶
Use an empty directory for the first checkout. Keep each root’s destination separate from other repositories and existing VisionByte workspaces.
Ordinary agent updates restore changes to tracked files and retain unrelated build outputs. Use TeamCity’s Enforce clean checkout when a workspace must be rebuilt.
Warning
Clean checkout removes files from the managed checkout directory, including untracked files and build outputs. Save required files before requesting it.
If TeamCity reports a directory conflict, review all attached roots and their mappings. Do not remove management files to force the plugin to reuse a folder containing unrelated data.
Cache Maintenance¶
To refresh the server’s repository cache, open
Administration → Diagnostics → Caches and reset visionbyte.
The next repository operation downloads the required data again.
Reset does not remove VCS root settings, build history, or agent workspaces. For a multi-server installation, reset the affected server’s cache. If the cache is busy, wait for the current repository operations to finish and retry.
Troubleshooting¶
VisionByte is missing: Check the plugin installation and restart the server. Look under VCS Roots → Create VCS root in project settings.
Connection succeeds but checkout fails: Check the branch name, repository permissions, selected checkout mode, and repository access from the server or agent performing the checkout.
Authentication fails: Verify credentials and repository permissions. For HTTPS errors, check the certificate and the node’s TLS configuration.
Configured branch is missing: Use the actual branch name, without
refs/heads/. Confirm that the repository contains a check-in.The plugin fails to start: Check Java 21, OS/CPU compatibility, and that the server and agents restarted after the upgrade.
Checkout folder conflicts: Use separate mappings for each root, save required outputs, and request clean checkout where necessary.
A symbolic link or mapping is rejected: Review the limitations below and exclude unsupported paths or adjust the rules.
Changes do not start builds: Check the VCS Trigger, branch specification, trigger branch filter, and any errors in changes collection.
Use the standard TeamCity server logs and agent Build Log when investigating failures. Include versions, operating system, checkout mode, sanitized rules, and the error message in a support request. Remove passwords and other credentials from logs before sharing them.
Supported Scope¶
Version 0.1.0.0 supports HTTP/HTTPS access, anonymous or username/password credentials, multiple branches, and server-side or agent-side checkout. Repository access is read-only; the plugin does not create remote commits, merges, tags, or branches.
Server checkout and directory-selection agent checkout do not create symbolic links. Exclude those paths or use whole-repository agent checkout on a suitable platform.
Agent checkout rules do not support wildcards or single-file remapping.
Directory selection supports up to 500,000 files.
SSH/private-key authentication, OAuth/token refresh, and personal builds are not supported.