docs(eng-11208): Adds format & upstream documentation for Alpine and Wolfi

[poconnor-cloud]

What's Changed

Updated and Added to our Alpine Format Documentation:

• Additional detail on how to handle upload/download of packages, with wolfi examples
• Added Upstream Proxying guidelines for Alpine / WOLFI
• Tested and verified examples, including setup script, basic (token, api_key) and cli authentication.
• Updated Index file

co-authored by @apoclyps

relates to:

• https://linear.app/cloudsmith/issue/ENG-11208/alpine-add-documentation-to-the-cloudsmith-docs

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
cloudsmith-docs	Ready	Preview, Comment	Apr 1, 2026 2:08pm

[poconnor-cloud]

TODO -

• Add details on how to configure Upstream via Web UI (Old and New)
• Add some images and screenshots

[apoclyps]

As part of the documentation, it's worth verifying that each of the mechanisms being documented works as expected e.g. adding a distribution, the auth mechanisms, etc. The ticket can be used to track that these work using the input + output to avoid adding a bunch of unnecessary context to the PR.

[Copilot]

Pull request overview

Updates Cloudsmith documentation to clarify Alpine/Wolfi APK usage and adds guidance for configuring Alpine/Wolfi upstream proxying and caching.

Changes:

• Adds Alpine upstream creation guidance and updates the upstreams index to include Alpine.
• Expands Alpine format docs to cover Wolfi, including upload/install instructions and upstream proxying/caching guidance.
• Refactors portions of existing upstream documentation for generic upstream fields and notes.

Reviewed changes

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

File	Description
src/content/repositories/upstreams/index.mdx	Adds Alpine to supported upstream formats and documents how to configure an Alpine/Wolfi upstream.
src/content/formats/alpine-repository.mdx	Reworks Alpine format docs to include Wolfi details, updated upload/install flows, and upstream proxying/caching instructions.

Comments suppressed due to low confidence (1)

src/content/formats/alpine-repository.mdx:255

• The removal instructions delete /etc/apk/keys/REPOSITORY@cloudsmith-FINGERPRINT.rsa.pub, but earlier setup instructions create /etc/apk/keys/REPOSITORY@OWNER-FINGERPRINT.rsa.pub. This mismatch means the documented cleanup step may not actually remove the installed key.

Remove the cloudsmith repository line, save then execute:

rm -f /etc/apk/keys/REPOSITORY@cloudsmith-FINGERPRINT.rsa.pub
apk update

---

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

[apoclyps]

Looks good to me 👍

I paired on part of this and pushed commits so unable to give an approval. Some changes to note:

• username:password as an auth mechanism isn't supported. It's not in the classic or new ui contextual docs (nor does it work when provided) so it's been removed here
• CLI changes were manually tested for alpine + wolfi

[ertzL]

I've just left too comments on removing the EA banner & adding a screenshot for configuring the upstream - but other than that LGTM!