Copyright © Erik Ramfelt, Olivier Dagenais, CloudBees, Inc. and others. Licensed under MIT Licence.
This plugin integrates Team Foundation Version Control, also known as TFVC, to Jenkins by connecting to Team Foundation Server (TFS) and Visual Studio Team Services (Team Services).
- The legacy wiki page on the Jenkins Confluence instance
- Build status of master and pull requests: (thanks to CloudBees!)
- Issues are tracked by the Jenkins JIRA
- Download the latest release from the Jenkins CDN or from the GitHub Releases page
Allows you to use a TFVC repository as an SCM in Jenkins jobs. At the moment, this plugin supports:
- Retrieving read-only copies of files and folders from a TFVC repository.
- Polling a TFVC repository to automatically start builds when there are changes.
- Links from the Jenkins change sets to the TFVC repository web interface. (Also known as a repository browser)
- Creating a label in the TFVC repository
The plugin will automatically create a workspace in TFS/Team Services and map a work folder (in the Jenkins workspace) to it.
The following sub-sections list the various versions of software that were tested and are thus supported. The plugin might work with other versions, they just haven't been tested.
The following table indicates compatibility and support for versions of TFS and Team Services.
Version Supported by the TFS plugin? Mainstream Support End Date Visual Studio Team Services ✅ n/a Visual Studio Team Foundation Server 2015 ✅ 2020/10/13 Microsoft Visual Studio Team Foundation Server 2013 ✅ 2019/04/09 Microsoft Visual Studio Team Foundation Server 2012 ✅ 2018/01/09 Microsoft Visual Studio Team Foundation Server 2010 ❌ ⚠️ 2015/07/14Microsoft Visual Studio Team System 2008 Team Foundation Server ❌ ⚠️ 2013/04/09Microsoft Visual Studio 2005 Team Foundation Server ❌ ⚠️ 2011/07/12
The plugin has been tested against the following operating systems and versions, with the latest updates as of 2015/08/27.
Name | Version |
---|---|
Windows Server | 2012 R2 |
Mac OS X | Yosemite 10.10.5 |
Ubuntu Linux | Server 14.04 LTS |
The plugin is built against Jenkins version 1.448 and that's the version integration tests are run against.
Ever since release 4.0.0, a command-line client or tool is no longer necessary as all the interaction with TFS or Team Services is done using the TFS SDK for Java. The native libraries needed by the SDK are automatically copied to a sub-directory under the agent user's home folder.
Versions 3.2.0 and earlier of the plugin required a command line tool to be installed on the build agents to retrieve source code from the TFVC repository.
- Install either Microsoft Visual Studio or Microsoft Team Explorer Everywhere Command-Line Client (CLC) on the build agents
- Add
tf.exe
(Visual Studio) OR one oftf.cmd
ortf
(TEE CLC) to thePATH
of the build agents' user(s).
Field | Description |
---|---|
Collection URL |
The URL to the Team Project Collection. Examples: https://tfs02.codeplex.com , https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection , http://tfs:8080/tfs/DefaultCollection |
Project path |
The Team Project and path to retrieve from the server. The project path must start with $/ , and contain any sub path that exists in the project repository. Example: $/Fabrikam-Fiber-TFVC/AuthSample-dev |
User name |
The name of the user that will be connecting to TFS/Team Services to query history, checkout files, etc. See User name and password below for a full description. |
User password |
The password, alternate password or personal access token associated with the user. See User name and password below for more details. |
Use update |
If this option is checked, then the workspace and work folder will not be removed at the end of build. This makes the build faster, but artifacts remain between builds. If it is not checked, the plugin will create a workspace and map it to a local folder at the start of the build, and then delete the workspace at the end of the build. |
Local workfolder |
The name of the local work folder. The specified folder will contain the files retrieved from the repository. Default is . , ie the files will be downloaded into the Hudson workspace folder. |
Workspace name |
The name of the workspace that Jenkins should use when creating and deleting workspaces on the server. The workspace name supports three macros; ${JOB_NAME} is replaced by the job name, ${USER_NAME} is replaced by the user name Jenkins is running as and ${NODE_NAME} is replaced by the name of the node. Default workspace name is Hudson-${JOB_NAME}-${NODE_NAME} . |
Cloaked paths |
A collection of server paths to cloak to exclude from the workspace and from the build trigger. Multiple entries must be placed onto separate lines. |
Repository browser |
Select Microsoft Team Foundation Server/Visual Studio Team Services to turn on links inside Jenkins jobs (in the Changes page) back to TFS/Team Services, for easier traceability. If the TFS server is reached by users through a different URL than that provided in Collection URL , such as the Fully-Qualified Domain Name (FQDN), provide a value for the URL sub-field. |
For [on-premises] Team Foundation Server, the User name can be specified in two ways:
EXAMPLE-DOMAIN\user
user@domain.example.com
For Team Services, there are also two options:
- Personal access tokens (recommended)
- In Team Services, click your name in the top right corner and select Security.
- In the Personal access tokens area, select Add.
- Describe the token (use something like "Jenkins server at jenkins.example.com"), select an expiry timeframe, double-check the Team Services account the token will be valid for and, until the corresponding defect in Team Services is fixed, select All scopes.
- Click [Create Token] and copy the generated personal access token to the clipboard.
- Back to Jenkins, enter the e-mail address associated with your Team Services account as the User name and the generated personal access token as the User password.
- Alternate credentials
- In Team Services, click your name in the top right corner and select Security.
- In the Alternate credentials area, select Enable alternate authentication credentials.
- Enter a secondary user name and password, then click [Save].
- Back to Jenkins, re-enter those credentials in the User name and User password fields.
The plugin now supports checking out from a specific label or any valid versionspec. Here's how to configure a job to do that:
ℹ️ Polling the server doesn't make sense when you want to build for a specific label because polling is not [currently] label-aware and could queue a build every polling interval. ℹ️
- Turn off SCM polling by making sure the Poll SCM checkbox is cleared (unchecked).
- Tick the This build is parameterised checkbox
- Add a String Parameter
- Set its Name to VERSION_SPEC
- Set its Description to the following:
Enter a valid version spec to use when checking out. Labels are prefixed with "L" and changesets are prefixed with "C". See the following for a versionspec reference: https://www.visualstudio.com/docs/tfvc/use-team-foundation-version-control-commands#use-a-versionspec-argument-to-specify-affected-versions-of-items Examples: "LFoo", "C42"
- Save the job.
Now, the next time you want to queue a build, you will need to provide a value for the VERSION_SPEC parameter. The build will then perform a checkout of the source as of the specified VERSION_SPEC.
In the event Jenkins is deployed on a network with no direct access to other networks (such as the internet), the TFS plugin now supports connecting through unauthenticated proxy servers.
ℹ️ The version of
httpclient
currently used by the TFS SDK does not support proxy authentication. ℹ️
Follow the instructions at JenkinsBehindProxy to configure Jenkins' use of a proxy server, which the TFS plugin also uses.
The plugin will set the following environment variables for the build, after a checkout:
- TFS_WORKSPACE - The name of the workspace.
- TFS_WORKFOLDER - The full path to the working folder.
- TFS_PROJECTPATH - The TFVC project path that is mapped to the workspace.
- TFS_SERVERURL - The URL to the Team Project Collection.
- TFS_USERNAME - The user name that is used to connect to TFS/Team Services.
- TFS_CHANGESET - The change set number that is checked out in the workspace
- Find out the server for your project, which is displayed in the source code page for your project at codeplex.com.
- The user name must be suffixed with
_cp
and the domain issnd
. If your user name is redsolo, then enter "snd\redsolo_cp
" as the user name in the plugin configuration. - Note that the user must be a member of the project to be able to create a workspace on the CodePlex server.
That's all you need to do to start retrieving files from your project at codeplex.com.
ℹ️ If you can upgrade to version 4 and up, then you can avoid a whole class of TF output parsing difficulties, otherwise, read on. ℹ️
The TF command line outputs date according to the locale and Microsofts own specification. Sometimes the outputed date can not be parsed by any of the default locale dependent parsers that the JDK includes (for some more details, see JENKINS-4184 and JENKINS-4021). This will throw an exception in the change set parsing and fail the build.
To fix this, do the following:
- Change the locale by Windows Regional Settings to United States and English on the server and all hudson nodes. After that tf.exe should output dates in english, which can be parsed properly.
- Start Hudson using the UnitedStates, English locale. Either set it using
-Duser.language=en -Duser.country=US
on the command line or check the documentation for the container that Hudson is running within.
The best way to get an idea of what will be coming in future releases is to look at the list of open pull requests.
The next release will be 4.2.0. See what's been committed since 4.1.0 and the upcoming ReleaseNotes.md.
Also planned for release 4.2.0 are the following:
- JENKINS-3033: TFS plug-in 4.0.0 lists all workspaces on server
- #33: Local workspaces are supported
- #35: overwrite flag
Details about previous releases can be found on the Releases page.