Artifact Dependencies

Configuring Artifact Dependencies Using Web UI

To add an artifact dependency to a build configuration:

1. When editing a build configuration, open the Dependencies page.

   

2. Click Add new artifact dependency and specify the following settings:

   

   • Depend on — the build configuration for the current build configuration to depend on.

   • Get artifacts from — the type of build whose artifacts are to be taken:

     • Latest successful build — artifacts will be taken from the successful dependency build with the most recent revision (the latest change ID)

     • Latest pinned build — artifacts will be taken from the pinned dependency build with the most recent revision (the latest change ID)

     • Latest finished build: if a snapshot dependency is also configured in a build configuration, artifacts will be taken from the build with the same sources as the current build

     • Build from the same chain — this option is useful when you have a snapshot dependency and want to obtain artifacts from a build with the same sources

     • Build with specified build number

     • Latest finished build with specified tag

   • Build number — the exact build number of the artifact. This field is available if you have selected build with specific build number in the_ Get artifacts from list.

   • Build tag — the tag of the build whose artifacts are to be used. When resolving the dependency, TeamCity will look for the last successful build with the given tag and use its artifacts. This field appears if you have selected last finished build with specified tag in the Get artifacts from list.

   • Build branch filter — allows setting a branch filter to limit source builds only to those in the matching branches. If not specified, the default branch is used. This field appears if the dependency has a branch specified in the VCS root settings.

   • Artifacts Rules — string expressions that specify which files and folders should be downloaded, and where they should be stored. See this section for more information: Artifacts Rules.

   • Clean destination paths before downloading artifacts — check this option to delete the content of the destination directories before copying artifacts. It will be applied to all inclusive rules.

3. Click Save to add your new dependency.

At any point you can launch a build with custom artifact dependencies.

Artifacts Rules

An artifact rule specifies which artifacts of the source build should be downloaded and where on the agent storage they should be stored.

Each individual artifact rule should start from a new line and have the following syntax:

The order of a rules is irrelevant. For each artifact the most specific rule (the one with the longest prefix before the first wildcard symbol) is applied.

Examples

Download all files from the target directory

To copy all files of from the target a/b directory of the source build to the lib directory of a dependent build, add the a/b/**=>lib rule. Copied files preserve their source hierarchy. For example, the a/b/c/file.txt file hosted in a sub-directory will be placed into the lib/c/file.txt folder.

Download all files that match the pattern

Wildcards allow you to specify patterns and that match multiple files as once. For example, the **/*.txt=>lib rule downloads all text files to the agent's lib directory.

Note that rules preserve the original directories structure. For example, the a/b/c/file.txt file will be stored as lib/a/b/c/file.txt.

Extract files from an archive

The Archive Path portion of an artifact rule allows you to specify which files from the target archive the dependent build should download.

• The a.zip!**=>destination rule unpacks the entire archive to the destination library. The archive is unpacked as is, with the inner hierarchy of subfolders preserved.

• The release-*.zip!*.dll=>dlls rule extracts *.dll libraries from all archives matching the release-*.zip pattern, and saves these libraries to the dlls directory.

• The a.zip!a/b/c/**/*.dll=>dlls rule extracts all .dll files from a/b/c and its subdirectories into the dlls directory. Files matching this rule will be stored without the a/b/c path.

Exclude irrelevant files

Start an artifact rule with the -: prefix to tell TeamCity a file or files that matches this pattern should not be downloaded by the dependent build.

• Two following rules result in downloading all text files from all directories, apart from the exclude.txt file located in the bad directory. Downloaded files are saved to the texts folder.

  **/*.txt=>texts -:bad/exclude.txt

• The following set of rules finds all archives that start with release, unpacks its .dll libraries, and saves them to the dlls directory. The Bad.dll file from the release-0.0.1.zip archive is skipped.

  +:release-*.zip!**/*.dll=>dlls -:release-0.0.1.zip!Bad.dll

• The combination below results in dowloading all artifacts to the target directory. The dependent build will completely ignore the excl directory except for the excl/must_have.txt file.

  **/*.*=>target -:excl/**/*.* +:excl/must_have.txt=>target

Download hidden artifacts

The artifacts placed under the .teamcity directory are considered hidden. These artifacts are ignored by wildcards by default.
If you want to include files from the .teamcity directory for any purpose, be sure to add the artifact path starting with .teamcity explicitly, for example:

