diff --git a/app/router.js b/app/router.js index e683b17aebc..4a4a34363c6 100644 --- 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 index 6c8ec0daeac..67132621c49 100644 --- 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 index f4dea175696..1e797bfa3fc 100644 --- a/app/templates/crate/settings/index.hbs +++ b/app/templates/crate/settings/index.hbs @@ -2,7 +2,7 @@ -
+

Owners

{{#unless this.addOwnerVisible}} @@ -56,11 +56,16 @@ {{! The "Trusted Publishing" section is hidden for now until we make this feature publicly available. }} {{#if this.githubConfigs}} -
+

Trusted Publishing

- - Add - +
+ + Learn more + + + Add + +
@@ -95,7 +100,7 @@
{{/if}} -

Danger Zone

+

Danger Zone

diff --git a/app/templates/docs/trusted-publishing.hbs b/app/templates/docs/trusted-publishing.hbs new file mode 100644 index 00000000000..ab5d19adb0c --- /dev/null +++ b/app/templates/docs/trusted-publishing.hbs @@ -0,0 +1,120 @@ + + + +

What is Trusted Publishing?

+

+ 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. +

+ +

+ 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. +

+ +

+ Note: crates.io currently only supports GitHub Actions, but we are planning to support other + CI/CD platforms like GitLab CI/CD in the future. +

+ +

Security Benefits

+
    +
  • No long-lived API tokens to manage or rotate
    • +
  • Tokens automatically expire after 30 minutes
    • +
  • Repository and workflow verification prevents unauthorized publishing
    • +
  • OIDC-based cryptographic verification with GitHub's public JWKS
    • +
  • Optional GitHub Actions environments for additional access controls
    • +
+ +

Quick Start

+

Follow these steps to set up Trusted Publishing for your crate:

+ +
    +
  1. Configure your crate for Trusted Publishing in the crates.io settings
    2. +
  2. Set up your GitHub Actions workflow with the required permissions and authentication action
    3. +
  3. Publish your crate using the automated workflow
    4. +
+ +

Prerequisites

+
    +
  • Your crate must already be published to crates.io (initial publish requires an API token)
    • +
  • You must be an owner of the crate on crates.io
    • +
  • Your repository must be on GitHub
    • +
+ +

Configuring Trusted Publishing

+

+ Configure your crate on crates.io: +

+ +
    +
  1. Go to your crate's Settings → Trusted Publishing
    2. +
  2. Click "Add Trusted Publisher" and fill in: +
      +
    • Repository owner: Your GitHub username or organization
      • +
    • Repository name: The name of your repository
      • +
    • Workflow filename: The filename of your GitHub Actions workflow (e.g., "release.yml")
      • +
    • Environment: Optional environment name if you're using GitHub environments
      • +
    +
    3. +
  3. Save the configuration
    4. +
+ +

GitHub Actions Setup

+

+ Create a workflow file at .github/workflows/release.yml. This example workflow will automatically publish your crate each time you push a version tag (like v1.0.0): +

+ + {{!-- template-lint-disable no-whitespace-for-layout --}} + 
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 }}
+ +

+ Optional: For enhanced security, create a GitHub Actions environment named "release" + in your repository settings with protection rules like required reviewers or deployment branches. +

+ +

Security & Best Practices

+
    +
  • Use specific workflow filenames to reduce the attack surface
    • +
  • Use GitHub Actions environments with protection rules for sensitive publishing
    • +
  • Limit workflow triggers to specific tags or protected branches
    • +
  • Review all actions used in your release workflow
    • +
  • Monitor publishing activities through crates.io email notifications
    • +
+ +

+ How it works: GitHub Actions generates an OIDC token that proves your workflow's identity. + The rust-lang/crates-io-auth-action exchanges this for a 30-minute access token that + cargo publish uses automatically. +

+ +

Migration from API Tokens

+

+ 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. +

+ +

Additional Resources

+ + \ No newline at end of file