Copy Strategies

In Digital.ai Deploy, a copy strategy is the mechanism used to transfer file.Folder artifacts to target hosts using the overthere.Host library.

A copy strategy defines how files are packaged, transferred, and extracted on the target system for example, whether they are bundled into an archive and moved in a single operation or copied individually. The selected strategy determines deployment performance and cross-platform compatibility.

Deploy supports the following copy strategies: Tar, ZipUnix, ZipWindows, and OneByOne (default, fallback). Strategies are applied based on the chosen configuration.

Target Host Environment Prerequisite (From Deploy 25.3+)

As part of performance improvements in Deploy 25.3, the system no longer verifies the presence of tar or unzip on the target host at runtime. These commands must be installed in advance. If they are missing, any archive-based copy strategy (Tar, ZipWindows, ZipUnix) will fail.

• Linux: Ensure both tar and unzip are installed.
• Windows: Ensure PowerShell 5.0 or later is available with unzip support.

---

OneByOne

Copies each file individually to the target host. This is the default for backward compatibility and is used as a fallback when no other strategy is configured. OneByOne works with any artifact type, but it's not recommended when your deployment needs to preserve file permissions.

File permission handling:
This strategy does not preserve original file permissions. On Unix systems, files are deployed with default permissions (rw-r--r--). On Windows, standard ACLs are used, but POSIX permissions are not supported. If you're deploying between different operating systems (for example, Linux to Windows), all POSIX permission information will be lost.

Deployment Performance

The OneByOne strategy transfers files individually, which can result in significantly slower deployments especially for large folders or many small files due to the high number of transfer operations required. This approach is generally less efficient and slower compared to archive-based strategies.

For faster deployments and better handling of file permissions, it is recommended to use Tar or Zip strategies, which transfer all files as a single archive and then extract them on the target host.

---

Tar

Bundles files into a tar archive, transfers, and extracts in place. From Deploy 25.3+, Tar supports advanced options like --strip-components and members for file.Folder, enabling targeted extraction and flattening directory structures. Use for .tar, .tar.gz, and .tar.bz2 artifacts on Unix/Linux systems over SSH, especially when you need to preserve file permissions.

File permission handling:
Original file permissions are preserved when deploying to Unix/Linux using SSH. Deployments to localhost or between different operating systems (Unix to Windows) may not retain permissions.

Limitation:

This strategy only works over SSH connections.

---

ZipWindows

Bundles files into a ZIP archive, transfers, and extracts them using the PowerShell ExtractArchive command on Windows targets. This strategy is designed for .zip artifacts and is ideal when deploying to Windows hosts with PowerShell 5.0 or later.

File permission handling:
This strategy does not retain POSIX file permissions. Standard Windows ACLs are applied during extraction. If you are deploying on older versions of Windows (earlier than Server 2016), you may need to upgrade PowerShell to meet requirements.

Limitation:

Requires PowerShell 5.0 or later with unzip support on the target Windows host.

---

ZipUnix

Bundles files into a ZIP archive, transfers, and extracts them using the unzip command on Unix hosts. Use this strategy for .zip artifacts when deploying to Unix/Linux targets over SSH, especially if you need to preserve file permissions.

File permission handling:
Original file permissions are preserved when deploying to Unix/Linux systems using SSH. Deployments to localhost or across different operating systems (such as Linux to Windows) will not retain POSIX permissions.

Limitation:

This strategy works only with SSH connections to Unix/Linux hosts and cannot retain permissions during cross-platform deployments.

---

How to Configure

Deploy 25.3 offers several configuration methods to optimize file.Folder deployments. The following section explain each option in order of precedence, from highest to lowest, in determining which copy strategy configuration is applied.

Configuration	Precedence	Behavior	Possible Values	Deploy Restart Required	Applicable For Version
Infrastructure CI details	1	If an Infrastructure CI has a copy strategy defined, this setting applies first.	Configurable per Infrastructure CI: Tar, ZipWindows, ZipUnix, OneByOne	No	All versions
Autodetect	2	Applies when autodetect: true on deploy-task.yaml and Infrastructure CI has no copy strategy defined.	true, false (default, for backward compatibility)	Yes (on modification)	All versions (behavior updated in 25.3)
Global configuration	3	Applies if Infrastructure copy strategy is not defined and autodetect: false.	Tar, Zip, OneByOne	No	25.3+
OneByOne (default and fallback)	4	Final fallback when no other setting is defined.	OneByOne copy strategy	No	All versions