• .teamcity/properties/*.properties

• .teamcity/*.*

Optional dependency

The following Kotlin DSL code illustrates a configuration that produces the output.txt artifact file.

import jetbrains.buildServer.configs.kotlin.* import jetbrains.buildServer.configs.kotlin.buildSteps.script object ConfigA : BuildType({ name = "ConfigA" artifactRules = "+:output.txt" steps { script { id = "simpleRunner" scriptContent = """ touch output.txt echo "Config A running..." > output.txt """.trimIndent() } } })

The dependent build configuration uses this output.txt file in its own script. However, the if ... else statement of the script allows for an alternative course of actions in case the target file is missing.

import jetbrains.buildServer.configs.kotlin.* import jetbrains.buildServer.configs.kotlin.buildSteps.script object ConfigB : BuildType({ name = "ConfigB" vcs { cleanCheckout = true } steps { script { id = "simpleRunner" scriptContent = """ FILE=output.txt if [ ! -f ${'$'}FILE ] then echo "No source file exists" else cat ${'$'}FILE fi """.trimIndent() } } dependencies { dependency(ConfigA) { snapshot { reuseBuilds = ReuseBuilds.NO } artifacts { artifactRules = "?:output.txt" } } } })

The ?:output.txt dependency ensures the dependent build can start even if the target file was not found. If this happens, the build log will include a corresponding warning.

Downloading Artifacts to Agent Home Directory

By default, artifacts can be dowloaded only to the agent work directory, downloading to the agent home directory is prohibited. To override the defaults, set custom rules to download artifacts by specifying the comma-separated paths in the buildAgent.properties: teamcity.artifactDependenciesResolution.bannedList and teamcity.artifactDependenciesResolution.allowedList. Adding a path to the banned list forbids artifacts download to this directory unless it is present in the allowed list.

Configuring Artifact Dependencies Using Ant Build Script

This section describes how to download TeamCity build artifacts inside the build script. These instructions can also be used to download artifacts from outside of TeamCity.

To handle artifact dependencies between builds, this solution is more complicated than configuring dependencies in the TeamCity UI but allows for greater flexibility. For example, managing dependencies this way will allow you to start a personal build and verify that your build is still compatible with dependencies.

To configure dependencies via Ant build script:

1. Download Ivy.

2. Add Ivy to the classpath of your build.

3. Create the ivyconf.xml file that contains some meta information about TeamCity repository. This file is to have the following content:

4. Replace YOUR_TEAMCITY_HOST_NAME with the host name of your TeamCity server.

5. Place ivyconf.xml in the directory where your build.xml will be running.

6. In the same directory create the ivy.xml file defining which artifacts to download and where to put them, for example:

where:

• YOUR_ORGANIZATION replace with the name of your organization.

• YOUR_MODULE replace with the name of your project or module where artifacts will be used.

• BUILD_TYPE_EXT_ID replace with the external ID of the build configuration whose artifacts are downloaded.

• BUILD_REVISION can be either a build number or one of the following strings: * latest.lastFinished

  • latest.lastSuccessful

  • latest.lastPinned

• TAG_NAME.tcbuildtag - last build tagged with the TAG_NAME tag

• ARTIFACT_FILE_NAME_WITHOUT_EXTENSION filename or regular expression of the artifact without the extension part.

• ARTIFACT_FILE_NAME_EXTENSION the extension part of the artifact filename.

7. Modify your build.xml file and add tasks for downloading artifacts, for example (applicable for Ant 1.6 and later):

Artifacts repository is protected by a basic authentication. To access the artifacts, you need to provide credentials to the <ivy:configure/> task. For example:

where TEAMCITY_HOST is hostname or IP address of your TeamCity server (without port and servlet context).
As USER_ID/PASSWORD you can use either username/password of a regular TeamCity user (the user should have corresponding permissions to access artifacts of the source build configuration) or system properties teamcity.auth.userId/teamcity.auth.password.

Build-level authentication

The system properties teamcity.auth.userId and teamcity.auth.password store automatically generated build-unique values which can be used to authenticate on TeamCity server. The values are valid only during the time the build is running. This generated user has limited permissions which allow build-related operations. The primary intent for the user is to use the authentication to download artifacts from other TeamCity builds within the build script.

Using the properties is preferable to using real user credentials since it allows the server to track the artifacts downloaded by your build. If the artifacts were downloaded by the build configuration artifact dependencies or using the supplied properties, the specific artifacts used by the build will be displayed at the Dependencies tab on the Build Results page. In addition, the builds which were used to get the artifacts from, can be configured to have different clean-up logic.