VSTS | TFS 2017 | TFS 2015
A release is a collection of artifacts. An artifact is a deployable component of your application. Release Management can deploy artifacts that are produced by a wide range of artifact sources, and stored in different types of artifact repositories.
When authoring a release definition, you link the appropriate artifact sources to your release definition. For example, you might link a Team Build build definition or a Jenkins project to your release definition.
When creating a release, you specify the exact version of these artifact sources; for example, the number of a build coming from Team Build, or the version of a build coming from a Jenkins project.
After a release is created, you cannot change these versions. A release is fundamentally defined by the versioned artifacts that make up the release. As you deploy the release to various environments, you will be deploying and validating the same artifacts in all environments.
A single release definition can be linked to multiple artifact sources. In this case, when you create a release, you specify individual versions for each of these sources.
Artifacts are central to a number of features in Release Management. Some of the features that depend on the linking of artifacts to a release definition are:
- Auto-trigger releases. You can configure new releases to be automatically created whenever a new version of an artifact is produced. For more details, see Continuous deployment triggers. Note that the ability to automatically create releases is available for only some artifact sources.
Artifact variables. Every artifact that is part of a release has metadata associated with it. This metadata includes the version number of the artifact, the branch of code from which the artifact was produced (in the case of build or source code artifacts), the definition that produced the artifact (in the case of build artifacts), and more. This information is accessible in the deployment tasks. For more details, see Artifact variables.
Work items and commits. The work items or commits that are part of a release are computed from the versions of artifacts. For example, each build in Team Build is associated with a set of work items and commits. The work items or commits in a release are computed as the union of all work items and commits of all builds between the current release and the previous release. Note that Release Management is currently able to compute work items and commits for only certain artifact sources.
Artifact download. Whenever a release is deployed to an environment, Release Management automatically downloads all the artifacts in that release to the agent where the deployment job runs. The procedure to download artifacts depends on the type of artifact. For example, Team Build artifacts are downloaded using an algorithm that downloads multiple files in parallel. Git artifacts are downloaded using Git library functionality. For more details, see Artifact download.
There are several types of tools you might use in your application lifecycle process to produce or store artifacts. For example, you might use continuous integration systems such as Team Build, Jenkins, or TeamCity to produce artifacts. You might also use version control systems such as Git or TFVC to store your artifacts. You can configure Release Management to deploy artifacts from all these sources.
By default, a release created from the release definition will use the latest version of the artifacts. At the time of linking an artifact source to a release definition, you can change this behavior by selecting one of the options to use the latest build from a specific branch by specifying the tags, a specific version, or allow the user to specify the version when the release is created from the definition. If you link more than one set of artifacts, you can specify which is the primary (default).
The following sections describe how to work with the different types of artifact sources.
You can link a release definition to any of the build definitions in your Visual Studio Team Services (VSTS) account or Team Foundation Server project collection.
you must include a Publish Artifacts task step in your build definition. For XAML build definitions, an artifact with the name drop is published implicitly.
Some of the differences in capabilities between different versions of TFS and VSTS are:
TFS 2015: You can link build definitions only from the same team project of your collection. You can link multiple definitions, but you cannot specify default versions. You can set up a continuous deployment trigger on only one of the definitions. When multiple build definitions are linked, the latest builds of all the other definitions are used, along with the build that triggered the release creation.
TFS 2017 and VSTS: You can link build definitions from any of the team projects in your collection or account. You can link multiple build definitions and specify default values for each of them. You can set up continuous deployment triggers on multiple build sources. When any of the builds completes, it will trigger the creation of a release.
The following features are available when using Team Build sources:
|Feature||Behavior with Team Build sources|
|Auto-trigger releases||New releases can be created automatically when new builds (including XAML builds) are produced. See Continuous Deployment for details. You do not need to configure anything within the build definition. See the notes above for differences between version of TFS.|
|Artifact variables||A number of artifact variables are supported for builds from Team Build.|
|Work items and commits||Team Build integrates with work items in TFS and VSTS. These work items are also shown in the details of releases. Team Build integrates with a number of version control systems such as TFVC and Git, GitHub, Subversion, and external Git repositories. Release Management shows the commits only when the build is produced from source code in TFVC or Git.|
|Artifact download||By default, build artifacts are downloaded to the agent. You can configure an option in the environment to skip the download of artifacts.|
|Deployment section in build||The build summary includes a Deployment section, which lists all the environments to which the build was deployed.|
To consume Jenkins artifacts, you must create a service endpoint with credentials to connect to your Jenkins server. For more details, see service endpoints and Jenkins service endpoint. You can then link a Jenkins project to a release definition. The Jenkins project must be configured with a post build action to publish the artifacts.
The following features are available when using Jenkins sources:
|Feature||Behavior with Jenkins sources|
|Auto-trigger releases||You cannot configure a continuous deployment trigger for Jenkins sources in a release definition. However, you can use the VSTS Continuous Deployment Plugin, available from the Jenkins website, to add post-build steps to Jenkins CI projects that trigger a release in TFS or VSTS when a build completes successfully.|
|Artifact variables||A number of artifact variables are supported for builds from Jenkins.|
|Work items and commits||Release Management cannot show work items or commits for Jenkins builds.|
|Artifact download||By default, Jenkins builds are downloaded to the agent. You can configure an option in the environment to skip the download of artifacts.|
Release Management in VSTS may not be able to contact your Jenkins server if, for example, it is within your enterprise network. In this case you can integrate Release Management with Jenkins by setting up an on-premises agent that can access the Jenkins server. You will not be able to see the name of your Jenkins projects when linking to a build, but you can type this into the link dialog field.
For more information about Jenkins integration capabilities, see VSTS Integration with Jenkins Jobs, Pipelines, and Artifacts.
TFVC, Git, and GitHub
There are scenarios in which you may want to consume artifacts stored in a version control system directly, without passing them through a build process. For example:
You manage configurations for various environments in different version control repositories, and you want to consume these configuration files directly from version control as part of the deployment process.
You manage your infrastructure and configuration as code (such as Azure Resource Manager templates) and you want to manage these files in a version control repository.
Because you can configure multiple artifact sources in a single release definition, you can link both a build definition that produces the binaries of the application as well as a version control repository that stores the configuration files into the same definition, and use the two sets of artifacts together while deploying.
Release Management integrates with Team Foundation Version Control (TFVC) repositories, Git repositories, and GitHub repositories.
You can link a release definition to any of the Git or TFVC repositories in any of the team projects in your collection (you will need read access to these repositories). No additional setup is required when deploying version control artifacts within the same collection.
When you link a Git or GitHub repository and select a branch, you can edit the default properties of the artifact types after the artifact has been saved. This is particularly useful in scenarios where the branch for the stable version of the artifact changes, and continuous delivery releases should use this branch to obtain newer versions of the artifact. You can also specify details of the checkout, such as whether check out submodules and LFS-tracked files, and the shallow fetch depth.
When you link a TFVC branch, you can specify the changeset to be deployed when creating a release.
The following features are available when using TFVC, Git, and GitHub sources:
|Feature||Behavior with TFVC, Git, and GitHub sources|
|Auto-trigger releases||You can configure a continuous deployment trigger for pushes into the repository in a release definition. This can automatically trigger a release when a new commit is made to a repository. See Triggers.|
|Artifact variables||A number of artifact variables are supported for version control sources.|
|Work items and commits||Release Management cannot show work items or commits associated with releases when using version control artifacts.|
|Artifact download||By default, version control artifacts are downloaded to the agent. You can configure an option in the environment to skip the download of artifacts.|
To integrate with TeamCity, you must first install the TeamCity artifacts for Release Management extension from Visual Studio Marketplace.
To consume TeamCity artifacts, start by creating a service endpoint with credentials to connect to your TeamCity server (see service endpoints for details).
You can then link a TeamCity build configuration to a release definition. The TeamCity build configuration must be configured with an action to publish the artifacts.
The following features are available when using TeamCity sources:
|Feature||Behavior with TeamCity sources|
|Auto-trigger releases||You cannot configure a continuous deployment trigger for TeamCity sources in a release definition. To create a new release automatically when a build is complete, add a script to your TeamCity project that invokes the Release Management REST APIs to create a new release.|
|Artifact variables||A number of artifact variables are supported for builds from TeamCity.|
|Work items and commits||Release Management cannot show work items or commits for TeamCity builds.|
|Artifact download||By default, TeamCity builds are downloaded to the agent. You can configure an option in the environment to skip the download of artifacts.|
Release Management in VSTS may not be able to contact your TeamCity server if, for example, it is within your enterprise network. In this case you can integrate Release Management with TeamCity by setting up an on-premises agent that can access the TeamCity server. You will not be able to see the name of your TeamCity projects when linking to a build, but you can type this into the link dialog field.
You can use the Release Management service in VSTS to deploy artifacts published by an on-premises TFS server. You don't need to make the TFS server visible on the Internet; you just set up an on-premises automation agent. Builds from an on-premises TFS server are downloaded directly into the on-premises agent, and then deployed to the specified target servers. They will not leave your enterprise network. This allows you to leverage all of your investments in your on-premises TFS server, and take advantage of the Release Management capabilities in VSTS.
Using this mechanism, you can also deploy artifacts published in one VSTS account from another VSTS account, or deploy artifacts published in one Team Foundation Server from another Team Foundation Server.
To enable these scenarios, you must install the TFS artifacts for Release Management extension from Visual Studio Marketplace. Then create a service endpoint with credentials to connect to your TFS server (see service endpoints for details).
You can then link a TFS build definition to your release definition. Choose External TFS Build in the Type list.
The following features are available when using external TFS sources:
|Feature||Behavior with external TFS sources|
|Auto-trigger releases||You cannot configure a continuous deployment trigger for external TFS sources in a release definition. To automatically create a new release when a build is complete, you would need to add a script to your build definition in the external TFS server to invoke REST APIs of Release Management and to create a new release.|
|Artifact variables||A number of artifact variables are supported for external TFS sources.|
|Work items and commits||Release Management cannot show work items or commits for external TFS sources.|
|Artifact download||By default, External TFS artifacts are downloaded to the agent. You can configure an option in the environment to skip the download of artifacts.|
Release Management in VSTS may not be able to contact an on-premises TFS server if, for example, it is within your enterprise network. In this case you can integrate Release Management with TFS by setting up an on-premises agent that can access the TFS server. You will not be able to see the name of your TFS projects or build definitions when linking to a build, but you can type these into the link dialog fields. In addition, when you create a release, VSTS may not be able to query the TFS server for the build numbers. Instead, type the Build ID (not the build number) of the desired build into the appropriate field, or select the Latest build.
Your artifacts may be created and exposed by other types of sources such as a NuGet repository. While we continue to expand the types of artifact sources supported in Release Management, you can start using it without waiting for support for a specific source type. Simply skip the linking of artifact sources in a release definition, and add custom tasks to your environments that download the artifacts directly from your source.
When you deploy a release to an environment, the versioned artifacts from each of the sources are, by default, downloaded to the automation agent so that tasks running within that environment can deploy these artifacts. The artifacts downloaded to the agent are not deleted when a release is completed. However, when you initiate the next release, the downloaded artifacts are deleted and replaced with the new set of artifacts.
A new unique folder in the agent is created for every release definition when you
initiate a release, and the artifacts are downloaded into that folder.
$(System.DefaultWorkingDirectory) variable maps to this folder.
Note that, at present, Release Management does not perform any optimization to avoid downloading the unchanged artifacts if the same release is deployed again. In addition, because the previously downloaded contents are always deleted when you initiate a new release, Release Management cannot perform incremental downloads to the agent.
You can, however, instruct Release Management to skip the automatic download of artifacts to the agent for a specific phase and environment of the deployment if you wish. Typically, you will do this when the tasks in that phase do not require any artifacts, or if you implement custom code in a task to download the artifacts you require.
Artifact source alias
To ensure the uniqueness of every artifact download, each artifact source linked to a release definition is automatically provided with a specific download location known as the source alias. This location can be accessed through the variable:
This uniqueness also ensures that, if you later rename a linked artifact source in its original location (for example, rename a build definition in Team Build or a project in Jenkins), you don't need to edit the task properties because the download location defined in the agent does not change.
The source alias is, by default, the name of the source selected when you linked the artifact source; depending on the type of the artifact source this will be the name of the build definition, job, project, or repository. You can edit the source alias from the artifacts tab of a release definition; for example, when you change the name of the build definition and you want to use a source alias that reflects the name of the build definition.
The source alias can contain only alphanumeric characters and underscores, and must start with a letter or an underscore
When you link multiple artifact sources to a release definition, one of them is designated as the primary artifact source. The primary artifact source is used to set a number of pre-defined variables. It can also be used in naming releases.
Release Management exposes a set of pre-defined variables that you can access and use in tasks and scripts; for example, when executing PowerShell scripts in deployment jobs. When there are multiple artifact sources linked to a release definition, you can access information about each of these. For a list of all pre-defined artifact variables, see variables.
Contributed links and additional information
- Code repo sources in Release Management
- TeamCity extension for Release Management
- Jenkins artifacts in Release Management
- External TFS artifacts for Release Management