UniversalPackages@0 - Universal packages v0 task

Use this task to download, or package and publish Universal Packages.

Syntax

# Universal packages v0
# Download or publish Universal Packages.
- task: UniversalPackages@0
  inputs:
    command: 'download' # 'download' | 'publish'. Required. Command. Default: download.
    downloadDirectory: '$(System.DefaultWorkingDirectory)' # string. Required when command = download. Destination directory. Default: $(System.DefaultWorkingDirectory).
    #publishDirectory: '$(Build.ArtifactStagingDirectory)' # string. Required when command = publish. Path to file(s) to publish. Default: $(Build.ArtifactStagingDirectory).
  # Feed & package details
    feedsToUse: 'internal' # 'internal' | 'external'. Alias: internalOrExternalDownload. Required when command = download. Feed location. Default: internal.
    #externalFeedCredentials: # string. Alias: externalEndpoint. Optional. Use when internalOrExternalDownload = external && command = download. organization/collection connection. 
    #vstsFeed: # string. Alias: feedListDownload. Required when internalOrExternalDownload = internal && command = download. Feed. 
    #vstsFeedPackage: # string. Alias: packageListDownload. Required when internalOrExternalDownload = internal && command = download. Package name. 
    #vstsPackageVersion: # string. Alias: versionListDownload. Required when internalOrExternalDownload = internal && command = download. Version. 
    #feedDownloadExternal: # string. Required when internalOrExternalDownload = external && command = download. Feed (or Project/Feed if the feed was created in a project). 
    #packageDownloadExternal: # string. Required when internalOrExternalDownload = external && command = download. Package name. 
    #versionDownloadExternal: # string. Required when internalOrExternalDownload = external && command = download. Version. 
  # Feed & package details
    #feedsToUsePublish: 'internal' # 'internal' | 'external'. Alias: internalOrExternalPublish. Required when command = publish. Feed location. Default: internal.
    #publishFeedCredentials: # string. Alias: externalEndpoints. Required when internalOrExternalPublish = external && command = publish. organization/collection connection. 
    #vstsFeedPublish: # string. Alias: feedListPublish. Required when internalOrExternalPublish = internal && command = publish. Destination Feed. 
    #vstsFeedPackagePublish: # string. Alias: packageListPublish. Required when internalOrExternalPublish = internal && command = publish. Package name. 
    #feedPublishExternal: # string. Required when internalOrExternalPublish = external && command = publish. Feed (or Project/Feed if the feed was created in a project). 
    #packagePublishExternal: # string. Required when internalOrExternalPublish = external && command = publish. Package name. 
    #versionOption: 'patch' # 'major' | 'minor' | 'patch' | 'custom'. Alias: versionPublishSelector. Required when command = publish. Version. Default: patch.
    #versionPublish: # string. Required when versionPublishSelector = custom && command = publish. Custom version. 
    #packagePublishDescription: # string. Optional. Use when command = publish. Description. 
  # Advanced
    #publishPackageMetadata: true # boolean. Optional. Use when command = publish && internalOrExternalPublish = internal. Publish pipeline metadata. Default: true.
    #verbosity: 'None' # 'None' | 'Trace' | 'Debug' | 'Information' | 'Warning' | 'Error' | 'Critical'. Verbosity. Default: None.
  # Output
    #publishedPackageVar: # string. Optional. Use when command = publish. Package Output Variable.

Inputs

command - Command
string. Required. Allowed values: download, publish. Default value: download.

Specifies the Universal Package command to run.

downloadDirectory - Destination directory
string. Required when command = download. Default value: $(System.DefaultWorkingDirectory).

Specifies the folder path where the task downloads the package's contents.

feedsToUse - Feed location
Input alias: internalOrExternalDownload. string. Required when command = download. Allowed values: internal (This organization/collection), external (Another organization/collection). Default value: internal.

Specifies a feed from this collection or another collection in Azure Artifacts.

externalFeedCredentials - organization/collection connection
Input alias: externalEndpoint. string. Optional. Use when internalOrExternalDownload = external && command = download.

Specifies the credentials to use for external registries located in the selected NuGet.config. For feeds in this organization or collection, leave this blank; the build's credentials are used automatically.

vstsFeed - Feed
Input alias: feedListDownload. string. Required when internalOrExternalDownload = internal && command = download.

