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.

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)

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.

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

Folders with the following names will be excluded by default:

  .git
.svn
.hg
.vscode
.idea
.terraform
node_modules
obj
  • Examples: Consider including an /examples directory with working samples to help users understand how to use your package.

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
├── 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

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:

  1. Using client secrets for authentication instead of interactive login
  2. Creating clear naming conventions for version numbers (e.g., based on git tags)
  3. Running validation tests before publishing
  # Example CI/CD publishing script (bash)
export IPM_CLIENT_SECRET="your-client-secret"
ipm publish --package myorg/my-package --version ${VERSION_NUMBER} --folder ./dist

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

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)