Introduction

IPM’s --summary-file parameter creates JSON reports that document what each operation did. These files record which files were processed, what was excluded, and basic operation metadata. They’re useful for tracking changes and understanding what happened during package operations.

Available for These Commands

The --summary-file parameter works with:

  • ipm build - Records what files were included and excluded during build
  • ipm export - Documents package export operations
  • ipm publish - Logs package publication details

Build Operation Summaries

When you use --summary-file with ipm build, it creates a JSON file documenting:

  • Files included: Complete list with SHA-256 hashes
  • Files excluded: Everything that was skipped during build
  • Basic metadata: Timestamp, source/destination paths, file counts

Example Build Summary 

{
  "timeStamp": "2025-09-12T04:53:51.669993+00:00",
  "action": "Build",
  "sourceFolder": "/source/path/my-package/",
  "destinationFolder": "/build/output/path",
  "totalFiles": 22,
  "files": [
    {
      "path": "main.tf",
      "hash": "SHA256:11c0e73332a574b5cc312076a98b0b8ccba7e6d75e7816987322b0050bd6ca2f"
    },
    {
      "path": "README.md",
      "hash": "SHA256:47ec043a6a898afc2a5a19d8e93fa34283b49c0134f6188ddda6567c6a411024"
    }
  ],
  "skippedFiles": [
    "ipmhub.manifest.json",
    ".terraform.lock.hcl",
    "packages/network-networksecuritygroup/main.tf",
    "packages/network-routetable/main.tf",
    "packages/network-virtualnetwork/main.tf"
  ]
}

Understanding Skipped Files

The skippedFiles array shows everything that was excluded during the build:

  • Package dependencies: Nested packages/* directories
  • Build artifacts: .terraform.lock.hcl, compiled files
  • System files: .DS_Store, temporary files
  • Version control: .git directories

This exclusion tracking helps you understand exactly what goes into your packages.

Using Build Summaries 

ipm build --source ./my-package --destination ./build-output --summary-file ./reports/build-report.json

Export Operation Summaries

Export summaries document package extraction operations.

ipm export --package publisher/package-name --destination ./export-folder --summary-file ./reports/export-report.json

Publish Operation Summaries

Publish summaries record package publication operations.

ipm publish --package publisher/package-name --version 1.0.0 --folder ./ --summary-file ./reports/publish-report.json

What These Files Are Good For

Change Tracking

Summary files help you track what changed between builds:

# Compare two build summaries
jq '.files[].path' build-v1.json > files-v1.txt
jq '.files[].path' build-v2.json > files-v2.txt
diff files-v1.txt files-v2.txt

Understanding Package Contents

See exactly what’s in your packages and what was excluded:

# Count included vs excluded files
echo "Included: $(jq '.totalFiles' build-report.json)"
echo "Excluded: $(jq '.skippedFiles | length' build-report.json)"

File Integrity Verification

The SHA-256 hashes let you verify files haven’t changed:

# Extract file hash from summary
jq -r '.files[] | select(.path=="main.tf") | .hash' build-report.json

Build Reproducibility

Summary files document exactly what was processed, helping reproduce builds:

# List all source files that were included
jq -r '.files[].path' build-report.json

Analyzing Exclusions

Understanding what gets skipped helps ensure your packages contain the right content:

Check for Expected Exclusions 

# Count package-related exclusions
jq '.skippedFiles[] | select(contains("packages/"))' build-report.json | wc -l

# Review configuration file exclusions
jq '.skippedFiles[] | select(contains(".tf") or contains(".yml"))' build-report.json

Identify Unexpected Exclusions 

# Look for specific patterns in excluded files
jq '.skippedFiles[] | select(contains("README"))' build-report.json

Best Practices

File Organization

Keep summary files organized by date and operation:

reports/
├── build/
│   ├── 2025-09-12/
│   │   ├── build-143015.json
│   │   └── build-151230.json
├── export/
│   └── 2025-09-12/
│       └── export-140015.json
└── publish/
    └── 2025-09-12/
        └── publish-162045.json

Automated Report Generation

Include summary files in your build scripts:

#!/bin/bash
REPORT_DIR="./reports/$(date +%Y-%m-%d)"
mkdir -p "$REPORT_DIR"

# Build with summary
ipm build --source ./src --destination ./dist \
  --summary-file "$REPORT_DIR/build-$(date +%H%M%S).json"

Report Validation

Basic checks to ensure reports are complete:

# Check if build completed
jq '.action == "Build"' build-report.json

# Validate file counts make sense
INCLUDED=$(jq '.totalFiles' build-report.json)
ACTUAL=$(jq '.files | length' build-report.json)
if [ "$INCLUDED" -ne "$ACTUAL" ]; then
  echo "File count mismatch in report"
fi

Integration Examples

CI/CD Pipeline Integration 

- name: Build with Summary
  run: |
    mkdir -p ./reports
    ipm build --source ./src --destination ./dist --summary-file ./reports/build-$(date +%Y%m%d-%H%M%S).json

Comparing Builds 

# Compare file lists between two builds
jq -r '.files[].path' old-build.json | sort > old-files.txt
jq -r '.files[].path' new-build.json | sort > new-files.txt
echo "Files added:"
comm -13 old-files.txt new-files.txt
echo "Files removed:"
comm -23 old-files.txt new-files.txt