Includes the selected feed. You must have Azure Artifacts installed and licensed to select a feed here. Specifies the FeedName for an organization-scoped feed and projectName/FeedName or ProjectID/FeedID for a project-scoped feed.

vstsFeedPackage - Package name
Input alias: packageListDownload. string. Required when internalOrExternalDownload = internal && command = download.

Specifies the name of the package for the task to download.

vstsPackageVersion - Version
Input alias: versionListDownload. string. Required when internalOrExternalDownload = internal && command = download.

Specifies the package version or uses a variable containing the version to download. This entry can also be a wildcard expression, such as *, to get the highest version. Examples: 1.* gets the highest version with major version 1, and 1.2.* gets the highest patch release with major version 1 and minor version 2.

feedDownloadExternal - Feed (or Project/Feed if the feed was created in a project)
string. Required when internalOrExternalDownload = external && command = download.

Specifies a feed in another organization/collection.

For project-scoped feeds, the value should be Project/Feed, where Project is the project's name or ID, and Feed is the feed's name/ID. For organization-scoped feeds, the value should be only the feed name.

packageDownloadExternal - Package name
string. Required when internalOrExternalDownload = external && command = download.

Specifies the package name to download.

versionDownloadExternal - Version
string. Required when internalOrExternalDownload = external && command = download.

Specifies the package version or uses a variable containing the version to download. This entry can also be a wildcard expression, such as *, to get the highest version. Examples: 1.* gets the highest version with major version 1, and 1.2.* gets the highest patch release with major version 1 and minor version 2. Wildcard patterns are not supported with pre-release packages.

publishDirectory - Path to file(s) to publish
string. Required when command = publish. Default value: $(Build.ArtifactStagingDirectory).

Specifies the path to list of files to be published.

feedsToUsePublish - Feed location
Input alias: internalOrExternalPublish. string. Required when command = publish. Allowed values: internal (This organization/collection), external (Another organization/collection). Default value: internal.

Specifies a feed from this collection or another collection in Azure Artifacts.

publishFeedCredentials - organization/collection connection
Input alias: externalEndpoints. string. Required when internalOrExternalPublish = external && command = publish.

Specifies the credentials to use for external feeds.

vstsFeedPublish - Destination Feed
Input alias: feedListPublish. string. Required when internalOrExternalPublish = internal && command = publish.

Specifies the project and the feed's name/GUID to publish to.

publishPackageMetadata - Publish pipeline metadata
boolean. Optional. Use when command = publish && internalOrExternalPublish = internal. Default value: true.

Associates this build/release pipeline's metadata (such as run # and source code information) with the package.

vstsFeedPackagePublish - Package name
Input alias: packageListPublish. string. Required when internalOrExternalPublish = internal && command = publish.

Specifies a package ID to publish or creates a new package ID if you've never published a version of this package before. Package names must be lower case and can only use letters, numbers, and dashes (-).

feedPublishExternal - Feed (or Project/Feed if the feed was created in a project)
string. Required when internalOrExternalPublish = external && command = publish.

Specifies the external feed name to publish to.

If the feed was created in a project, the value should be Project/Feed, where Project is the project's name or ID, and Feed is the feed's name. If the feed was not created in a project, the value should be only the feed name.

packagePublishExternal - Package name
string. Required when internalOrExternalPublish = external && command = publish.

Specifies the package name when publishing to an external feed.

versionOption - Version
Input alias: versionPublishSelector. string. Required when command = publish. Allowed values: major (Next major), minor (Next minor), patch (Next patch), custom. Default value: patch.

Specifies a version increment strategy. The custom value to input your package version manually. For new packages, the first version will be 1.0.0 if you specify major, 0.1.0 if you specify minor, or 0.0.1 if you specify patch. See the Semantic Versioning spec for more information.

versionPublish - Custom version
string. Required when versionPublishSelector = custom && command = publish.

Specifies a custom version schema for the package.

packagePublishDescription - Description
string. Optional. Use when command = publish.

Specifies the description of the package contents and/or the changes made in this version of the package.

verbosity - Verbosity
string. Allowed values: None, Trace, Debug, Information, Warning, Error, Critical. Default value: None.

Specifies the amount of detail displayed in the output.

publishedPackageVar - Package Output Variable
string. Optional. Use when command = publish.

Specifies a name for the variable that will contain the published package name and version.

