Skip to content

Commit 7dff13c

Browse files
Turbo87Turbo87
committed
Add Trusted Publishing documentation
1 parent b2d3876 commit 7dff13c

File tree

2 files changed

+122
-0
lines changed

2 files changed

+122
-0
lines changed

‎app/router.js

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,9 @@ Router.map(function () {
6161
// of the URL to be `/security`.
6262
this.route('security');
6363
this.route('data-access');
64+
this.route('docs', function () {
65+
this.route('trusted-publishing');
66+
});
6467
this.route('confirm', { path: '/confirm/:email_token' });
6568
this.route('accept-invite', { path: '/accept-invite/:token' });
6669
this.route('support');

‎app/templates/docs/trusted-publishing.hbs

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
<PageHeader @title="Trusted Publishing" />
2+
3+
<TextContent @boxed={{true}}>
4+
<h2>What is Trusted Publishing?</h2>
5+
<p>
6+
Trusted Publishing is a secure way to publish your Rust crates from GitHub Actions without manually managing API tokens.
7+
It uses OpenID Connect (OIDC) to verify that your workflow is running from your repository, then provides a short-lived token for publishing.
8+
</p>
9+
10+
<p>
11+
Instead of storing long-lived API tokens in your repository secrets, Trusted Publishing allows GitHub Actions to authenticate
12+
directly with crates.io using cryptographically signed tokens that prove the workflow's identity.
13+
</p>
14+
15+
<p>
16+
<strong>Note:</strong> crates.io currently only supports GitHub Actions, but we are planning to support other
17+
CI/CD platforms like GitLab CI/CD in the future.
18+
</p>
19+
20+
<h3>Security Benefits</h3>
21+
<ul>
22+
<li><strong>No long-lived API tokens</strong> to manage or rotate</li>
23+
<li><strong>Tokens automatically expire</strong> after 30 minutes</li>
24+
<li><strong>Repository and workflow verification</strong> prevents unauthorized publishing</li>
25+
<li><strong>OIDC-based cryptographic verification</strong> with GitHub's public JWKS</li>
26+
<li><strong>Optional GitHub Actions environments</strong> for additional access controls</li>
27+
</ul>
28+
29+
<h2>Quick Start</h2>
30+
<p>Follow these steps to set up Trusted Publishing for your crate:</p>
31+
32+
<ol>
33+
<li><strong>Configure your crate for Trusted Publishing</strong> in the crates.io settings</li>
34+
<li><strong>Set up your GitHub Actions workflow</strong> with the required permissions and authentication action</li>
35+
<li><strong>Publish your crate</strong> using the automated workflow</li>
36+
</ol>
37+
38+
<h3>Prerequisites</h3>
39+
<ul>
40+
<li>Your crate must already be published to crates.io (initial publish requires an API token)</li>
41+
<li>You must be an owner of the crate on crates.io</li>
42+
<li>Your repository must be on GitHub</li>
43+
</ul>
44+
45+
<h2>Configuring Trusted Publishing</h2>
46+
<p>
47+
Configure your crate on crates.io:
48+
</p>
49+
50+
<ol>
51+
<li>Go to your crate's Settings → Trusted Publishing</li>
52+
<li>Click "Add Trusted Publisher" and fill in:
53+
<ul>
54+
<li><strong>Repository owner:</strong> Your GitHub username or organization</li>
55+
<li><strong>Repository name:</strong> The name of your repository</li>
56+
<li><strong>Workflow filename:</strong> The filename of your GitHub Actions workflow (e.g., "release.yml")</li>
57+
<li><strong>Environment:</strong> Optional environment name if you're using GitHub environments</li>
58+
</ul>
59+
</li>
60+
<li>Save the configuration</li>
61+
</ol>
62+
63+
<h2>GitHub Actions Setup</h2>
64+
<p>
65+
Create a workflow file at <code>.github/workflows/release.yml</code>:
66+
</p>
67+
68+
<pre><code>name: Publish to crates.io
69+
on:
70+
push:
71+
tags: ['v*']
72+
jobs:
73+
publish:
74+
runs-on: ubuntu-latest
75+
environment: release # Optional: for enhanced security
76+
permissions:
77+
id-token: write # Required for OIDC token exchange
78+
contents: read # Required to checkout repository
79+
steps:
80+
- uses: actions/checkout@v4
81+
- uses: rust-lang/crates-io-auth-action@v1
82+
id: auth
83+
- run: cargo publish
84+
env:
85+
CARGO_REGISTRY_TOKEN: $\{{ steps.auth.outputs.token }}</code></pre>
86+
87+
<p>
88+
<strong>Optional:</strong> For enhanced security, create a GitHub Actions environment named "release"
89+
in your repository settings with protection rules like required reviewers or deployment branches.
90+
</p>
91+
92+
<h2>Security & Best Practices</h2>
93+
<ul>
94+
<li><strong>Use specific workflow filenames</strong> to reduce the attack surface</li>
95+
<li><strong>Use GitHub Actions environments</strong> with protection rules for sensitive publishing</li>
96+
<li><strong>Limit workflow triggers</strong> to specific tags or protected branches</li>
97+
<li><strong>Review all actions used</strong> in your release workflow</li>
98+
<li><strong>Monitor publishing activities</strong> through crates.io email notifications</li>
99+
</ul>
100+
101+
<p>
102+
<strong>How it works:</strong> GitHub Actions generates an OIDC token that proves your workflow's identity.
103+
The <code>rust-lang/crates-io-auth-action</code> exchanges this for a 30-minute access token that
104+
<code>cargo publish</code> uses automatically.
105+
</p>
106+
107+
<h2>Migration from API Tokens</h2>
108+
<p>
109+
To migrate from API tokens: set up Trusted Publishing following the steps above, test it,
110+
then remove the API token from your repository secrets. Both methods can be used simultaneously during transition.
111+
</p>
112+
113+
<h2>Additional Resources</h2>
114+
<ul>
115+
<li><a href="https://rust-lang.github.io/rfcs/3691-trusted-publishing-cratesio.html">RFC 3691: Trusted Publishing for crates.io</a></li>
116+
<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>
117+
<li><a href="https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment">GitHub: Using environments for deployment</a></li>
118+
</ul>
119+
</TextContent>

0 commit comments

Comments
 (0)