Artifacts Migration Tool
The artifacts migration tool is a command-line tool that allows you to transfer build artifacts from one storage to another.
Currently, the tool accepts only Amazon S3 buckets and Azure storages as migration targets. Note that you need to install an unbundled plugin to set up Azure storages: Azure Artifact Storage.
Download the Artifacts Migration Tool
You can download this tool from the Project Settings | Artifacts Storage page.
Note that you need this tool to be on the same machine where the TeamCity server is installed.
Configuration File
Before you can run the artifacts migration tool, you need to specify the following settings in the config/application.properties file.
teamcity.storage.migration.host— the TeamCity server's address (protocol, host, and port).teamcity.storage.migration.artifact.directories— the absolute path to the local TeamCity artifact storage. If your TeamCity server uses multiple directories as artifacts storages, use a semicolon character (;) as a separator.teamcity.storage.migration.access.token— the TeamCity authentication token. Tokens must have permissions sufficient to access artifact storages. Navigate to Your Profile | Access Tokens to create a new token.
The server URL and default artifact storage paths can be found on the Administration | Global Settings page.
The snippet below demonstrates the contents of a sample application.properties file.
Auth Settings for Cloud Storages
AWS S3
To migrate artifacts to or from Amazon S3 buckets, the artifacts migration tool needs to use AWS credentials stored on the server machine. See this documentation article for more information: Set up AWS Credentials and Region for Development.
If a project has multiple S3-compatible storages that need to be migrated and require different credentials, use Custom AWS profiles to provide these credentials. To associate a specific profile in the credentials file with the particular storage, add the following property to the tool's config/application.properties file:
<FEATURE_ID>is the storage ID from the storage settings page.<PROFILE_NAME>is the profile name from the AWS credentials file.
Microsoft Azure
Authentication in Microsoft Azure is enabled by using EnvironmentCredential instances. TeamCity uses authentication with a client secret, which requires the following environment variables to be present on the TeamCity server machine:
AZURE_TENANT_IDAZURE_CLIENT_IDAZURE_CLIENT_SECRET
We expect to support more authentication scenarios (including authentication via Azure CLI commands) in future release cycles.
Target Storage Settings
The migration tool copies or moves artifacts to the currently active storage. Before you run the migration process, go to the Project Settings | Artifacts Storage page of a project whose artifacts you want to migrate, and activate the target storage.
Run the Migration Tool
Open the terminal at the <artifacts_migration_tool>/bin folder and run the "migrate" (Linux, macOS) or "migrate.bat" (Windows) file with the --project (-p) parameter. This parameter accepts external project IDs as values.
You can add the --recursive (-r) parameter to specify whether the tool should recursively process all subprojects of the selected project.
If you need to migrate artifacts from cloud storage rather than a local directory, specify the additional --source (-s) parameter and pass a storage ID as a value.
The first time you run the migration tool in this mode, it detects artifacts that should be copied, saves the migration plan, and asks you for the next step.
Update the migration plan.
Show the migration plan.
Copy artifacts from the source storage to the target storage.
Revert the migration. This option removes copied artifacts from the target storage. You can select this option in case of an incomplete or interrupted migration.
Delete artifacts from the source storage.
Forget the migration plan. Use this option to discard the saved migration plan if you specified incorrect migration parameters.
To migrate artifacts in one go (without the tool asking you for confirmation or input), specify the required migration steps by adding the following commands.
--create-migration-plan— create or update the migration plan.--show-migration-plan— show the migration plan.--start-migration— copy artifacts from the source storage to the target storage.--revert-migration— remove copied artifacts from the target storage in case of an incomplete or interrupted migration.--remove-artifacts-in-source— delete copied artifacts from the source storage. Artifacts that were not copied will not be removed.--reset-migration-plan— discard the current migration plan.
For example, the following command moves artifacts from the given Amazon S3 storage to a currently active storage.
Additional Configuration Properties
You can add the following properties to the configuration file.
teamcity.storage.migration.processing.threadCount— the number of threads that the tool should use for processing. The default value is 4.teamcity.storage.migration.failWhenCannotAccessStorageSettings— controls whether the migration should fail if the tool cannot fetch the storage settings from the TeamCity server. It may happen due to the lack of permissions. The default value is false.teamcity.storage.migration.copying.threadCount— the number of threads that the tool should use to upload data to a cloud storage. The default value is 4.teamcity.storage.migration.upload.numberOfRetries— the number of attempts the tool makes when uploading data to a cloud storage if it encounters errors. The default value is 5.teamcity.storage.migration.upload.retryDelayMs— the initial delay between attempts in milliseconds. The default value is 1000.teamcity.storage.migration.s3.forceVirtualHostAddressing— specifies whether the tool should use the virtual hosted style of S3 URL addresses instead of the deprecated path style. The default value is true.