1. Configure at Infrastructure Level

On any overthere.Host CI except localhost, select a Copy Strategy in the Artifact Copy Startegy section. This is applicable in environments where you want to enforce a consistent strategy across specific hosts.

2. Enable Autodetect (Recommended)

From version 25.3, the copy strategy for a file.Folder artifact can be automatically determined based on the uploaded source artifact type, rather than the target host’s extraction capabilities. This behavior is turned off by default to make it compatible with older versions, but it can be enabled by setting the properties in deploy-task.yaml as follows:

deploy.task:
  artifact-copy-strategy:
    autodetect: true

When autodetect is set to true, Digital.ai Deploy selects the appropriate extraction tool based on the artifact’s extension (TAR, ZIP, etc.), optimizing deployments without requiring host-level configuration.

tip

For mixed artifact deployments, enable autodetect and remove infrastructure-level copy strategy settings for optimal performance.

3. Create a Global Default Copy Strategy

You can define a global default copy strategy using the configuration item defaultCopyStrategy. This strategy is applied when neither autodetect nor infrastructure-level settings are used.

This option is useful when you need a global fallback for all file.Folder deployments.
It works similarly to default CI naming conventions such as defaultSmtpServer, defaultNamedCredential, and defaultProxyServer.

For more information, see Default names for CIs in Deploy

• The new CI is called Configuration/defaultCopyStrategy and is referenced by file.Folder.
• You can create this configuration under Configuration > New > file > FileCopyStrategy.

note

The name of this configuration item must be exactly defaultCopyStrategy, and the type must be file.FileCopyStrategy. When named this way, the configuration is automatically bound to file.Folder as the default and is mapped in file.folder.defaultCopyStrategy.

How Global Default is Applied

• New folder artifacts: If a global default is set, it is automatically applied to any newly created CI of file.Folder.
• Existing folder artifacts: Not automatically applied to CIs created before the global configuration. Update their defaultCopyStrategy field manually to use the global setting.
• Fallback behavior: If the selected strategy cannot be applied (for example, tar command unavailable), the system falls back to OneByOne copy strategy.

---

Recommended Configuration

For best performance and minimal configuration overhead starting with Deploy 25.3+:

1. Enable autodetect (autodetect: true) so Deploy selects the optimal copy strategy per artifact.
2. Remove infrastructure (host)–level copy strategy settings unless a specific host must enforce a fixed strategy (for example, policy or tooling limitation).
3. Use the global default (defaultCopyStrategy) only as a fallback for file.Folder deployables. It applies at the folder level when no infrastructure-level setting or autodetect configuration is present.
4. Keep OneByOne only as the implicit fallback do not set it explicitly except when troubleshooting strategy failures.

If you must set a strategy manually, refer above for guidance on which strategy fits your artifact type and host environment.

Use Autodetect

Autodetect configuration option selects the copy strategy based on the artifact type. Each TAR or ZIP is transferred once as an archive and extracted on the target. In contrast, a fixed host-level strategy forces all artifacts to use the same method, which can slow deployments or cause permission issues for the minority type in mixed TAR/ZIP deployments.

Use a Global Default

Set defaultCopyStrategy in these scenarios:

• Initial rollout: To enforce a consistent baseline strategy.
• Environment validation: Confirm that tar, unzip, and PowerShell are available on target hosts before enabling autodetect.
• Multi-team environments: Provide a safe interim baseline for multiple teams.

After validation, remove the global default and rely on autodetect.

Example Use Case

When deployments contain mixed artifact types — 80% TAR / 20% ZIP files.

Scenario	Copy Strategy Defined in Infrastructure CI	Autodetect	Result	Performance
1	Tar	False	TAR files deployed using Tar copy strategy (optimized). ZIP files fallback to OneByOne copy strategy.	Partial (~80% optimized)
2	None	True	TAR files deployed using Tar copy strategy (optimized). ZIP files deployed using ZipUnix or ZipWindows copy strategy.	Full (100% optimized)