Use Jenkins to restore and publish packages

Last Update: 3/6/2017

Team Services | TFS 2017

Visual Studio Team Services's package management works with the continuous integration tools your team already uses. In this Jenkins walkthrough, you'll create a NuGet package and publish it to a Visual Studio Team Services feed. If you need help on Jenkins setup, you can learn more on the Jenkins wiki.

Setup

This walkthrough uses Jenkins 1.635 running on Windows 10. The walkthrough is simple, so any recent Jenkins and Windows versions should work.

Ensure the following Jenkins plugins are enabled:

Some of these plugins are enabled by default. Others you will need to install by using Jenkins's "Manage Plugins" feature.

The example project

The sample project is a simple shared library written in C#.

  • To follow along with this walkthrough, create a new C# Class Library solution in Visual Studio 2015.
  • Name the solution "FabrikamLibrary" and uncheck the Create directory for solution checkbox.
  • On the FabrikamLibrary project's context menu, choose Properties, then choose Assembly Information.
  • Edit the description and company fields. Now generating a NuGet package is easier.

Update assembly info to supply a description and company

  • Check the new solution into a Git repo where your Jenkins server can access it later.

Add the Team Services NuGet tools to your repo

The easiest way to use the Team Services NuGet service is by adding the Microsoft.VisualStudio.Services.NuGet.Bootstrap package to your project.

  • Open a PowerShell prompt and cd to the root directory of your app's code.
  • Get a copy of nuget.exe to use temporarily. The PowerShell command Invoke-WebRequest https://dist.nuget.org/win-x86-commandline/latest/nuget.exe -OutFile nuget.exe makes this easy.
  • In the PowerShell window, run the command .\nuget.exe install -OutputDirectory packages Microsoft.VisualStudio.Services.NuGet.Bootstrap to fetch the bootstrapping tools.
  • Run .\packages\Microsoft.VisualStudio.Services.NuGet.Bootstrap.*\tools\Bootstrap.ps1 to initialize your environment.
    • This will create a nuget.config in the root of your repo, where you can specify the feeds you want NuGet to use.
    • It will also create an init script which developers and build agents run each time they want to work with this repo. init ensures you always have the latest VSTS NuGet tools and also sets up authentication to VSTS-hosted feeds.
  • Delete the copy of nuget.exe you downloaded earlier: rm .\nuget.exe
    • Going forward, this repo will rely on a copy of nuget.exe installed by the bootstrapping tools.
  • Update your .gitignore/.tfignore file to exclude .tools/ and packages/.
  • Update nuget.config to list the feeds used by your app.
  • Check in the changes to your repo.

Create a package from your project

Whenever you work from a command line, run init.cmd first. This sets up your environment to allow you to work with nuget.exe and the Team Services NuGet service.

  • Change into the directory containing FabrikamLibrary.csproj.
  • Run the command nuget spec to create the file FabrikamLibrary.nuspec, which defines how your NuGet package builds.
  • Edit FabrikamLibrary.nuspec to remove the boilerplate tags <licenseUrl>, <projectUrl>, and <iconUrl>. Change the tags from Tag1 Tag2 to fabrikam.
  • Ensure that you can build the package using the command nuget pack FabrikamLibrary.csproj. Note, you should target the .csproj (project) file, not the NuSpec file.
  • A file called FabrikamLibrary.1.0.0.0.nupkg will be produced.

Set up a feed in Team Services and add it to your project

  • Create a feed in your Team Services account called MyGreatFeed. Since you're the owner of the feed, you will automatically be able to push packages to it.
  • Add the URL for the feed you just generated to the nuget.config in the root of your repo.
    • Find the <packageSources> section of nuget.config.
    • Just before </packageSources>, add a line using this template: <add key="MyGreatFeed" value="{feed_url}" />. Change {feed_url} to the URL of your feed.
    • Commit this change to your repo.

Add your feed URL to nuget.config

  • Generate a PAT (personal access token) for your user account. This PAT will allow the Jenkins build process to authenticate to Visual Studio Team Services as you, so be sure to protect your PAT like a password.
  • Save your feed URL and PAT to a text file for use later in the walkthrough.

Create a build definition in Jenkins

New Jenkins build definition

  • Under Source Code Management, set the build to use Git and select your Git repo.
  • Under Build Environment, select the Use secret text(s) or file(s) option.
    • Add a new Username and password (separated) binding.
    • Set the Username Variable to "FEEDUSER" and the Password Variable to "FEEDPASS". These are the environment variables Jenkins will fill in with your credentials when the build runs.
    • Choose the Add button to create a new username and password credential in Jenkins.
    • Set the username to "token" and the password to the PAT you generated earlier. Choose Add to save these credentials.

New credentials in Jenkins

Jenkins build environment

  • Under Build (see screenshot below), follow these steps:
    • Choose Execute Windows batch command. In the Command box, type init.cmd.
    • Choose Build a Visual Studio project or solution using MSBuild. This step should point to msbuild.exe and FabrikamLibrary.sln.
    • Choose Execute Windows batch command again, but this time, use this command: .tools\VSS.NuGet\nuget pack FabrikamLibrary\FabrikamLibrary.csproj.

Jenkins build steps

  • Save this build definition and queue a build.
  • The build's Workspace will now contain a .nupkg just like the one you built locally earlier.

Publish a package using Jenkins

These are the last walkthrough steps to publish the package to a feed:

  • Edit the build definition in Jenkins.
  • After the last build step (which runs nuget pack), add a new Execute a Windows batch command build step.
  • In the new Command box, add these two lines:
    • The first line puts credentials where NuGet can find them: .tools\VSS.NuGet\nuget sources update -Name "MyGreatFeed" -UserName "%FEEDUSER%" -Password "%FEEDPASS%"
    • The second line pushes your package using the credentials saved above: .tools\VSS.NuGet\nuget push *.nupkg -Name "MyGreatFeed" -ApiKey VSS

Push package

  • Queue another build. This time, the build machine will authenticate to Team Services and push the package to the feed you selected.