Skip to content

vishnugms/tfs-plugin

BranchesTags
 
 

Repository files navigation

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) and Git to Jenkins by connecting to Team Foundation Server (TFS) and Visual Studio Team Services (Team Services).

Quick links

What can you do with it?

That depends on which version control system you use in TFS/Team Services:

Team Foundation Version Control

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.

Git

The TFS plug-in for Jenkins enhances the Git plug-in for Jenkins by adding some integration features:

  • A push trigger, to request builds of specific commits in Git repositories without needing to schedule SCM polling
  • A build step that adds a "build pending" status to the associated pull request and/or commit in TFS/Team Services
  • A post-build action that add a "build completed" status to the associated pull request and/or commit in TFS/Team Services
  • Some endpoints for TFS/Team Services to use to activate the integration. Please refer to the Jenkins with Visual Studio Team Services page for instructions on configuring the integration.

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 (Team Services)

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/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.580 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 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.

3.2.0 and earlier

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.

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

Global configuration

To make use of the Git integration with TFS/Team Services, it is necessary to first configure your team project collection(s). Follow these instructions for each team project collection (most organizations will only have one).

  1. Add credentials:
    1. Select Jenkins > Credentials
    2. Select Add domain
      1. In the Domain Name field, enter the host's friendly name, such as fabrikam-fiber-inc
      2. In the Description field, you can enter some notes, such as who maintains the server, etc.
      3. Next to Specification, select Add > Hostname
        1. In the Include field, enter the Fully-Qualified Domain Name (FQDN), such as fabrikam-fiber-inc.visualstudio.com
      4. Click OK
    3. Select Add Credentials
      1. For the Kind field, select Username with password
      2. For the Scope field, select Global (Jenkins, nodes, items, all child items, etc)
      3. See the User name and password section below for the values of the Username and Password; a Personal Access Token (PAT) is strongly recommended, with the following Authorized Scopes:
        1. Code (read)
        2. Code (status)
      4. You can use the Description field to record details about the PAT, such as its intended collection, the selected authorization scopes and expiration date. For example: fabrikam-fiber-inc, code read+status, expires 2017-08-05
      5. Click OK
  2. Add the collection URL and associate it with the right credential:
    1. Select Jenkins > Manage Jenkins > Configure System
    2. Scroll to TFS/Team Services and click Add
      1. If using Team Services, the value of the Collection URL field should omit /DefaultCollection.
      2. Select the associated Credentials value created earlier.
      3. Click Test Connection.
    3. Click Save

Job configuration

Team Foundation Version Control

If your source code is in a TFVC repository, this section is for you.

SCM configuration

Field Description
Collection URL The URL to the Team Project Collection. Examples: https://tfs02.codeplex.com, https://fabrikam-fiber-inc.visualstudio.com, 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.

Git

If your source code is in a Git repository located on a TFS/Team Services server, this section is for you. Make sure you first followed the instructions in "Global configuration" and added your team project collections, associated with credentials.

Git configuration

If you didn't have the Git plug-in for Jenkins already, installing the TFS plug-in for Jenkins should have brought it on as a dependency.

  1. Use the Git Source Code Management and add the URL to your Git repository in TFS/Team Services, omitting the /DefaultCollection if you are using Team Services.
  2. If you haven't done so already, follow the instructions in the "User name and password" section to generate a Personal Access Token, and then add a "Credential" as specified in the "Global configuration" section. You should then be able to select it in the Credentials field.
  3. To be able to build the merge commits created for pull requests in TFS/Team Services, click the Advanced... button
    1. In the Name field, enter origin (or some unique name if you already have other repositories)
    2. In the Refspec field, enter +refs/heads/*:refs/remotes/origin/* +refs/pull/*:refs/remotes/origin-pull/* (replacing "origin" as necessary)
  4. Scroll down to Build Triggers and you can now check the Build when a change is pushed to TFS/Team Services checkbox.
  5. Scroll down to Build, select Add build step > Set build pending status in TFS/Team Services, moving it first in the list of steps, to notify TFS/Team Services as early as possible that a Jenkins build has been started.
  6. Add other build steps, as necessary.
  7. Scroll down to Post-build Actions, select Add post-build action > Set build completion status in TFS/Team Services.

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 Team Services (Team Services, previously known as Visual Studio Online)

For Team Services, there are also two options:

  1. Personal access tokens (recommended)
    1. In Team Services, click your name in the top right corner and select Security.
    2. In the Personal access tokens area, select Add.
    3. 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.
    4. Click [Create Token] and copy the generated personal access token to the clipboard.
    5. 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.
  2. Alternate credentials
    1. In Team Services, click your name in the top right corner and select Security.
    2. In the Alternate credentials area, select Enable alternate authentication credentials.
    3. Enter a secondary user name and password, then click [Save].
    4. 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 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. ℹ️

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

ℹ️ Support for proxy servers requiring authentication is planned. ℹ️

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

FAQ

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

  • 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 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 CodePlex 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 5.0.0. See what's been committed since 4.1.0 and the upcoming ReleaseNotes.md.

Past

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

About

Jenkins tfs plugin

jenkins-ci.org/

Resources

Readme
Activity

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

30 tags

Packages

No packages published

Languages

  • Java 91.2%
  • HTML 8.4%
  • Other 0.4%