Task control options

All tasks have control options in addition to their task inputs. For more information, see Control options and common task properties.

Output variables

None.

Remarks

Use this task to download, or package and publish Universal Packages.

My Pipeline needs to access a feed in a different project

If the pipeline is running in a different project than the project hosting the feed, you must set up the other project to grant read/write access to the build service. See Package permissions in Azure Pipelines for more details.

Examples

The simplest way to get started with the Universal Package task is to use the Pipelines task editor to generate the YAML. You can then copy the generated code into your project's azure-pipelines.yml file. In this example, the sample demonstrates how to quickly generate the YAML using a pipeline that builds a GatsbyJS progressive web app (PWA).

Universal Packages are a useful way to both encapsulate and version a web app. Packaging a web app into a Universal Package enables quick rollbacks to a specific version of your site and eliminates the need to build the site in the deployment pipeline.

This example pipeline demonstrates how to fetch a tool from a feed within your project. The Universal Package task is used to download the tool, run a build, and again uses the Universal Package task to publish the entire compiled GatsbyJS PWA to a feed as a versioned Universal Package.

Download a package with the Universal Package task

The second task in the sample project uses the Universal Package task to fetch a tool, imagemagick, from a feed that is within a different project in the same organization. The tool, imagemagick, is required by the subsequent build step to resize images.

1. Add the Universal Package task by clicking the plus icon, typing "universal" in the search box, and clicking the Add button to add the task to your pipeline.

   

2. Click the newly added Universal Package task and the Command to Download.

3. Choose the Destination directory to use for the tool download.

4. Select a source Feed that contains the tool, set the Package name, and choose Version of the imagemagick tool from the source Feed.

   

5. After completing the fields, click View YAML to see the generated YAML.

   

6. The Universal Package task builder generates simplified YAML that contains non-default values. Copy the generated YAML into your azure-pipelines.yml file at the root of your project's git repo.

   # Download Universal Package
   steps:
   - task: UniversalPackages@0
     displayName: 'Universal download'
     inputs:
       downloadDirectory: Application
       vstsFeed: '00000000-0000-0000-0000-000000000000/00000000-0000-0000-0000-000000000001'
       vstsFeedPackage: imagemagick
       vstsPackageVersion: 1.0.0
   

Publish a package with the Universal Package task

The last step in this sample pipeline uses the Universal Package task to upload the production-ready Gatsby PWA that was produced by the Run gatsby build step to a feed as a versioned Universal Package. Once in a feed, you have a permanent copy of your complete site that can be deployed to hosting provider and started with gatsby serve.

1. Add another Universal Package task to the end of the pipeline by clicking the plus icon, typing "universal" in the search box, and clicking the Add button to add the task to your pipeline. This task gathers all of the production-ready assets produced by the Run gatsby build step, produce a versioned Universal Package, and publish the package to a feed.

   

2. Set the Command to Publish.

3. Set Path to file(s) to publish to the directory containing your GatsbyJS project's package.json.

4. Choose a destination feed, a package name, and set your versioning strategy.

   

5. After completing the required fields, click View YAML.

6. Copy the resulting YAML into your azure-pipelines.yml file as before. The YAML for this sample project displays below.

   # Publish Universal Package
   steps:
   - task: UniversalPackages@0
     displayName: 'Universal publish'
     inputs:
       command: publish
       publishDirectory: Application
       vstsFeedPublish: '00000000-0000-0000-0000-000000000000/00000000-0000-0000-0000-000000000002' # You can also use '<projectName>/<feedName>' instead of the GUIDs
       vstsFeedPackagePublish: mygatsbysite
       packagePublishDescription: 'A test package'
   

This example demonstrated how to use the Pipelines task builder to quickly generate the YAML for the Universal Package task, which can then be placed into your azure-pipelines.yml file. The Universal Package task builder supports all of the advanced configurations that can be created with Universal Package task's arguments.

Note

Publishing a package directly to a view is not supported in Azure Artifacts. You must publish the package to your feed first, then promote it to a view.

Requirements

Requirement	Description
Pipeline types	YAML, Classic build, Classic release
Runs on	Agent, DeploymentGroup
Demands	None
Capabilities	This task does not satisfy any demands for subsequent tasks in the job.
Command restrictions	Any
Settable variables	Any
Agent version	2.144.0 or greater
Task category	Package