Introduction

The ipm publish command allows you to publish new package versions to IPMHub. This guide covers the publishing process and best practices to ensure your packages are properly structured and accessible, including support for verified packages and comprehensive audit reporting.

Prerequisites

Before publishing a package with IPM, ensure you have:

  1. Created the package on IPMHub portal (see IPM Publishing guide)
  2. Prepared your package content in a local directory
  3. Authenticated with IPMHub using ipm login
  4. Determined the appropriate semantic version (e.g., 1.0.0)
  5. For verified packages: Built package with manifest using ipm build --include-manifest

Publishing Workflow

Basic Publishing

The standard syntax for publishing a package:

  ipm publish --package <publisher>/<package-name> --version <version> --folder <source-folder>

Required Parameters

  • --package or -p: The full package name including publisher (e.g., layer8solutions/bicep-module)
  • --version or -v: The semantic version number (e.g., 1.2.3)
  • --folder or -f: The directory containing the package content

Example 

  ipm publish --package layer8solutions/hello-world --version 1.0.0 --folder ./

This command publishes version 1.0.0 of the hello-world package under the layer8solutions publisher, using files from the current directory.

Verified Package Publishing

When publishing packages that contain manifest files, IPM automatically performs comprehensive verification:

  # Publish a verified package (manifest auto-detected)
ipm publish --package layer8solutions/hello-world --version 1.0.0 --folder ./build-output

IPM automatically:

  1. Detects Manifest Files: Identifies manifest files in the package directory
  2. Performs Integrity Verification: Validates all files against build-time hashes
  3. Validates Content: Ensures no unauthorized modifications since build
  4. Awards Verification Badge: Packages passing all checks receive verified status

If verification fails, publication is rejected with detailed error information.

Publishing with Audit Reporting

Generate comprehensive audit documentation for compliance and governance:

  ipm publish --package layer8solutions/hello-world --version 1.0.0 --folder ./ --summary-file ./audit/publish-report.json

Complete Enterprise Publishing

Combine verified packages with audit reporting for maximum enterprise compliance:

  # Publish verified package with full audit trail
ipm publish --package mycompany/enterprise-module --version 2.1.0 --folder ./build-output --summary-file ./audit/publish-$(date +%Y%m%d-%H%M%S).json

Verified Package Features

Automatic Verification Process

When a manifest file is detected during publish, IPM performs:

File Presence Verification

  • Confirms all files listed in manifest are present
  • Detects unauthorized file additions or removals
  • Validates directory structure integrity

Cryptographic Hash Validation

  • Recalculates SHA-256 hash for each file
  • Compares with build-time hashes from manifest
  • Rejects publication on any hash mismatches

Package Integrity Confirmation

  • Validates complete package hash
  • Ensures no modifications since build
  • Provides cryptographic proof of integrity

Verification Badge Award

  • Successful verification awards “verified” badge
  • Badge provides visual confirmation of package integrity
  • Creates trust chain from build to deployment

For complete verified package documentation, see the Verified Packages guide.

Audit Reporting for Publishing

Publication Audit Reports

When using --summary-file, publish operations generate comprehensive reports containing:

Package Publication Details

  • Package name, version, and publisher information
  • Publication timestamp and duration
  • Authentication and authorization records
  • Source folder analysis and file inventory

Verification Documentation (for verified packages)

  • Manifest detection and validation results
  • Individual file hash verification status
  • Complete package integrity confirmation
  • Verification badge award documentation

Compliance Information

  • User authentication and permission validation
  • Publication approval workflow evidence
  • Regulatory compliance markers
  • Change management documentation

Performance Metrics

  • Upload duration and throughput
  • File processing statistics
  • Network performance indicators
  • Resource utilization details

