Skip to content

Commit ea28376

Browse files
CopilotNoopDog
Copilot
and
NoopDog
authored
Enable trusted publishing for npm releases (#723)
* Initial plan * feat: enable trusted publishing for npm releases - Add id-token: write permission for OIDC authentication - Configure setup-node with always-auth for trusted publishing - Remove NODE_AUTH_TOKEN secret usage - Add provenance and access flags to npm publish command - Add comprehensive documentation in docs/TRUSTED_PUBLISHING.md Co-authored-by: NoopDog <3239697+NoopDog@users.noreply.github.com> * docs: add safety note about removing npm secret Co-authored-by: NoopDog <3239697+NoopDog@users.noreply.github.com> * style: run prettier on TRUSTED_PUBLISHING.md Co-authored-by: NoopDog <3239697+NoopDog@users.noreply.github.com> * fix: apply prettier 2.8.3 formatting (#0) Use project's prettier version (2.8.3) instead of npx version (3.7.4) to ensure consistent formatting with CI checks. --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: NoopDog <3239697+NoopDog@users.noreply.github.com>
1 parent 6cf79a9 commit ea28376

File tree

2 files changed

+136
-3
lines changed

2 files changed

+136
-3
lines changed

‎.github/workflows/release-please.yml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ on:
77
permissions:
88
contents: write
99
pull-requests: write
10+
id-token: write # Required for trusted publishing to npm
1011

1112
name: release-please
1213

@@ -29,6 +30,7 @@ jobs:
2930
with:
3031
node-version: "22.12.0"
3132
registry-url: "https://registry.npmjs.org"
33+
always-auth: true # Enable authentication for trusted publishing
3234

3335
- name: Install dependencies
3436
if: ${{ steps.release.outputs.release_created }}
@@ -40,6 +42,4 @@ jobs:
4042

4143
- name: Publish to NPM
4244
if: ${{ steps.release.outputs.release_created }}
43-
run: npm publish
44-
env:
45-
NODE_AUTH_TOKEN: ${{ secrets.DATABIOSPHERE_FINDABLE_UI_NPM_PUBLISH_TOKEN }} # Ensure this token is scoped to only the permissions required for npm publication to limit security risks.
45+
run: npm publish --provenance --access public

‎docs/TRUSTED_PUBLISHING.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# Trusted Publishing Setup for NPM
2+
3+
This repository uses GitHub's trusted publishing workflow to securely publish packages to npm without using long-lived access tokens.
4+
5+
## What is Trusted Publishing?
6+
7+
Trusted publishing is a security feature that allows GitHub Actions to publish packages to npm using short-lived, automatically generated tokens via OpenID Connect (OIDC). This eliminates the need to store long-lived npm tokens as repository secrets, reducing the attack surface and improving supply chain security.
8+
9+
## Configuration
10+
11+
### GitHub Actions Workflow
12+
13+
The `.github/workflows/release-please.yml` workflow is configured with the following settings for trusted publishing:
14+
15+
#### Required Permissions
16+
17+
```yaml
18+
permissions:
19+
contents: write # Required for release-please to create releases
20+
pull-requests: write # Required for release-please to create PRs
21+
id-token: write # Required for trusted publishing to npm
22+
```
23+
24+
The `id-token: write` permission enables the workflow to request OIDC tokens from GitHub's OIDC provider.
25+
26+
#### Node.js Setup
27+
28+
```yaml
29+
- uses: actions/setup-node@v4
30+
with:
31+
node-version: "22.12.0"
32+
registry-url: "https://registry.npmjs.org"
33+
always-auth: true # Enable authentication for trusted publishing
34+
```
35+
36+
The `always-auth: true` setting ensures that authentication is enabled when publishing packages.
37+
38+
#### Publishing with Provenance
39+
40+
```yaml
41+
- name: Publish to NPM
42+
run: npm publish --provenance --access public
43+
```
44+
45+
The `--provenance` flag enables build provenance, which creates a publicly verifiable link between the package and its source code and build. The `--access public` flag ensures the package is published as public.
46+
47+
## NPM Setup Requirements
48+
49+
To enable trusted publishing for this package on npm, you need to:
50+
51+
1. **Log in to npm** and navigate to the package settings for `@databiosphere/findable-ui`
52+
2. **Add a GitHub Actions Publishing Workflow**:
53+
54+
- Go to the package's publishing settings
55+
- Click "Add GitHub Actions Publishing Workflow"
56+
- Configure the trusted publisher with:
57+
- **Repository**: `DataBiosphere/findable-ui`
58+
- **Workflow**: `.github/workflows/release-please.yml`
59+
- **Environment**: (leave blank, no environment is used)
60+
61+
3. **Verify the Configuration**:
62+
- Ensure the trusted publisher is listed in the package settings
63+
- The workflow will use OIDC to authenticate automatically when publishing
64+
65+
## Security Benefits
66+
67+
- **No Long-Lived Tokens**: Eliminates the need to store npm access tokens as GitHub secrets
68+
- **Automatic Rotation**: Tokens are short-lived and automatically generated for each workflow run
69+
- **Build Provenance**: The `--provenance` flag creates verifiable attestations linking the package to its source
70+
- **Reduced Attack Surface**: Compromised secrets cannot be used outside the workflow context
71+
- **Audit Trail**: All publishes are tied to specific GitHub Actions workflow runs
72+
73+
## Migration Notes
74+
75+
### Removed Configuration
76+
77+
The following configuration is no longer needed with trusted publishing:
78+
79+
- **Repository Secret**: `DATABIOSPHERE_FINDABLE_UI_NPM_PUBLISH_TOKEN` - This secret can be safely removed from the repository settings as it is no longer used. **Important**: Only remove this secret after confirming the trusted publishing workflow works successfully in production to avoid disrupting the release process.
80+
- **NODE_AUTH_TOKEN Environment Variable**: No longer required in the publish step
81+
82+
### Workflow Changes
83+
84+
1. Added `id-token: write` permission
85+
2. Added `always-auth: true` to `setup-node` action
86+
3. Removed `NODE_AUTH_TOKEN` environment variable from publish step
87+
4. Added `--provenance` and `--access public` flags to `npm publish`
88+
89+
## Testing
90+
91+
To test the trusted publishing workflow:
92+
93+
1. Create a test commit on a feature branch
94+
2. Merge to the `main` branch
95+
3. If the commit triggers a release (based on conventional commits), the workflow will:
96+
- Create a release PR via release-please
97+
- Once merged, create a GitHub release
98+
- Automatically publish to npm using trusted publishing
99+
100+
Monitor the workflow run in the Actions tab to verify successful publication.
101+
102+
## References
103+
104+
- [npm Trusted Publishers Documentation](https://docs.npmjs.com/trusted-publishers)
105+
- [GitHub: Publishing Node.js Packages](https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages/publishing-nodejs-packages-from-github-actions)
106+
- [npm Provenance Documentation](https://docs.npmjs.com/generating-provenance-statements)
107+
- [OpenID Connect in GitHub Actions](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
108+
109+
## Troubleshooting
110+
111+
### Publishing Fails with Authentication Error
112+
113+
If the workflow fails with an authentication error:
114+
115+
1. Verify that trusted publishing is properly configured on npm for the package
116+
2. Ensure the repository, workflow path, and environment (if any) match exactly in the npm settings
117+
3. Confirm that the workflow has the `id-token: write` permission
118+
119+
### Provenance Attestation Not Generated
120+
121+
If the package is published but provenance is not attached:
122+
123+
1. Ensure the `--provenance` flag is included in the `npm publish` command
124+
2. Verify that the workflow has `id-token: write` permission
125+
3. Check that the package is being published from a supported environment (GitHub Actions)
126+
127+
### Package Access Issues
128+
129+
If the package fails to publish due to access issues:
130+
131+
1. Ensure the `--access public` flag is set (for public packages)
132+
2. Verify that the npm package settings allow public access
133+
3. Confirm that the organization and package name are correct

0 commit comments

Comments
 (0)