Team Foundation Server plugin for Jenkins

Copyright © Erik Ramfelt, Olivier Dagenais, CloudBees, Inc. and others. Licensed under MIT Licence.

Summary

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 (VSTS).

Quick links

• 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

What can you do with it?

Allows you to use TFS and VSTS as an SCM in Jenkins jobs. At the moment, this plugin supports:

• Retrieving read-only copies of files and folders from TFS/VSTS.
• Polling TFS/VSTS to automatically start builds when there are changes.
• Links from the Jenkins change sets to the TFS/VSTS web interface. (Also known as a repository browser)
• Creating a label in TFS

The plugin will automatically create a workspace in TFS/VSTS and map a work folder (in the Jenkins workspace) to it.

Supported versions

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.

Team Foundation Server (TFS) / Visual Studio Team Services (VSTS)

The following table indicates compatibility and support for versions of TFS and VSTS.

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/14
Microsoft Visual Studio Team System 2008 Team Foundation Server	❌	⚠️ 2013/04/09
Microsoft Visual Studio 2005 Team Foundation Server	❌	⚠️ 2011/07/12

Operating Systems

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

Jenkins

The plugin is built against Jenkins version 1.448 and that's the version integration tests are run against.

Configuration

Requirements

4.0.0 and later (New!)

Ever since release 4.0.0, a command-line client or tool is no longer necessary as all the interaction with the TFS or VSTS server 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.

3.2.0 and earlier

Versions 3.2.0 and earlier of the plugin required a TFS command line tool to be installed on the build agents that will be retrieving source code from TFS.

1. Install either Microsoft Visual Studio or Microsoft Team Explorer Everywhere Command-Line Client (CLC) on the build agents
2. Add tf.exe (Visual Studio) OR one of tf.cmd or tf (TEE CLC) to the PATH of the build agents' user(s).

Job configuration

Field	Description
Server URL	The URL to the Team Project Collection. Examples: https://tfs02.codeplex.com, https://example.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: $/project/trunk/src.
User name	The name of the user that will be connecting to TFS/VSTS 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 Team System Web Access to turn on links inside Jenkins jobs (in the Changes page) back to TFS / VSTS, for easier traceability. If the TFS server is reached by users through a different URL than that provided in Server URL, such as the Fully-Qualified Domain Name (FQDN), provide a value for the URL sub-field.

User name and password

Team Foundation Server (on-premises)

For [on-premises] Team Foundation Server, the User name can be specified in two ways:

1. EXAMPLE-DOMAIN\user
2. [email protected]

Visual Studio Team Services (VSTS, a.k.a. TFS in the cloud, previously known as Visual Studio Online)

For VSTS, there are also two options:

1. Personal access tokens (recommended)
   1. In VSTS, click your name in the top right corner and select My profile.
   2. Select the Security hub.
   3. In the Personal access tokens area, select Add.
   4. Describe the token (use something like "Jenkins server at jenkins.example.com"), select an expiry timeframe, double-check the VSTS account the token will be valid for and, until the corresponding defect in VSTS is fixed, select All scopes.
   5. Click [Create Token] and copy the generated personal access token to the clipboard.
   6. Back to Jenkins, enter the e-mail address associated with your VSTS account as the User name and the generated personal access token as the User password.
2. Alternate credentials
   1. In VSTS, click your name in the top right corner and select My profile.
   2. Select the Security hub.
   3. In the Alternate credentials area, select Enable alternate authentication credentials.
   4. Enter a secondary user name and password, then click [Save].
   5. Back to Jenkins, re-enter those credentials in the User name and User password fields.

Checkout by label (New since version 3.2.0)

The plugin now supports checking out from a specific label. 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. ℹ️

1. Turn off SCM polling by making sure the Poll SCM checkbox is cleared (unchecked).
2. Tick the This build is parameterised checkbox
   1. Add a String Parameter
   2. Set its Name to VERSION_SPEC
   3. Set its Description to the following:

   Enter a valid version spec to use when checking out.
   Labels are prefixed with "L" and can optionally be scoped by appending "@" with a scope name
   (see the documentation on the Label Command at https://msdn.microsoft.com/en-us/library/9ew32kd1.aspx).
   Example: "LFoo"
   

3. 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.

Proxy server support (New since version 4.1.0)

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.

Build environment variables

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 project path that is mapped to the workspace.
• TFS_SERVERURL - The URL to the Team Foundation Server.
• TFS_USERNAME - The user name that is used to connect to the Team Foundation Server.
• TFS_CHANGESET - The change set number that is checked out in the workspace

FAQ

How should I set up the plugin for my CodePlex project?

• Find out the TFS 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 is snd. 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 Team foundation server.

That's all you need to do to start retrieving files from your project at codeplex.com.

The plugin is having problems parsing the dates that TF outputs, what can I do?

ℹ️ 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.

Timeline

Future

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.

Present

The next release will be 4.1.0. See what's been committed since 4.0.0 and the upcoming [ReleaseNotes.md].

Past

Details about previous releases can be found on the Releases page.