release(eng-12003): Release of arbitrary metadata support

[BartoszBlizniak]

Description

Release PR for cloudsmith-cli v1.17.0.

This release introduces arbitrary package metadata to the CLI: a standalone cloudsmith metadata command group (CRUD) and push-time --metadata-* flags on every cloudsmith push <format> subcommand. SBOMs, JFrog BuildInfo documents, and other custom JSON payloads can now be attached to packages in a single push command — or managed afterwards via the dedicated subcommand group.

What's in this PR

• README.md: documents the metadata command group and the push-time --metadata-* flags, following the existing structure (one section per feature, examples, failure-behavior note).
• CHANGELOG.md: adds the 1.17.0 entry covering both the standalone command group and the push integration.

Feature recap

cloudsmith metadata command group

• metadata add OWNER/REPO/PACKAGE --content-type ... (--file PATH | --content JSON) [--source-identity ...]
• metadata list OWNER/REPO/PACKAGE [METADATA_SLUG_PERM] [--source-kind ...] [--classification ...]
• metadata update OWNER/REPO/PACKAGE METADATA_SLUG_PERM (--file PATH | --content JSON) [--source-identity ...]
• metadata remove OWNER/REPO/PACKAGE METADATA_SLUG_PERM [-y]

Content type is set on creation and cannot be changed. Defaults --source-identity to cloudsmith-cli@<version>. Supports --output-format json | pretty_json.

Push-time --metadata-* flags

Every cloudsmith push <format> subcommand now accepts:

• --metadata-content-file PATH (or - for stdin)
• --metadata-content JSON
• --metadata-content-type MIME
• --metadata-source-identity TEXT
• --on-metadata-failure [error|warn]: per-push override for how validation/attach failures are handled. error (default) aborts the push; warn downgrades to a warning and uploads the package anyway.

Configuration

• New metadata_failure_mode key in config.ini (error | warn | 0) sets the default failure mode for push-time metadata. Resolution precedence is --on-metadata-failure flag → $CLOUDSMITH_METADATA_FAILURE_MODE env var → metadata_failure_mode config key → error default.

Type of Change

• New feature
• Refactoring
• Bug fix
• Breaking change
• Documentation update
• Other

Additional Notes

• Default mode aborts the push on validation/attach failure with the HTTP status as the exit code. Wrappers that need legacy "best-effort" behaviour can opt in via any of: the --on-metadata-failure warn CLI flag (per-push), $CLOUDSMITH_METADATA_FAILURE_MODE=warn (per-shell), or metadata_failure_mode = warn in config.ini (persistent).

Examples

Push:

cloudsmith push raw ${ORG}/${REPO} payload.txt --name metadata-demo --version 1.0.0 --republish --metadata-content '{"build_id": "demo-inline", "git_sha": "abc123"}' --metadata-content-type application/json

Checking raw package upload parameters ... OK
Validating metadata content from inline ... OK
Checking payload.txt file upload parameters ... OK
Requesting file upload for payload.txt ... OK
Uploading payload.txt:  [####################################]  100%
Creating a new raw package ... OK
Created: demo-org/repo/payloadtxt-wu4u (bONvPYh5LfhH)
Attaching metadata to package bONvPYh5LfhH ... OK
Metadata attached: demo-org/repo/payloadtxt-wu4u/ATkdRL03Uwk6

Synchronising payloadtxt-wu4u:  [####################################]  100%  Completed / Fully Synchronised

Package synchronised successfully in 16.006934 second(s)!

Push with invalid metadata:

cloudsmith push raw ${ORG}/${REPO} payload.txt --name metadata-demo --version 1.0.0 --republish --metadata-content-file buildinfo-broken.json --metadata-content-type application/vnd.jfrog.buildinfo+json

Checking raw package upload parameters ... OK
Validating metadata content from buildinfo-broken.json ... FAILED
ERROR
Metadata content failed validation (HTTP 422): Invalid input. (status: 422 - Unprocessable Entity)

Detail: Invalid input.
Content Field: Content does not conform to the schema for content type 'application/vnd.jfrog.buildinfo+json'.

Push with invalid metadata and $CLOUDSMITH_METADATA_FAILURE_MODE set to warn:

CLOUDSMITH_METADATA_FAILURE_MODE=warn cloudsmith push raw ${ORG}/${REPO} payload.txt --name metadata-demo --version 1.0.0 --republish --metadata-content-file buildinfo-broken.json --metadata-content-type application/vnd.jfrog.buildinfo+json

Checking raw package upload parameters ... OK
Validating metadata content from buildinfo-broken.json ... FAILED
Metadata content failed validation (HTTP 422): Invalid input.
Package upload will continue without metadata. Unset $CLOUDSMITH_METADATA_FAILURE_MODE (or set it to ``error``) to fail the push instead.
Checking payload.txt file upload parameters ... OK
Requesting file upload for payload.txt ... OK
Uploading payload.txt:  [####################################]  100%
Creating a new raw package ... OK
Created: demo-org/repo/payloadtxt-6mm2 (H4Q1EDW8Gm2E)

Fix the metadata content, then run:
cloudsmith metadata add demo-org/repo/payloadtxt-6mm2 --file buildinfo-broken.json --content-type application/vnd.jfrog.buildinfo+json

Synchronising payloadtxt-6mm2:  [####################################]  100%  Completed / Fully Synchronised

Package synchronised successfully in 6.121764 second(s)!

Manage existing metadata:

cloudsmith metadata add your-org/awesome-repo/better-pkg --content-type application/json --content '{"foo": "bar"}'
cloudsmith metadata list your-org/awesome-repo/better-pkg
cloudsmith metadata update your-org/awesome-repo/better-pkg meta-slug --content '{"foo": "baz"}'
cloudsmith metadata remove your-org/awesome-repo/better-pkg meta-slug

[BartoszBlizniak]

TODO: Bump version

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review and subscribe this PR to future pushes, or @claude review once for a one-time review.

_{Tip: disable this comment in your organization's Code Review settings.}

[Copilot]

Pull request overview

Documentation-only release PR for cloudsmith-cli v1.17.0. Updates README.md and CHANGELOG.md to document the new arbitrary metadata support (standalone cloudsmith metadata command group and push-time --metadata-* flags), and incidentally refreshes example placeholders in existing push/download sections from your-account to your-org.

Changes:

• Add README sections for Package Metadata and Attaching Metadata During Push, including failure-mode precedence docs.
• Update CHANGELOG with a 1.17.0 entry dated 2026-05-18 covering the metadata command group and push integration.
• Rename your-account to your-org in pre-existing push/download examples for consistency.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
README.md	Documents new metadata command group and --metadata-* push flags; updates placeholder org name in existing examples.
CHANGELOG.md	Adds 1.17.0 release entry describing metadata command group, push-time flags, and failure mode configuration.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.