Example Publish Audit Report 

  {
  "timeStamp": "2025-07-16T08:52:49.068426+00:00",
  "action": "Publish",
  "sourceFolder": "/Users/bas/Documents/code/demo/vdl/demo1/ipm-build",
  "packageName": "layer8solutions/ipm-network-tf",
  "version": "1.2.4",
  "archiveHash": "sha256:9ad255c0e96abb72e2024958320650b839efee948c29b8ec241928e76be07e5a",
  "totalFiles": 22,
  "files": [
    {
      "path": "ipmhub.json",
      "hash": "SHA256:30f7156cf6bcae721b3b572290e34f916f117c6d7681e9b9541f62d016138b9a"
    },
    {
      "path": "main.tf",
      "hash": "SHA256:690dddd37992681f8a583692d45cd13f8242dacdfc607f9b812fcd59b4312f86"
    },
    {
      "path": "main.yaml",
      "hash": "SHA256:d19f3be446b9707c3ae93305813b58cdf8b89eeed252b54ee8417392fd781c86"
    },
    {
      "path": "README.md",
      "hash": "SHA256:47ec043a6a898afc2a5a19d8e93fa34283b49c0134f6188ddda6567c6a411024"
    },
    {
      "path": "RELEASENOTES.MD",
      "hash": "SHA256:31179283f0de1bfac406bd05163b60adeee5f983a35a19dadc12d74ad2ec3dd0"
    },
    {
      "path": "variables.tf",
      "hash": "SHA256:749e4cfec2c1591897e9e4c3d76ebb2e4d546f02e5854de88c51f9d14a44b3d4"
    },
    {
      "path": ".copy-2-root/base.tf",
      "hash": "SHA256:cd59337382b24fc572a04b71a4629ce6e3a24d7231ab9d90c4fe6513daa1256b"
    },
    {
      "path": ".copy-2-root/main.yaml",
      "hash": "SHA256:0aeea18d24131a0267d4f319fa92b296a90224e038e04446e791d2d80107ee04"
    },
    {
      "path": "azdo-pipelines/README.md",
      "hash": "SHA256:81f39868707be6dc82874bb6aba80d82471a49289d71b0d7d5fe671c369d7709"
    },
    {
      "path": "azdo-pipelines/jobs/apply-job.yml",
      "hash": "SHA256:8afaed6d6de52803f5e78e7f99e917d71327274fe05e7f8eb8d6b1d6eff066f3"
    },
    {
      "path": "azdo-pipelines/jobs/init-job.yml",
      "hash": "SHA256:0f85f2ad5f76648e84c7eac00257c0e4f4616fc3fb6caef2a86b98a1fc14492a"
    },
    {
      "path": "azdo-pipelines/jobs/plan-job.yml",
      "hash": "SHA256:90f26f78ad23db3eace95387e590c6481a0cff52e6e8201375dd198ddf5a1f25"
    },
    {
      "path": "azdo-pipelines/jobs/security-scan-job.yml",
      "hash": "SHA256:336bb8d9c1ec0656e8c73265bcea6b8a28044e692c93058cbe71dcf750a95a8f"
    },
    {
      "path": "azdo-pipelines/jobs/validate-job.yml",
      "hash": "SHA256:d2c70cdd5beeb64231509968afe0273ffbb208bd7eebda42f3e89a9da21c47d0"
    }
  ]
}

For comprehensive audit reporting capabilities, see the Audit Reporting guide.

Content Considerations

When publishing a package, IPM will include all files in the specified directory and its subdirectories with these important notes:

  • README Files: Including a README.md file is strongly recommended to provide usage instructions and documentation.

  • Automatically excluded files and folders: Some specific file extensions or folders are automatically excluded when building or publishing a package:

Files with the following extensions will be excluded by default:

  .lnk, .gitignore, .hgignore, .svnignore, .suo, .user, .sln.docstates, .log
.userosscache, .DS_Store, .Thumbs.db, .pyc, .pyo, .ps1xml, .psc1
.class, .o, .obj, .dll, .exe, .so, .dylib, .iso, .trace, .pid

Folders with the following names will be excluded by default:

  .git, .svn, .hg, .vscode, .idea, .terraform, node_modules, obj
bin, __pycache__, .egg, .egg-info, .whl

  • Examples: Consider including an /examples directory with working samples to help users understand how to use your package.

  • Manifest Files: For verified packages, ensure manifest files are present and unmodified since build

Best Practices

File Organization

Organize your package files in a clean, logical structure:

  my-package/
├── README.md         # Documentation with usage examples
├── main.bicep        # Main module file (or equivalent)
├── ipmhub.json       # Package metadata nested packages
├── manifest.json     # Verification manifest (for verified packages)
├── packages/         # Nested packages (if applicable)
│   └── nested-package/
│       └── main.bicep
└── examples/         # Example implementations
    └── basic/
        └── main.bicep

