Team Foundation Server Plugin

Skip to end of metadata
Go to start of metadata

Summary

This plugin integrates Microsoft Team Foundation Server source control (also known as TFVC) to Jenkins.

Plugin Information

Plugin ID tfs Changes In Latest Release
Since Latest Release
Latest Release
Latest Release Date
Required Core
Dependencies
4.0.0 (archives)
Aug 27, 2015
1.448
Source Code
Issue Tracking
Pull Requests
Maintainer(s)
GitHub
Open Issues
Pull Requests
Olivier Dagenais (id: olivierdagenais)
Usage Installations 2014-Aug 1942
2014-Sep 2046
2014-Oct 2125
2014-Nov 2116
2014-Dec 2098
2015-Jan 2139
2015-Feb 2189
2015-Mar 2456
2015-Apr 2475
2015-May 2466
2015-Jun 2639
2015-Jul 2677

With this plugin you can use a workspace that will create a work folder in the Jenkins workspace. At the moment, this plugin supports:

  • Retrieving read-only copies of files and folders from a Team Foundation Server.
  • Polling a Team Foundation Server to automatically start builds when there are changes.
  • Links from the Jenkins change sets to Team Server Web Access. (Also known as a repository browser)

The plugin will automatically create a workspace on the Team Foundation Server 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 / Visual Studio Online

The plugin has been tested against Visual Studio Online, as well as the following versions of TFS:

  • 2012 RTM
  • 2013 RTM
  • 2015 RTM

Note that mainstream support for TFS 2010 ended 2015/07/14.

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 TFS command-line client or tool is no longer necessary as all the interaction with the TFS 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

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/VSO 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}.
Repository browser If the Team Foundation Server has any web access to the files, this can be configured here. By adding a repository browser, the plugin will create links in the Changes page to the repository browser. Currently the plugin supports Team System Web Access.

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. user@domain.example.com

Visual Studio Online (a.k.a. TFS-as-a-service)

For Visual Studio Online, there are also two options:

  1. Personal access tokens (recommended)
    1. 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 Visual Studio Online account the token will be valid for and, until the corresponding defect in VSO 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 VSO account as the User name and the generated personal access token as the User password.
  2. Alternate credentials
    1. 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:

  1. Turn off SCM polling by making sure the Poll SCM checkbox is cleared (unchecked).
    Polling TFS 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.
  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 Enter a valid TFS 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). 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.

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 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 issue #4184 and issue #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.

Plugin version information

Change log

Future: 4.1.0

After version 4.0.0, the following pull requests will be revisited and updated for inclusion into a tentatively-titled 4.1.0 release:

  • #3: JENKINS-4709 - Exclusion Regions
  • #7: Jenkins TFS Plugin Enhancements
  • #9: Support NO_CI
  • #10 French version of tf.exe
  • #26: TFS2012
  • #27: TFS Exclusion JENKINS-24593
  • #28: Support workspace cloaking
  • #30: "Upgrade TFS SDK to version 12.0.2"
  • #33: "Local workspaces are supported."
  • #34: "Partial Success == Failure"
  • #35: "overwrite flag"
  • #38: "TFSLabeler: Using getRootProject and getRootBuild to get Scm and Workspace"
  • #39: "Fix current logging to actually print the username and add a message"
  • #40: "JENKINS-29156 include work items info in the changeset log"
  • #43: "Fix multi configuration job"

