Skip to main content
Version: Deploy 26.1

Deploy Larger Artifacts > 2 GB

Deploy 26.1 and later supports deploying artifacts larger than 2 GB. Large artifacts are transferred using a streaming approach instead of being fully loaded into memory, which significantly reduces memory pressure during deployment. This topic covers which artifact types are supported, how permissions are handled, storage compatibility, and best practices.

tip

Overall memory usage depends on the Deploy heap size configuration. Ensure the JVM heap is sized appropriately for your environment and workload. For guidance, see Production Environment Installation.

By default, ZIP archives up to 2 GB are processed in memory. To adjust this threshold, see Customizing Large Artifact Deployments.

Artifact Types Supported​

Deploy 26.1 and later extends large-artifact support to all three artifact base types in the Unified Deployment Model:

  • udm.FileArtifact - stored and deployed as a single file.
  • udm.ArchiveArtifact - stored and deployed as a single archive.
  • udm.FolderArtifact - extracted as a directory (folder) on the target during deployment.

During deployment, only udm.FolderArtifact performs extraction of the archive into a directory. udm.FileArtifact and udm.ArchiveArtifact are delivered to the target as-is since no extraction occurs, and no special action is needed for artifacts larger than 2 GB.

Permission Handling​

All deployments work as expected. However, udm.FolderArtifact deployments using ZIP (> 2 GB) or JAR archives have limitations in POSIX permission retention when the streaming code path is used. TAR-based artifacts preserve POSIX permissions regardless of size.

For more technical details, see How Deploy Processes Large Artifacts. To customize executable file detection and permission defaults, see Customizing Large Artifact Deployments.

Artifact Storage​

Deploy uses a stream-based approach to read both internal and external artifacts. File-based artifact access was replaced with streaming from Deploy 9.0 onwards. The availability of large-artifact support varies by storage type.

Internal Storage​

Internal storage uses the filesystem by default, or can be configured to use a database. For HA configurations with external workers or a clustered master setup, Deploy requires either a shared filesystem or database storage.

  • Filesystem (default) - Artifacts are stored directly on the disk with no size limitation. Deployments larger than 2 GB are supported when using filesystem internal storage in both standalone and clustered setups. In a clustered setup, the filesystem must be shared so that both the active and standby Deploy nodes can access it. For more information, see Set up an Active-Hot-standby Cluster.
  • Database - Deploying artifacts larger than 2 GB is currently limited when using database-backed artifact storage.

For more information, see:

External Storage​

External artifacts are referenced by URI and can be downloaded during CI creation or at deployment time. Deploy supports HTTP/HTTPS, Maven, JFrog Artifactory, and custom protocols.

  • HTTP / HTTPS - Deploy streams the artifact directly from the remote URL with no size limitation. Artifacts larger than 2 GB are fully supported.
  • Maven / JFrog Artifactory - When the external artifact storage is Maven or JFrog Artifactory, deployments larger than 2 GB are not supported.

For more information, see:

Limitations

Deploying artifacts larger than 2 GB is currently limited when using database-backed internal artifact storage or Maven / JFrog Artifactory external storage. These limitations will be addressed in coming releases.

Export, Import, and Deployment of Large Artifacts​

Export, import, and deployment of CIs with large artifacts are supported via the UI and XL CLI. However, the Deploy CLI has limitations for creating, importing, exporting, and deploying such CIs.

For more information about artifact types, archive handling, permissions, and deployment strategies, see the following topics.