Artifacts in Azure Pipelines

Note

In Microsoft Team Foundation Server (TFS) 2018 and previous versions, build and release pipelines are called definitions, runs are called builds, service connections are called service endpoints, stages are called environments, and jobs are called phases.

Note

We recommend upgrading from build artifacts (PublishBuildArtifacts@1 and DownloadBuildArtifacts@0) to pipeline artifacts (PublishPipelineArtifact@1 and DownloadPipelineArtifact@2) for faster output storage speeds.

Artifacts are the files that you want your build to produce. Artifacts can be anything that your team needs to test or deploy your app.

How do I publish artifacts?

Artifacts can be published at any stage of pipeline. You can use two methods for configuring what to publish as an artifact and when to publish it: alongside your code with YAML, or in the Azure Pipelines UI with the classic editor.

Example: Publish a text file as an artifact

- powershell: gci env:* | sort-object name | Format-Table -AutoSize | Out-File $env:BUILD_ARTIFACTSTAGINGDIRECTORY/environment-variables.txt

- task: PublishBuildArtifacts@1
  inputs:
    pathToPublish: '$(Build.ArtifactStagingDirectory)'
    artifactName: drop
  • pathToPublish: the folder or file path to publish. It can be an absolute or a relative path, and wildcards are not supported.
  • artifactName: the name of the artifact that you want to create.

Note

You cannot use Bin, App_Data and other folder names reserved by IIS as an artifact name because this content is not served in response to Web requests. Please see ASP.NET Web Project Folder Structure for more details.

YAML is not supported in TFS.

Example: Publish two sets of artifacts

- powershell: gci env:* | sort-object name | Format-Table -AutoSize | Out-File $env:BUILD_ARTIFACTSTAGINGDIRECTORY/environment-variables.txt

- task: PublishBuildArtifacts@1
  inputs:
    pathToPublish: '$(Build.ArtifactStagingDirectory)'
    artifactName: drop1
- task: PublishBuildArtifacts@1
  inputs:
    pathToPublish: '$(Build.ArtifactStagingDirectory)'
    artifactName: drop2
  • pathToPublish: the folder or file path to publish. It can be an absolute or a relative path, and wildcards are not supported.
  • artifactName: the name of the artifact that you want to create.

Note

You cannot use Bin, App_Data and other folder names reserved by IIS as an artifact name because this content is not served in response to Web requests. Please see ASP.NET Web Project Folder Structure for more details.

YAML is not supported in TFS.

Example: Assemble C++ artifacts into one location and publish as an artifact

- powershell: gci env:* | sort-object name | Format-Table -AutoSize | Out-File $env:BUILD_ARTIFACTSTAGINGDIRECTORY/environment-variables.txt

- task: CopyFiles@2
  inputs:
    sourceFolder: '$(Build.SourcesDirectory)'
    contents: '**/$(BuildConfiguration)/**/?(*.exe|*.dll|*.pdb)'
    targetFolder: '$(Build.ArtifactStagingDirectory)'
- task: PublishBuildArtifacts@1
  inputs:
    pathToPublish: '$(Build.ArtifactStagingDirectory)'
    artifactName: drop
  • sourceFolder: the folder that contains the files you want to copy. If you leave this value empty, copying will be done from the root folder of your repo ($(Build.SourcesDirectory)).
  • contents: location(s) of the file(s) that will be copied to the destination folder.
  • targetFolder: destination folder.
  • pathToPublish: the folder or file path to publish. It can be an absolute or a relative path, and wildcards are not supported.
  • artifactName: the name of the artifact that you want to create.

Note

You cannot use Bin, App_Data and other folder names reserved by IIS as an artifact name because this content is not served in response to Web requests. Please see ASP.NET Web Project Folder Structure for more details.

YAML is not supported in TFS.

How do I consume artifacts?

You can consume your artifacts in different ways: you can use it in your release pipeline, pass it between your pipeline jobs, download it directly from your pipeline and even download it from feeds and upstream sources.

Consume artifacts in release pipelines

You can download artifacts produced by either a build pipeline (created in a classic editor) or a YAML pipeline (created through a YAML file) in a release pipeline and deploy them to the target of your choice.

Consume an artifact in the next job of your pipeline

You can consume an artifact produced by one job in a subsequent job of the pipeline, even when that job is in a different stage (YAML pipelines). This can be useful to test your artifact.

Download to debug

You can download an artifact directly from a pipeline for use in debugging.

- powershell: gci env:* | sort-object name | Format-Table -AutoSize | Out-File $env:BUILD_ARTIFACTSTAGINGDIRECTORY/environment-variables.txt

- task: DownloadBuildArtifacts@0
  inputs:
    buildType: 'current'
    downloadType: 'single'
    artifactName: 'drop'
    downloadPath: '$(System.ArtifactsDirectory)'
  • buildType: specify which build artifacts will be downloaded: current (the default value) or from a specific build.
  • downloadType: choose whether to download a single artifact or all artifacts of a specific build.
  • artifactName: the name of the artifact that will be downloaded.
  • downloadPath: path on the agent machine where the artifacts will be downloaded.

YAML is not supported in TFS.

Note

In case you are using a deployment task, you can then reference your build artifacts by using $(Agent.BuildDirectory) variable. See Agent variables for more information on how to use predefined variables.

Tips

  • Artifact publish location argument: Azure Pipelines/TFS (TFS 2018 RTM and older: Artifact type: Server) is the best and simplest choice in most cases. This choice causes the artifacts to be stored in Azure Pipelines or TFS. But if you're using a private Windows agent, you've got the option to drop to a UNC file share.

  • Use forward slashes in file path arguments so that they work for all agents. Backslashes don't work for macOS and Linux agents.

  • Build artifacts are stored on a Windows filesystem, which causes all UNIX permissions to be lost, including the execution bit. You might need to restore the correct UNIX permissions after downloading your artifacts from Azure Pipelines or TFS.

  • On Azure Pipelines and some versions of TFS, two different variables point to the staging directory: Build.ArtifactStagingDirectory and Build.StagingDirectory. These are interchangeable.

  • The directory referenced by Build.ArtifactStagingDirectory is cleaned up after each build.

  • Deleting a build that published Artifacts to a file share will result in the deletion of all Artifacts in that UNC path.

  • You can get build artifacts from the REST API.

Use these tasks to publish artifacts:

Explore, download, and deploy your artifacts

When the build is done, if you watched it run, select the Summary tab and see your artifact in the Build artifacts published section.

Published build artifact

When the build is done, if you watched it run, select the name of the completed build and then select the Artifacts tab to see your artifact.

Published build artifact TFS

From here, you can explore or download the artifacts.

You can also use Azure Pipelines to deploy your app by using the artifacts that you've published. See Artifacts in Azure Pipelines releases.

Publish from TFS to a UNC file share

If you're using a private Windows agent, you can set the artifact publish location option (TFS 2018 RTM and older: artifact type) to publish your files to a UNC file share.

Note

Use a Windows build agent. This option doesn't work for macOS and Linux agents.

Choose file share to copy the artifact to a file share. Common reasons to do this:

  • The size of your drop is large and consumes too much time and bandwidth to copy.

  • You need to run some custom scripts or other tools against the artifact.

If you use a file share, specify the UNC file path to the folder. You can control how the folder is created for each build by using variables. For example: \\my\share\$(Build.DefinitionName)\$(Build.BuildNumber).

Publish artifacts from TFS 2015 RTM

If you're using TFS 2015 RTM, the steps in the preceding examples are not available. Instead, you copy and publish your artifacts by using a single task: Build: Publish Build Artifacts.

Next steps