4.0.0 (Aug 27 2015)

  • Minor development improvement: Add framework for integration and functional tests. (pull request #41)
  • Minor improvement: Upgrade to version 14.0.1 of the TFS SDK for Java. (pull request #45)
  • Major feature: use only the TFS SDK for Java for talking to TFS/VSO, eliminating the need to install Visual Studio, Team Explorer or Team Explorer Everywhere on build agents. Made possible through the following pull requests: #42, #44, #46, #47, #48, #49, #51, #52, #54, #56
  • Minor feature: Add support for Visual Studio Online. Made possible through the following pull requests: #50, #57
  • Minor feature: More efficient single version history. Thanks to Matt Mitchell (@mmitche) who reported the issue through pull request #53, ultimately fixed with pull request #55.
  • Minor development improvement: Fix Javadoc errors and enforce Javadoc verification. (pull request #58)

3.2.0 (Apr 14 2015)

  • Fix: Passwords are no longer encoded but encrypted. Thanks to Nicolas De loof (@ndeloof) who helped fix issue #23033.
    This makes downgrading the plugin difficult - create a backup of the job configuration XML files if you intend to downgrade to pre-3.2.0 and don't want to re-enter the TFS user's password.
  • Fix: TFS plugin does not create label as trigger value is not saved in config. Thanks to Chad Strauch (@boatski) who fixed issue #23344 with pull request #29.
  • Minor feature: can now checkout by version spec (i.e. label). Thanks to Vinicius Kopcheski (@kopcheski) who implemented issue #3002 with pull request #24, subsequently improved with pull request #36.

3.1.1 (Feb 25 2014)

3.0.1 (Oct 25 2013)

  • Fixes UnsatisfiedLinkError when path to plugin contains spaces. Thanks to Jesse Jacob for reporting and helping diagnose the problem. (pull request #18)

3.0.0 (Oct 23 2013)

  • Now using the TFS SDK for Java to obtain richer information about committers/culprits. (pull request #17)
  • If you get an UnsatisfiedLinkError, either:
    • Please upgrade to 3.0.1 at your earliest convenience
    • Work around the defect by defining the com.microsoft.tfs.jni.native.base-directory property to point to the tfs plugin's native folder.
      For example, add the following to the /service/arguments element of jenkins.xml, before the -jar argument:
      "-Dcom.microsoft.tfs.jni.native.base-directory=C:\Program Files (x86)\Jenkins\plugins\tfs\WEB-INF\lib\native"

2.0 (Sep 4 2013)

1.20 (Sep 17 2011)

1.19 (Sep 05 2011)

  • Fixed the problem of getting the change set number from the checked out workspace. (issue #10900)

1.18 (Sep 01 2011)

  • Fixed so german output from the tfs tool can be parsed properly. (issue #10784)
  • Added new env variable containing the TFS change set number TFS_CHANGESET. mzagar contributed the fix. (issue #6078)

1.17 (Mar 10 2011)

  • Reverted the fix that changed the way how URLs to TSWA was built. (issue #7394)

1.16 (Mar 7 2011)

  • Fixed so a build no longer throws a NullPointerException when the node that it was previous built on was deleted. (issue #8322)
  • Updated the TFS Web Access URLs so they work with TFS 2008. (issue #7394)

1.12 (Jan 4 2011)

  • Fixed so changes that was committed after the workspace was updated is not included into the change log. (issue #6596)
  • Fixed so the date is parsed using the correct keyword. (issue #6454)
  • Updated plugin so it works with the TEE command line tool. (issue #6870)
  • Added support for change sets that has been checked in by a user not responsible for the change. (ie /Author checkins) issue #4943)

1.11 (Feb 1 2010)

1.10 (Dec 30 2009)

  • Changed user and domain name regex to be more lenient than only accepting lower case characters. (issue #4600)
  • Updated code for more recent Hudson

1.9 (Aug 31 2009)

  • Updated TFS SCM to conform with changes in base SCM class. This fixes the NPE when polling a server. (issue #4325)

1.8

  • Fixed so when a workspace is removed or wiped on a node, or when the project is deleted or renamed, the TFS workspace will be deleted. (issue #2208)
  • Fixed a problem when TF command line tool outputed dates containing p.m. which is not recognized by the default date parsers. (issue #4184)
  • The TFS workspace is no longer removed during a build, instead it is removed at the begning of the next build if the Use update flag is not set (issue #3778)
  • If workspace name, project path or local folder is changed in the configuration; the next build will remove the TFS workspace and create a new one with the new configuration. (issue #3784)

1.6

  • Updated regular expression to avoid StackOverFlowError while parsing long changesets history data (issue #3683)
  • Added TFS_PROJECTPATH, TFS_SERVERURL, TFS_USERNAME to the environment variable list (issue #3784)

1.5

  • Fixed a problem with diff links for the Team System Web Access repository browser (issue #3780)
  • Fixed a problem when comments contained forbidden XML chars (such as &, <, >, etc), which would throw an exception when trying to load the change log. (issue #2229)

1.4

  • Fixed a problem with interfacing with the tf tool on linux (issue #2241)
  • Fixed a problem with name casing in a resource folder (issue #2229)
  • Fixed a problem with workspace names containing a space (issue #2264)
  • Fixed a problem if the workspace already existed on another computer it was deleted at the end of the checkout (issue #2268)
  • Added the macro ${NODE_NAME} that can be used in a workspace name
  • Added very basic support for the opentf client (issue #2277)
  • Fixed so the workspace name and work folder path are available as build environmental variables (issue #2266)
  • Fixed so the build is not failed if the TF tool returns a exit code for partial success (exit code=1)
  • Fixed so invalid characters in the workspace name are replaced with _
  • Added support for paramterized builds (server url, project path and workspace name can contain build parameters) (issue #2302)

1.3

  • Improved support for Team System Web Access; added links to file content and diffs to previous version.

1.2

  • Added support for Team System Web Access repository browser. Now the Changes page has links to TSWA.
  • Fixed a bug where the work folder was not cleaned between builds if the job is not using the update feature.

1.1

  • Quick release for supporting older Hudsons than 1.234

1.0

  • Initial version supporting Microsoft and Teamprise command line clients.

Labels

Edit
plugin-scm plugin-scm Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

Add Comment