Skip to content

Commit da57d50

Browse files
Turbo87Turbo87
authored
Merge pull request #11414 from Turbo87/trustpub-docs
Add Trusted Publishing documentation
2 parents 45ccc62 + 012fe63 commit da57d50

File tree

4 files changed

+142
-7
lines changed

4 files changed

+142
-7
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/styles/crate/settings/index.module.css

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,14 @@
1-
.owners-header, .trusted-publishing-header {
1+
.header {
22
display: flex;
33
justify-content: space-between;
44
align-items: center;
5+
flex-wrap: wrap;
6+
gap: var(--space-s);
7+
margin: var(--space-m) 0;
8+
9+
> h2 {
10+
margin: 0;
11+
}
512
}
613

714
.email-form {

‎app/templates/crate/settings/index.hbs

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
<CrateHeader @crate={{this.crate}} />
44

5-
<div local-class="owners-header">
5+
<div local-class="header">
66
<h2>Owners</h2>
77
{{#unless this.addOwnerVisible}}
88
<button type="button" class="button button--small" data-test-add-owner-button {{on "click" this.showAddOwnerForm}}>Add Owner</button>
@@ -56,11 +56,16 @@
5656

5757
{{! The "Trusted Publishing" section is hidden for now until we make this feature publicly available. }}
5858
{{#if this.githubConfigs}}
59-
<div local-class="trusted-publishing-header">
59+
<div local-class="header">
6060
<h2>Trusted Publishing</h2>
61-
<LinkTo @route="crate.settings.new-trusted-publisher" class="button button--small" data-test-add-trusted-publisher-button>
62-
Add
63-
</LinkTo>
61+
<div>
62+
<LinkTo @route="docs.trusted-publishing" class="button button--tan button--small" data-test-trusted-publishing-docs-button>
63+
Learn more
64+
</LinkTo>
65+
<LinkTo @route="crate.settings.new-trusted-publisher" class="button button--small" data-test-add-trusted-publisher-button>
66+
Add
67+
</LinkTo>
68+
</div>
6469
</div>
6570

6671
<table local-class="trustpub" data-test-trusted-publishing>
@@ -95,7 +100,7 @@
95100
</table>
96101
{{/if}}
97102

98-
<h2>Danger Zone</h2>
103+
<h2 local-class="header">Danger Zone</h2>
99104

100105
<div>
101106
<LinkTo @route="crate.delete" class="button button--red" data-test-delete-button>

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

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
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>. This example workflow will automatically publish your crate each time you push a version tag (like <code>v1.0.0</code>):
66+
</p>
67+
68+
{{!-- template-lint-disable no-whitespace-for-layout --}}
69+
<pre><code class="language-yaml" {{highlight-syntax}}>name: Publish to crates.io
70+
on:
71+
push:
72+
tags: ['v*'] # Triggers when pushing tags starting with 'v'
73+
jobs:
74+
publish:
75+
runs-on: ubuntu-latest
76+
environment: release # Optional: for enhanced security
77+
permissions:
78+
id-token: write # Required for OIDC token exchange
79+
contents: read # Required to checkout repository
80+
steps:
81+
- uses: actions/checkout@v4
82+
- uses: rust-lang/crates-io-auth-action@v1
83+
id: auth
84+
- run: cargo publish
85+
env:
86+
CARGO_REGISTRY_TOKEN: $\{{ steps.auth.outputs.token }}</code></pre>
87+
88+
<p>
89+
<strong>Optional:</strong> For enhanced security, create a GitHub Actions environment named "release"
90+
in your repository settings with protection rules like required reviewers or deployment branches.
91+
</p>
92+
93+
<h2>Security &amp; Best Practices</h2>
94+
<ul>
95+
<li><strong>Use specific workflow filenames</strong> to reduce the attack surface</li>
96+
<li><strong>Use GitHub Actions environments</strong> with protection rules for sensitive publishing</li>
97+
<li><strong>Limit workflow triggers</strong> to specific tags or protected branches</li>
98+
<li><strong>Review all actions used</strong> in your release workflow</li>
99+
<li><strong>Monitor publishing activities</strong> through crates.io email notifications</li>
100+
</ul>
101+
102+
<p>
103+
<strong>How it works:</strong> GitHub Actions generates an OIDC token that proves your workflow's identity.
104+
The <code>rust-lang/crates-io-auth-action</code> exchanges this for a 30-minute access token that
105+
<code>cargo publish</code> uses automatically.
106+
</p>
107+
108+
<h2>Migration from API Tokens</h2>
109+
<p>
110+
To migrate from API tokens: set up Trusted Publishing following the steps above, test it,
111+
then remove the API token from your repository secrets. Both methods can be used simultaneously during transition.
112+
</p>
113+
114+
<h2>Additional Resources</h2>
115+
<ul>
116+
<li><a href="https://rust-lang.github.io/rfcs/3691-trusted-publishing-cratesio.html">RFC 3691: Trusted Publishing for crates.io</a></li>
117+
<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>
118+
<li><a href="https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment">GitHub: Using environments for deployment</a></li>
119+
</ul>
120+
</TextContent>

0 commit comments

Comments
 (0)