Supporting users with effective documentation is key to helping them build an understanding of what attestations are and how they can be used.
Our research found that existing documentation about attestations was either missing entirely or written only for expert audiences. To address this and to support our UI recommendations, we suggest the following principles to help registries create effective documentation for attestation consumers.
Attestations documentation should:
Help package consumers understand attestations, including what they are, how they work, and what their limitations are
Help package consumers understand attestations within the context of other security features and practices
Direct package maintainers towards workflows that generate attestations
For attestation documentation to be most successful, we recommend documentation authors follow these seven principles:
To ensure clarity and consistency for attestation consumers, use key terms as defined below. Adhering to these standards prevents user confusion across packaging ecosystems.
Package consumers and maintainers require (and have) different levels of knowledge about security concepts and features, including attestations.
Content for package consumers should be separated from content for package maintainers, surfacing relevant and actionable information to each audience.
Structure the Information Architecture around user roles, using clear, top-level sections like “Using This Repository” (for consumers) and “Publishing Packages” (for maintainers).
Attestations are only one part of a larger security story. To be effective, documentation must place them in context, helping users build a holistic mental model of risk.
Documentation for package consumers should explain how security practices and features work together as a layered defense. It should be structured around the fundamental questions a user has about risk:
Can I trust the source code? Explaining signals like project activity, vulnerability scanning, etc.
Where did this package come from and how was it made? Explaining build provenance and attestations
Did I download the same file that is hosted on the package repository? Explaining checksums and integrity
Some package consumers hold the incorrect assumption that because a package is published on an official repository it is secure and/or trustworthy. To combat this, include disclaimers on pages for package consumers, directing users towards security documentation.
Example from PyPI: Warning: Installing packages from PyPI means running third-party code, which carries inherent security risks. Before installing any package, we strongly recommend reading our Package security guide.
Documentation should be opinionated in favor of security. The most secure method for any task should be presented as the canonical, recommended path.
When writing documentation about publishing packages, prominently feature the most secure, automated publishing method that generates attestations. This should be the first and most detailed workflow described, establishing it as the modern standard.
Where applicable, clearly and explicitly state that using the recommended workflow confers the benefit of generating provenance attestations automatically. This makes adopting the secure workflow more compelling.
Legacy methods that do not produce attestations should be explicitly marked as “deprecated” or “for advanced use cases” to guide users away from them.
Transparently list the threats the user faces (e.g., Typosquatting, Account Takeover) and what they can do to protect themselves. Explain platform-level features that mitigate common attacks, including the role of Trusted Publishing and attestations.
Provide clear reporting channels for users concerned about the security of an individual package or the package repository as a whole.
Documentation must be upfront about the scope and limitations of the security practices or features it describes.
State clearly that an attestation proves provenance (where a file came from) but does not vouch for the code’s safety (that the code is free of bugs or vulnerabilities). Explain that trusting an attestation means implicitly trusting the tooling and authority that issued it.
Be transparent about the readiness of downstream tooling. Where applicable, highlight that automated attestation verification is not yet ready in common package managers.
To help RubyGems.org, PyPI, and npm adopt attestation documentation best practices, we have created specific recommendations for each repository. Each recommendation includes user-tested templates that can be used to create new documentation or revise existing materials.
We encourage RubyGems.org, PyPI and npm to use, improve, and extend these templates as they see fit. Other package repositories can also use these templates as inspiration for their own attestations documentation.