docs: improve the generic format & upstream documentation#335
docs: improve the generic format & upstream documentation#335
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
apoclyps
changed the title
There was a problem hiding this comment.
Pull request overview
This PR updates Cloudsmith documentation around the Generic repository format (and its relationship to signing keys) to reduce ambiguity and provide clearer, more explicit examples—especially around upstream prefixes and download/auth flows.
Changes:
- Updates Generic format documentation with revised identifier tables, upload/download examples, upstream proxying explanation, and a concrete upstream example.
- Adjusts Generic “Key Signing Support” messaging to make lack of signing explicit and points to Raw format for signed artifacts.
- Aligns signing-keys matrix styling for Generic to match other “Not Supported by Format” entries.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
src/content/supply-chain-security/signing-keys.mdx |
Updates Generic row styling to reflect “Not Supported by Format” consistently. |
src/content/formats/generic-repository.mdx |
Refines Generic format docs: examples, upstream prefix explanation, download/auth guidance, and signing support messaging. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| Example `curl` commands to download a generic package from a public repository: | ||
|
|
||
| ```shell | ||
| curl -sLf -O 'https://generic.cloudsmith.io/public/OWNER/REPOSITORY/path/to/file.tar.gz' | ||
| ``` | ||
|
|
||
| With upstream prefix: | ||
|
|
||
| ```shell | ||
| curl -sLf -O 'https://generic.cloudsmith.io/public/OWNER/REPOSITORY/node_distributions/latest/node-v4.9.1.tar.gz' | ||
| curl -sLf -O "https://generic.cloudsmith.io/OWNER/REPOSITORY/UPSTREAM_PREFIX/path/to/file.tar.gz" | ||
| ``` |
There was a problem hiding this comment.
The public download example hard-codes UPSTREAM_PREFIX into the URL, but upstream prefixes only apply to upstream-cached content; directly uploaded files won't have that segment. Add a direct-upload URL example (no prefix) and a separate upstream-cached example (with prefix) to avoid implying the prefix is always required.
| Using Entitlement Token authentication: | ||
|
|
||
| ```shell | ||
| curl -sLf -O 'https://generic.cloudsmith.io/TOKEN/OWNER/REPOSITORY/FILEPATH' | ||
| ``` | ||
|
|
||
| With upstream prefix: | ||
|
|
||
| ```shell | ||
| curl -sLf -O 'https://generic.cloudsmith.io/TOKEN/OWNER/REPOSITORY/UPSTREAM_PREFIX/FILEPATH' | ||
| ``` | ||
|
|
||
| Using HTTP Basic authentication: | ||
|
|
||
| ```shell | ||
| curl -sLf -u "USERNAME:PASSWORD" -O 'https://generic.cloudsmith.io/basic/OWNER/REPOSITORY/FILEPATH' | ||
| curl -sLf -u "token:TOKEN" -O "https://generic.cloudsmith.io/OWNER/REPOSITORY/UPSTREAM_PREFIX/path/to/file.tar.gz" | ||
| ``` |
There was a problem hiding this comment.
The headings/wording imply “Entitlement Token authentication” is distinct from “HTTP Basic authentication”, but the shown curl commands use -u (HTTP Basic) in both cases with username token and the token/API key as the password. Consider rewording to describe this as HTTP Basic auth with different credentials (and add a USERNAME/PASSWORD example only if it’s supported for Generic).
| <Note variant="note" headline="Private Repositories"> | ||
| Private Cloudsmith repositories require authentication. You can choose between Entitlement Token Authentication or HTTP Basic Authentication. The setup method will differ depending on what authentication type you choose to use. | ||
| </Note> | ||
|
|
There was a problem hiding this comment.
The prior “Secrets management” warning about treating entitlement tokens and API keys as secrets was removed. Other format docs include this warning (e.g., Go registry), and removing it increases the risk of users committing credentials into source control; consider re-adding a short warning note here.
| | FILEPATH | The repository path where the file will be stored (e.g., `path/to/file.tar.gz`) | | ||
| | UPSTREAM_PREFIX | Upstream prefix (e.g., `node_distributions/`) for files cached from upstreams | | ||
| | Identifier | Description | | ||
| |-:---------------|-:------------------------------------------------------------------------------------------------------------------| |
There was a problem hiding this comment.
The table alignment row uses |-:...|-:...|, which isn't valid Markdown table syntax and likely won't render correctly. Use standard alignment markers (e.g., | :--- | :--- | for left alignment or | ---: | --- | as needed).
| |-:---------------|-:------------------------------------------------------------------------------------------------------------------| | |
| | :------------- | :------------------------------------------------------------------------------------------------------------------ | |
| | REPOSITORY | Your Cloudsmith Repository name (also called "slug") | | ||
| | TOKEN | Your Cloudsmith Entitlement Token (see [Entitlements](/software-distribution/entitlement-tokens) for more details) | | ||
| | API-KEY | Your Cloudsmith API Key | | ||
| | UPSTREAM_PREFIX | Upstream prefix (e.g., `node_distributions/`) for files cached from upstreams | |
There was a problem hiding this comment.
UPSTREAM_PREFIX is described with a trailing slash (node_distributions/), but later examples treat it as a path segment without a trailing slash. This can lead to double slashes in constructed URLs; consider documenting the prefix without a trailing slash and stating it is inserted as a single path segment.
| | UPSTREAM_PREFIX | Upstream prefix (e.g., `node_distributions/`) for files cached from upstreams | | |
| | UPSTREAM_PREFIX | Upstream prefix (e.g., `node_distributions`, without a trailing slash) used as a single path segment for files cached from upstreams | |
1 participant
What's Changed
Based on feedback from Customers, the generic documentation isn't clear enough and needs improved clarify.
The following changes attempts to remove ambiguity and provide explicit clear examples to follow.