Copy Strategies

In Digital.ai Deploy, a copy strategy controls how file.Folder artifacts are transferred to target hosts using the overthere.Host library. It specifies whether files are packaged as an archive or copied individually, affecting deployment speed and compatibility.

Deploy supports four copy strategies: Tar, ZipUnix, ZipWindows, and OneByOne (default/fallback). The strategy is selected based on your configuration and environment.

Target Host Environment Prerequisite (Deploy 25.3+)

Starting with Deploy 25.3, Deploy no longer checks for tar or unzip at runtime. These tools must be installed on the target host before deployment. If missing, archive-based strategies (Tar, ZipWindows, ZipUnix) will fail.

• Linux: Install tar and unzip.
• Windows: Ensure PowerShell 5.0+ is available with unzip support.

---

OneByOne

Copies each file individually to the target host. This is the default strategy for backward compatibility and acts as a fallback when no other strategy is configured. OneByOne works with any artifact type, but is not recommended if you need to preserve file permissions.

File Permission Handling

Original file permissions are not preserved. On Unix, files use default permissions (rw-r--r--). On Windows, standard ACLs are applied, but POSIX permissions are not supported. Deployments between different operating systems (for example, Linux to Windows) lose POSIX permission information.

Deployment Performance

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

For faster deployments and better file permission handling, use Tar or Zip strategies, which transfer all files as a single archive and extract them on the target host.

---

Tar

Bundles files into a tar archive, transfers, and extracts them on the target host. From Deploy 25.3+, Tar supports options like --strip-components and members for file.Folder, enabling targeted extraction and directory flattening. Use this strategy 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 via SSH. Deployments to localhost or across different operating systems (for example, Unix to Windows) may not retain permissions.

Limitation:

This strategy works only 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 for .zip artifacts and is ideal for Windows hosts with PowerShell 5.0 or later.

File Permission Handling

POSIX file permissions are not retained. Standard Windows ACLs are applied during extraction. For older Windows versions (earlier than Server 2016), 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 via SSH. Deployments to localhost or across different operating systems (for example, 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 provides several configuration methods (since Deploy 25.3) to optimize file.Folder deployments. The following section explains each option in order of precedence, from highest to lowest, for determining which copy strategy 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 Strategy section. Use this option 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 off by default for compatibility, but can be enabled in deploy-task.yaml:

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

When autodetect is set to true, Digital.ai Deploy selects the 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 as 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.
• 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 (e.g., tar command unavailable), the system falls back to OneByOne copy strategy.

---

Recommended Configuration

For best performance and minimal configuration overhead 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 to the guidance above for which strategy fits your artifact type and host environment.

Use Autodetect

The autodetect option selects the copy strategy based on the artifact type. Each TAR or ZIP is transferred as a single archive and extracted on the target. A fixed host-level strategy forces all artifacts to use the same method, which can slow deployments or cause permission issues for minority artifact types in mixed TAR/ZIP deployments (for example, when most artifacts are TAR but some are ZIP).

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 (for example, 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)