Version Management

Follow semantic versioning principles when publishing new versions:

  • Major (1.x.x): Breaking changes
  • Minor (x.1.x): New features, backward compatible
  • Patch (x.x.1): Bug fixes, backward compatible

Pre-publishing Checklist

Before publishing, verify:

  1. All necessary files are included in your source folder
  2. Your README.md is up-to-date and includes:
    • Package purpose and description
    • Installation instructions
    • Usage examples
    • Parameter documentation
  3. You have the correct permissions to publish to the specified package
  4. For verified packages: manifest file is present and unmodified
  5. Audit reporting requirements are met for enterprise environments

Enterprise Publishing Workflow

For enterprise environments, follow this comprehensive workflow:

  # 1. Build verified package with audit trail
ipm build --source ./src --destination ./dist --include-manifest --summary-file ./audit/build-report.json

# 2. Publish with comprehensive documentation
ipm publish --package myorg/enterprise-app --version 1.2.0 --folder ./dist --summary-file ./audit/publish-report.json

Package Visibility

When publishing, your package will be accessible according to the visibility setting configured when the package was created:

  • Public: Visible and downloadable by anyone
  • Hybrid: Visible in search but requires authorization to download
  • Private: Only visible to authorized users

See Package Visibility for detailed information.

Publishing in CI/CD Pipelines

For automated publishing in CI/CD pipelines, consider:

Enterprise CI/CD with Verification 

  # Enterprise CI/CD pipeline with verified packages
- name: Build Verified Package
  run: |
    mkdir -p ./audit-reports
    ipm build --source ./src --destination ./dist --include-manifest --summary-file ./audit-reports/build-$(date +%Y%m%d-%H%M%S).json

- name: Publish Verified Package
  run: |
    ipm publish --package ${{ env.PACKAGE_NAME }} --version ${{ env.VERSION }} --folder ./dist --summary-file ./audit-reports/publish-$(date +%Y%m%d-%H%M%S).json
  env:
    IPM_CLIENT_SECRETS: ${{ secrets.IPM_CLIENT_SECRET }}

Compliance Integration 

  # Example CI/CD publishing script with compliance
export IPM_CLIENT_SECRET="your-client-secret"

# Build with verification
ipm build --source ./src --destination ./dist --include-manifest

# Publish with audit documentation
ipm publish --package myorg/my-package --version ${VERSION_NUMBER} --folder ./dist --summary-file ./compliance/publish-report.json

# Validate publication success
if jq -e '.verification.verifiedBadgeAwarded' ./compliance/publish-report.json; then
  echo "Verified package published successfully"
else
  echo "Publication succeeded but verification failed"
  exit 1
fi

Troubleshooting

Common Issues

If you encounter issues when publishing:

  1. Authentication Errors: Ensure you’re logged in (ipm login) and have publisher permissions
  2. Version Conflicts: Verify you’re not attempting to publish a version that already exists
  3. Missing Files: Confirm all required files are present in your source folder
  4. Verification Failures: For verified packages, ensure manifest file is present and files haven’t been modified

Verification-Specific Issues

Manifest File Missing 

  Error: Manifest file not found in package directory
Solution: Build package with --include-manifest parameter

Hash Verification Failure 

  Error: File hash mismatch - main.tf
Expected: SHA256:11c0e73...
Actual:   SHA256:22d1e84...
Solution: Rebuild package or restore original file content

File Missing from Manifest 

  Error: File 'config.yaml' found in package but not in manifest
Solution: Rebuild package with current file set

For persistent issues, check:

  • Network connectivity to IPMHub
  • Permission settings for your user or organization
  • Log files for detailed error messages (--loglevel Debug can help)
  • Audit reports for detailed operation documentation

Enterprise Compliance Features

Regulatory Support

Publishing with audit reporting supports:

  • SOX Compliance: Complete audit trails for financial system deployments
  • ISO 27001: Security control evidence and change management
  • GDPR: Data processing activity documentation
  • Industry Standards: Compliance with sector-specific requirements

Governance Integration

  • Change Management: Complete documentation of package changes
  • Approval Workflows: Evidence of proper authorization
  • Risk Management: Security verification and integrity proof
  • Operational Transparency: Performance metrics and process documentation