Tracking Package Deployments
  • 30 May 2024
  • 3 Minutes to read
  • Dark
    Light
  • PDF

Tracking Package Deployments

  • Dark
    Light
  • PDF

Article summary

The Package Deployments feature records package deployment information (such as the target and user) from tools such as BuildMaster and OctopusDeploy, and provides you with a package-centric view of deployments.

This feature allows you to determine exactly which package versions were deployed, when, by whom, with which tool, and so on. This simplifies the auditing process by keeping clear records directly in ProGet. It also helps you quickly find vulnerable servers when a known vulnerability is identified: The feature in ProGet shows all servers running a particular package so you can quickly make updates.

There are no restrictions on this feature in the Free edition of ProGet. Package deployment records can be found, once configured, in the "History" tab on the Package Overview page.

Custom Records

Consumers of any package type may customize the Feed API GET request with the following HTTP headers:

  • X-ProGet-Deployment-Application - (Required) the application or tool doing the deployment e.g., NuGet, BuildMaster, Some Custom Tool
  • X-ProGet-Deployment-Description - (Required) brief summary of deployment
  • X-ProGet-Deployment-Target - (Required) string that identifies where the package was installed, typically the server name
  • X-ProGet-Deployment-Url - (Optional) URL that links to more information about the deployment
  • X-ProGet-Deployment-UserName - (Optional) name of the user performing the deployment, defaults to authenticated user
  • X-ProGet-Deployment-Date - (Optional) ISO 8601 UTC date of deployment, or current date if not supplied

Package Deployment API

If you are using a tool other than BuildMaster or OctopusDeploy to deploy your packages, you can use the Package Deployment API to extend this feature in ProGet and add custom package deployment records to ProGet from other tools.

Authentication

If you disallow anonymous access to your feed, you will need to create an API Key that grants access to the Package Deployment API. This key requires the Feeds_DownloadPackage privilage.

To specify an API Key, use the request header (X-ApiKey), querystring (key), or api:«api-key» as the username. See API Key Usage to learn more.

🚀 Quick Example: Authenticating with PowerShell

For example, to authenticate with the API key abc12345 to the query packages endpoint, you could specify the API key as follows:

$headers = @{
    'X-ApiKey': 'abc12345'
}
Invoke-RestMethod -Method Post -Uri 'https://{proget-server}/api/package-deployment/' -Body 'FeedName=DefaultNuGet&Application=ProfitCalc&Description=Deployed by Custom Release Server&Target=localhost&PackageName=Newtonsoft.Json&Version=12.0.3' -Headers $headers

PackageDeployment Object Attributes

PackageDeployment is a JSON object that corresponds to the fields on a Package Deployment Record. It's used as input data for the Package Deployment API endpoint as a JSON-formatted object.

PropertyDetails
Application(Required) string - the application or tool doing the deployment (e.g., NuGet, BuildMaster, Some Custom Tool)
Description(Required) string - brief summary of deployment
Target(Required) string - identifies where the package was installed, typically the server name
FeedName(Required) string - the name of the package feed
PackageName(Required) string - the name or ID of your package
Version(Required) string - the version of the package deployed
GroupName(Optional) string - the group, scope, or namespace of the package (this varies based on feed type)
UserName(Optional) string - name of the user performing the deployment, defaults to authenticated user
Url(Optional) string - URL that links to more information about the deployment
Date(Optional) ISO 8601 UTC date - date of deployment, or current date if not supplied

Package Deployment Endpoint

HTTP Request Specification

To set a package's status, simply POST to the URL with an appropriate API Key and a PackageDeployment object as the request body.

POST /api/package-deployment/

HTTP Response Specification

ResponseDetails
200 (Success)indicates the package deployment record was added
400 (Invalid Input)indicates invalid or missing properties on the input; the body will provide some details as text
403 (Unauthorized API Key)indicates a missing, unknown, or unauthorized API Key; the package status will not be updated
500 (Server Error)indicates an unexpected error; the body will contain the message

Sample Usage Scripts

Add Deployment Record (Powershell)

This script will add a deployment record to the application ProfitCalc, using application/json as the Content-Type.

Invoke-RestMethod -Method Post -Uri 'https://{proget-server}/api/package-deployment/' -Body 'FeedName=DefaultNuGet&Application=ProfitCalc&Description=Deployed by Custom Release Server&Target=localhost&PackageName=Newtonsoft.Json&Version=12.0.3'

Add Deployment Record (Powershell)

This script will add a deployment record to the application ProfitCalc, using application/x-www-form-urlencoded as the Content-Type.

$data = @{
    FeedName='DefaultNuGet'
    Application='ProfitCalc'
    Description='Deployed by Custom Release Server'
    Target='localhost'
    PackageName='Newtonsoft.Json'
    Version='12.0.3'
}
$headers = @{
    'content-type' = 'application/json'
}
Invoke-RestMethod -Method Post -Uri 'https://{proget-server}/api/package-deployment/' -Body ($data | ConvertTo-JSON) -Headers $headers

Was this article helpful?