Configure upstream behavior

TFS 2017

Upstream sources enables developers to use a single feed to publish and consume packages from Artifact feeds and public registries such as NuGet.org or npmjs.com. To set up upstream sources for your feed, check the box to include packages from common public sources. This will allow your feed to use packages from the common public registries.

Previously, Artifact feeds combined a list of available package versions from the feed and all the upstream sources.

Upstream behavior is a feature that enables developers to choose if they want to consume externally-sourced package versions. Upstream behavior dictates which packages will be made available from the public registries for individual packages.

When the upstream behavior is enabled, when a package is published to your Azure Artifacts feed, any version from the public registry will be blocked and not made available for download.

This approach provides another layer of security by blocking the exposure to malicious packages that may infiltrate the public registries.

Users will still be able to toggle off the upstream behavior setting and consume packages from the public registries if they choose to do so.

Applicable scenarios

The next section shows a few common scenarios where the upstream behavior is triggered to block externally sourced package versions along with few other cases where no blockage to the public packages is needed.

Public versions will be blocked

• Private package version made public: in this scenario, a team has a private package that was made public. The upstream behavior in this case will be triggered to block any new public versions (untrusted packages).

  

• Having both private and public packages: in this scenario, if a team already has both private and public packages, enabling the upstream behavior will result in blocking any new package versions from the public registry.

  

Public versions will not be blocked

• All packages are private: if all existing packages are private and the team won't be consuming any public packages, the new upstream behavior will have no effect on the team's workflow in this scenario.

  

• All packages are public: if all the packages consumed are public, whether it's from the public registry or any other open-source repositories, the new upstream behavior will have no effect on the team's workflow in this scenario.

  

• Public package made private: if a public package is switched to a private package, the new upstream behavior will have no effect on the team's workflow in this scenario.

  

Allow external versions

To configure the new upstream behavior, select a package from within your feed then select the toggle button to Allow external sourced versions.

Allow external versions using the REST API

Aside from using the feed's user interface, you can also configure the upstream behavior using the Azure DevOps Services REST API. Select the appropriate tab and find the links to the REST API docs.

Allow external versions with PowerShell

To successfully execute the next steps in this section, you will need to create a personal access token with packaging Read, write, & manage permissions. See Use personal access tokens to learn how to create your personal access token.

In an elevated PowerShell command prompt window, run the following command to create an environment variable for your personal access token.

$env:PATVAR = "YOUR_PAT_GOES_HERE"

The following commands will convert your personal access token to baser64 encoded string and construct the HTTP request header.

$token = [Convert]::ToBase64String(([Text.Encoding]::ASCII.GetBytes("username:$env:PatVar")))
$headers = @{
    Authorization = "Basic $token"
}

Invoking the REST method requires an endpoint url. Enter your OrganizationName, ProjectName, FeedName, Protocol, and your PackageName to construct the $Url variable. (Project-scoped feed example: /pkgs.dev.azure.com/MyOrg/MyProject/_apis/packaging/feeds/MyFeed/nuget/packages/Myapp1.0.nupkg/upstreaming?api-version=6.1-preview.1)

• Project-scoped feed:

$url = "https://pkgs.dev.azure.com/{OrganizationName}/{ProjectName}/_apis/packaging/feeds/{FeedName}/{Protocol}/packages/{PackageName}/upstreaming?api-version=6.1-preview.1"

• Organization-scoped feed:

$url = "https://pkgs.dev.azure.com/{OrganizationName}/_apis/packaging/feeds/{FeedName}/{Protocol}/packages/{PackageName}/upstreaming?api-version=6.1-preview.1"

Now that we have both the header and the endpoint URL set up, we can start sending HTTP requests to get, set, and clear upstreaming for any specific package.

Get upstreaming behavior

Run the following command to retrieve the upstream behavior state of your package. $url and $headers are the same variables we used in the previous section.

Invoke-RestMethod -Uri $url -Headers $headers

Set upstreaming behavior

Run the following commands to allow externally sourced versions for your package. This will set versionsFromExternalUpstreams to AllowExternalVersions, and will use the $url and $headers variables to query the REST API.

$body = '{"versionsFromExternalUpstreams": "AllowExternalVersions"}'

Invoke-RestMethod -Uri $url -Headers $headers -Body $body -Method Patch -ContentType "application/json"

Clear upstreaming behavior

To clear the upstream behavior for your package, run the following commands to set versionsFromExternalUpstreams to Auto and query the REST API.

$body = '{"versionsFromExternalUpstreams": "Auto"}'

Invoke-RestMethod -Uri $url -Headers $headers -Body $body -Method Patch -ContentType "application/json"

Related articles

• Understand upstream sources
• Set up upstream sources
• Manage dependencies with upstream sources
• Feeds permissions
• Best practices