rust-lang · Turbo87 · Jun 23, 2025 · Jun 23, 2025 · Jun 23, 2025 · Jun 23, 2025
diff --git a/app/router.js b/app/router.js
@@ -61,6 +61,9 @@ Router.map(function () {
   // of the URL to be `/security`.
   this.route('security');
   this.route('data-access');
+  this.route('docs', function () {
+    this.route('trusted-publishing');
+  });
   this.route('confirm', { path: '/confirm/:email_token' });
   this.route('accept-invite', { path: '/accept-invite/:token' });
   this.route('support');

diff --git a/app/styles/crate/settings/index.module.css b/app/styles/crate/settings/index.module.css
@@ -1,7 +1,14 @@
-.owners-header, .trusted-publishing-header {
+.header {
     display: flex;
     justify-content: space-between;
     align-items: center;
+    flex-wrap: wrap;
+    gap: var(--space-s);
+    margin: var(--space-m) 0;
+
+    > h2 {
+        margin: 0;
+    }
 }
 
 .email-form {

diff --git a/app/templates/crate/settings/index.hbs b/app/templates/crate/settings/index.hbs
@@ -2,7 +2,7 @@
 
 <CrateHeader @crate={{this.crate}} />
 
-<div local-class="owners-header">
+<div local-class="header">
   <h2>Owners</h2>
   {{#unless this.addOwnerVisible}}
     <button type="button" class="button button--small" data-test-add-owner-button {{on "click" this.showAddOwnerForm}}>Add Owner</button>
@@ -56,11 +56,16 @@
 
 {{! The "Trusted Publishing" section is hidden for now until we make this feature publicly available. }}
 {{#if this.githubConfigs}}
-  <div local-class="trusted-publishing-header">
+  <div local-class="header">
     <h2>Trusted Publishing</h2>
-    <LinkTo @route="crate.settings.new-trusted-publisher" class="button button--small" data-test-add-trusted-publisher-button>
-      Add
-    </LinkTo>
+    <div>
+      <LinkTo @route="docs.trusted-publishing" class="button button--tan button--small" data-test-trusted-publishing-docs-button>
+        Learn more
+      </LinkTo>
+      <LinkTo @route="crate.settings.new-trusted-publisher" class="button button--small" data-test-add-trusted-publisher-button>
+        Add
+      </LinkTo>
+    </div>
   </div>
 
   <table local-class="trustpub" data-test-trusted-publishing>
@@ -95,7 +100,7 @@
   </table>
 {{/if}}
 
-<h2>Danger Zone</h2>
+<h2 local-class="header">Danger Zone</h2>
 
 <div>
   <LinkTo @route="crate.delete" class="button button--red" data-test-delete-button>

diff --git a/app/templates/docs/trusted-publishing.hbs b/app/templates/docs/trusted-publishing.hbs
@@ -0,0 +1,120 @@
+<PageHeader @title="Trusted Publishing" />
+
+<TextContent @boxed={{true}}>
+  <h2>What is Trusted Publishing?</h2>
+  <p>
+    Trusted Publishing is a secure way to publish your Rust crates from GitHub Actions without manually managing API tokens.
+    It uses OpenID Connect (OIDC) to verify that your workflow is running from your repository, then provides a short-lived token for publishing.
+  </p>
+
+  <p>
+    Instead of storing long-lived API tokens in your repository secrets, Trusted Publishing allows GitHub Actions to authenticate
+    directly with crates.io using cryptographically signed tokens that prove the workflow's identity.
+  </p>
+
+  <p>
+    <strong>Note:</strong> crates.io currently only supports GitHub Actions, but we are planning to support other
+    CI/CD platforms like GitLab CI/CD in the future.
+  </p>
+
+  <h3>Security Benefits</h3>
+  <ul>
+    <li><strong>No long-lived API tokens</strong> to manage or rotate</li>
+    <li><strong>Tokens automatically expire</strong> after 30 minutes</li>
+    <li><strong>Repository and workflow verification</strong> prevents unauthorized publishing</li>
+    <li><strong>OIDC-based cryptographic verification</strong> with GitHub's public JWKS</li>
+    <li><strong>Optional GitHub Actions environments</strong> for additional access controls</li>
+  </ul>
+
+  <h2>Quick Start</h2>
+  <p>Follow these steps to set up Trusted Publishing for your crate:</p>
+
+  <ol>
+    <li><strong>Configure your crate for Trusted Publishing</strong> in the crates.io settings</li>
+    <li><strong>Set up your GitHub Actions workflow</strong> with the required permissions and authentication action</li>
+    <li><strong>Publish your crate</strong> using the automated workflow</li>
+  </ol>
+
+  <h3>Prerequisites</h3>
+  <ul>
+    <li>Your crate must already be published to crates.io (initial publish requires an API token)</li>
+    <li>You must be an owner of the crate on crates.io</li>
+    <li>Your repository must be on GitHub</li>
+  </ul>
+
+  <h2>Configuring Trusted Publishing</h2>
+  <p>
+    Configure your crate on crates.io:
+  </p>
+
+  <ol>
+    <li>Go to your crate's Settings → Trusted Publishing</li>
+    <li>Click "Add Trusted Publisher" and fill in:
+      <ul>
+        <li><strong>Repository owner:</strong> Your GitHub username or organization</li>
+        <li><strong>Repository name:</strong> The name of your repository</li>
+        <li><strong>Workflow filename:</strong> The filename of your GitHub Actions workflow (e.g., "release.yml")</li>
+        <li><strong>Environment:</strong> Optional environment name if you're using GitHub environments</li>
+      </ul>
+    </li>
+    <li>Save the configuration</li>
+  </ol>
+
+  <h2>GitHub Actions Setup</h2>
+  <p>
+    Create a workflow file at <code>.github/workflows/release.yml</code>. This example workflow will automatically publish your crate each time you push a version tag (like <code>v1.0.0</code>):
+  </p>
+
+  {{!-- template-lint-disable no-whitespace-for-layout  --}}
+  <pre><code class="language-yaml" {{highlight-syntax}}>name: Publish to crates.io
+on:
+  push:
+    tags: ['v*']  # Triggers when pushing tags starting with 'v'
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: release  # Optional: for enhanced security
+    permissions:
+      id-token: write     # Required for OIDC token exchange
+      contents: read      # Required to checkout repository
+    steps:
+    - uses: actions/checkout@v4
+    - uses: rust-lang/crates-io-auth-action@v1
+      id: auth
+    - run: cargo publish
+      env:
+        CARGO_REGISTRY_TOKEN: $\{{ steps.auth.outputs.token }}</code></pre>
+
+  <p>
+    <strong>Optional:</strong> For enhanced security, create a GitHub Actions environment named "release"
+    in your repository settings with protection rules like required reviewers or deployment branches.
+  </p>
+
+  <h2>Security &amp; Best Practices</h2>
+  <ul>
+    <li><strong>Use specific workflow filenames</strong> to reduce the attack surface</li>
+    <li><strong>Use GitHub Actions environments</strong> with protection rules for sensitive publishing</li>
+    <li><strong>Limit workflow triggers</strong> to specific tags or protected branches</li>
+    <li><strong>Review all actions used</strong> in your release workflow</li>
+    <li><strong>Monitor publishing activities</strong> through crates.io email notifications</li>
+  </ul>
+
+  <p>
+    <strong>How it works:</strong> GitHub Actions generates an OIDC token that proves your workflow's identity.
+    The <code>rust-lang/crates-io-auth-action</code> exchanges this for a 30-minute access token that
+    <code>cargo publish</code> uses automatically.
+  </p>
+
+  <h2>Migration from API Tokens</h2>
+  <p>
+    To migrate from API tokens: set up Trusted Publishing following the steps above, test it,
+    then remove the API token from your repository secrets. Both methods can be used simultaneously during transition.
+  </p>
+
+  <h2>Additional Resources</h2>
+  <ul>
+    <li><a href="https://rust-lang.github.io/rfcs/3691-trusted-publishing-cratesio.html">RFC 3691: Trusted Publishing for crates.io</a></li>
+    <li><a href="https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect">GitHub: About security hardening with OpenID Connect</a></li>
+    <li><a href="https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment">GitHub: Using environments for deployment</a></li>
+  </ul>
+</TextContent>