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 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 ./

Verified Package Publishing

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

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

IPM automatically:

  1. Detects manifest files in the package directory
  2. Validates all files against build-time hashes
  3. Ensures no unauthorized modifications since build
  4. Awards a verified badge if all checks pass

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

Publishing with Audit Reporting

Generate audit documentation for compliance and governance:

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

After Publishing: Malware Scanning

Every published version is automatically scanned for malicious content. This is a background process that runs after ipm publish completes.

  • The scan can take up to 5 minutes
  • During this time, the version is unlisted and not available for download
  • Check scan status in the portal under the version overview

Scan States

Status Meaning
Awaiting Scan Queued. Download blocked until scan completes.
Unknown Status could not be determined. Contact support if this persists.
Scan Failed Scanner encountered an error. Contact support if this persists.
Skipped Scan was skipped for this version.
Clean No threats detected. Version is available for download.
No Threats Found No threats detected. Version is available for download.
Malicious Malicious content detected. Version is permanently blocked.

For full details on the scanning process, see Malware Scanning.

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 reports containing:

  • 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)
  • Compliance markers and performance metrics

For audit reporting capabilities, see the Audit Reporting guide.

Content Considerations

When publishing a package, IPM includes all files in the specified directory and subdirectories with these notes:

  • Including a README.md file is strongly recommended
  • Version numbers must use semantic versioning with digits only (e.g., 1.0.0)
  • Files and folders matching default exclusion rules are automatically skipped

Package Visibility

When publishing, your package is 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:

Basic CI/CD 

- name: Publish Package
  run: |
    ipm publish --package ${{ env.PACKAGE_NAME }} --version ${{ env.VERSION }} --folder ./
  env:
    IPM_CLIENT_SECRETS: ${{ secrets.IPM_CLIENT_SECRET }}

Enterprise CI/CD 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-report.json

- name: Publish Verified Package
  run: |
    ipm publish --package ${{ env.PACKAGE_NAME }} --version ${{ env.VERSION }} --folder ./dist --summary-file ./audit-reports/publish-report.json
  env:
    IPM_CLIENT_SECRETS: ${{ secrets.IPM_CLIENT_SECRET }}

Accounting for Malware Scanning in Pipelines

If a pipeline step depends on the newly published version being downloadable, wait for the scan to complete before proceeding:

ipm publish --package myorg/my-module --version 1.2.0 --folder ./

# Wait for background scan to complete
sleep 300

ipm add --package myorg/my-module --version 1.2.0

Troubleshooting

Common Issues

  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 the manifest file is present and files haven’t been modified
  5. Version not downloadable after publish: Check the version overview in the portal – scanning may still be in progress