Task: Package

Description

This task creates deployment packages that contain build outputs and a manifest file. The task copies built artifacts from the build list into a .tar archive package for deployment. It records artifact and source metadata in the embedded Wazi Deploy manifest file.

Note: The Package task requires build maps to be enabled. Build maps are enabled by default in DBB 3.0.4 and later. Build maps can be disabled globally by using the disableBuildMaps variable in the MetadataInit task configuration, but this prevents the Package task from running.

What gets packaged

The Package task packages deployable outputs that are created during the Languages stage of the build. Any deployable build output is a candidate for packaging. An artifact is considered a deployable output when the step (or DD statement) that creates it is marked as an output and assigned a deployType value.

- step: copyJCL
  type: copy
  condition: ${FILE_EXT} == "jcl"
  target: //'${HLQ}.JCL(${MEMBER})'
  copyMode: TEXT
  deployType: JCL

- step: linkEdit
  type: mvs
  pgm: IEWBLINK
  dds:
  - { name: "SYSLIN", dsn: "${HLQ}.OBJ(${ENTRY})", options: "shr" }
  - { name: "SYSLMOD", dsn: "${HLQ}.LOAD(${ENTRY})", options: "shr",
      output: true, deployType: "LOAD", scan: "${scanLoadModule}" }

Usage examples

- lifecycle: pipeline
  cli:
    usage: dbb build pipeline [arguments] [options]
    options:
      - longOption: "release-id"
        hasArg: true
        description: "The release identifier for the package being created. ie: 1.0.0"
      - longOption: "build-id"
        hasArg: true
        description: "The build identifier for the package being created. ie: 20240415.7"
  
  tasks:
    - Start
    - ScannerInit
    - MetadataInit
    - ImpactAnalysis
    - Languages    # Defined in Languages.yaml
    - Package
    - Finish

Task dependency list

The task depends on context variables that are exported by the Start and MetadataInit tasks. Additionally, it must run after the Languages task to ensure all build outputs are available and build map metadata has been refreshed.

• Start
• MetadataInit
• LanguageTask

Actions

• Validates that build maps are not disabled globally (required for packaging).
• Retrieves the build list populated by Language tasks. This list contains all successfully built source files.
• Processes each build map to extract output artifacts and their metadata.
• Copies build outputs (from PDS members or z/OS UNIX files) to a temporary package directory structure.
• Calculates SHA-256 hashes for each packaged artifact.
• Populates SCM information from source repositories that are involved in building the artifacts.
• Records dependency metadata for each artifact based on build map inputs and binary inputs.
• Processes deleted artifacts from deleted build maps (for incremental deployments).
• Generates a Wazi Deploy manifest YAML file (wazideploy_manifest.yml) that contains artifact metadata.
• Creates a .tar archive of the package directory.
• Writes the package to the output directory (defaults to LOGS directory).

Package structure

The Package task creates a structured deployment package with the following directory layout:

<application>-<version>.tar
├── wazideploy_manifest.yml    # Wazi Deploy manifest file
├── bin/                        # PDS-based outputs
│   ├── load/                   # LOAD modules
│   ├── dbrm/                   # Database Request Modules
│   ├── obj/                    # Object decks
│   └── <deployType>/           # Other deploy types
└── uss/                        # z/OS UNIX file outputs
    ├── jcl/                    # JCL files
    └── <deployType>/           # Other deploy types

Each artifact in the package includes:

• The build output file
• Metadata in the manifest (name, type, hash, properties, and dependencies)

Copy mode mappings

The Package task uses DBB CopyMode settings to determine how to copy PDS members to the package directory. Different deploy types require different copy modes to preserve the correct data format.

variables:
  - name: copyModeMappings
    value:
      - deployType: CUSTOM
        copyMode: BINARY
      - deployType: LOAD
        copyMode: LOAD  # Override default

Wazi Deploy manifest

The Package task generates a Wazi Deploy application manifest file (named wazideploy_manifest.yml) at the root of the package. This file conforms to the Wazi Deploy manifest schema.

For complete details on the manifest structure, schema, and examples, see the Wazi Deploy application manifest file documentation.

The manifest contains the following sections:

Excluding deploy types

You can exclude specific deploy types from packaging by using the excludedDeployTypes variable. This is useful when certain outputs are not to be deployed:

variables:
  - name: excludedDeployTypes
    value:
      - OBJ           # Exclude any generated object decks marked as outputs
      - UNIT-TESTCASE # Exclude unit testcase programs marked as outputss

Syntax

- task: Package
  comment: String # Message printed to stdout when the task begins executing.
  condition: Boolean # Boolean expression to optionally execute task. Default is true.
  variables:
    - name: copyModeMappings # List of deploy type to DBB CopyMode mappings
      value: # Default - See copy mode mappings above.
        - deployType: String # Deploy type name (e.g., LOAD, DBRM, COPY)
          copyMode: String # DBB CopyMode: BINARY, LOAD, TEXT, or VB_BINARY
    - name: excludedDeployTypes # List of deploy types to exclude from packaging
      value: [String] # Default is NONE.
    - name: outputDir # Directory where the tar package file is written
      value: String # Default is ${LOGS} directory.

Task variables

variables:
  - name: copyModeMappings
    value:
      - deployType: MYLOAD
        copyMode: LOAD
      - deployType: MYTEXT
        copyMode: TEXT

variables:
  - name: excludedDeployTypes
    value:
      - OBJ
      - EQALANGX

variables:
  - name: outputDir
    value: /u/packages/releases

Build Context (advanced)

In addition to the task variables provided by users in the DBB YAML configuration files, some tasks require inputs and generate outputs to the zBuilder Build Context. The Build Context is a dynamic storage area passed into each task being executed by the zBuilder and is used for task-to-task communication.

Package naming convention

The Package task generates .tar files by using the following naming convention:

<application>-<version>.tar

Where:

• <application> is the application name from the build context
• <version> is:
  • <releaseId>-<buildId> if a release identifier is provided
  • <buildId> if no release identifier is provided

Example: MyApp-1.0.0-20260114.164500.tar

Error handling

The Package task fails in the following cases:

• Build maps are disabled globally (with the MetadataInit disableBuildMaps configuration variable)
• A build map is missing for a file in the build list
• A deploy type has no corresponding copy mode mapping
• An artifact copy operation fails
• Hash calculation fails for an artifact
• The .tar archive creation fails

If no artifact is built or deleted, the task skips package generation and returns with a warning message.