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.

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.

teamcity.storage.migration.access.token=aBcEfgHIjkLMnoPQRsTUVwxyz
teamcity.storage.migration.artifact.directories=C:\\ProgramData\\JetBrains\\TeamCity\\system\\artifacts
teamcity.storage.migration.host=http://localhost:8111

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:

teamcity.storage.migration.s3.custom.profile.<FEATURE_ID>=<PROFILE_NAME>

• <FEATURE_ID> is the storage ID from the storage settings page.

• <PROFILE_NAME> is the profile name from the AWS credentials file.

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.

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.

./migrate --project="NetFrameworkProject3"

migrate.bat --project="NetFrameworkProject3"

You can add the --recursive (-r) parameter to specify whether the tool should recursively process all subprojects of the selected project.

tip

If the migration tool cannot access a subproject's storage, it will skip this project. Add the failWhenCannotAccessStorageSettings=true property to the tool's configuration file to force the tool to fail in these scenarios.

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.

./migrate -p "NetFrameworkProject3" --source="PROJECT_EXT_2"

migrate.bat -p "NetFrameworkProject3" --source="PROJECT_EXT_2"

tip

Currently, the tool accepts only Amazon S3 bucket IDs as the "source" parameter values.

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.

./migrate --project="SampleProject" --source="PROJECT_EXT_2" --start-migration --remove-artifacts-in-source

migrate.bat --project="SampleProject" --source="PROJECT_EXT_2" --start-migration --remove-artifacts-in-source

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.s3.threadCount — the number of threads that the tool should use to upload data to S3. The default value is 4.

• 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.

• teamcity.storage.migration.s3.upload.numberOfRetries — the number of attempts the tool makes when uploading data to S3 if it encounters errors. The default value is 5.

• teamcity.storage.migration.s3.upload.retryDelayMs — the initial delay between attempts in milliseconds. The default value is 1000.