Skip to content

Commit e692f2e

Browse files
tenphitenphi
authored
chore: update github actions (#926)
1 parent cb6340e commit e692f2e

File tree

4 files changed

+378
-116
lines changed

4 files changed

+378
-116
lines changed

‎.github/PUBLISHING.md‎

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
# Publishing CI/CD Documentation
2+
3+
This document describes how the npm publishing workflows operate and the manual steps required for setup.
4+
5+
## Current Behavior (User Perspective)
6+
7+
### On Pull Request
8+
9+
When you create or update a pull request:
10+
11+
1. **Canary Release** — A canary version is automatically published to npm
12+
- Version format: `0.0.0-canary-<short-sha>`
13+
- npm tag: `pr_<pr-number>` (e.g., `pr_123`)
14+
- A comment is posted to the PR with the npm link:
15+
> Deployed canary version [0.0.0-canary-abc1234](https://www.npmjs.com/package/@cube-dev/ui-kit/v/0.0.0-canary-abc1234)
16+
- Install via: `npm install @cube-dev/ui-kit@pr_<pr-number>`
17+
18+
2. **Tests & Lint** — Linting and unit tests run in parallel
19+
20+
3. **Storybook Review** — Storybook is deployed to Chromatic for visual review
21+
- A comment is posted with review and preview links
22+
23+
4. **Size Limit** — Bundle size is measured and reported in a PR comment
24+
25+
### On Push to `main` Branch
26+
27+
When changes are pushed to `main` (typically via merged PRs):
28+
29+
1. **Changesets Processing** — The workflow checks for pending changesets:
30+
31+
**If there are pending changesets:**
32+
- A "Release Pull Request" is created/updated automatically
33+
- This PR contains version bumps and changelog updates
34+
- No npm publish happens yet
35+
36+
**If there are no pending changesets (Release PR was just merged):**
37+
- The package is built and published to npm
38+
- Uses the version specified in `package.json` (updated by the Release PR)
39+
- Published with the `latest` tag
40+
41+
2. **Storybook Deployment** — If no publish happened, Storybook is deployed to Chromatic production
42+
- Auto-accepts visual changes since this is the main branch
43+
44+
### Release Workflow Summary
45+
46+
```
47+
Developer creates PR → Canary published → PR merged to main
48+
↓
49+
Has pending changesets?
50+
├── Yes → Create/update Release PR
51+
└── No → Publish to npm
52+
```
53+
54+
## Ignored Paths
55+
56+
Pull request workflows are skipped for changes only in:
57+
- `.changeset/**`
58+
- `.husky/**`
59+
60+
---
61+
62+
## Trusted Publishing Migration
63+
64+
### What Changed
65+
66+
Publishing logic has been moved to a dedicated `publish.yml` workflow file to support npm's [Trusted Publishing](https://docs.npmjs.com/trusted-publishers) feature.
67+
68+
### Benefits
69+
70+
- **No more NPM_TOKEN secret** — Authentication uses OIDC tokens
71+
- **Automatic provenance** — npm automatically generates provenance attestations
72+
- **Enhanced security** — Short-lived tokens instead of long-lived secrets
73+
- **Audit trail** — Cryptographic proof of build origin
74+
75+
---
76+
77+
## Manual Setup Steps
78+
79+
Complete these steps **before** merging the trusted publishing changes:
80+
81+
### Step 1: Configure Trusted Publisher on npmjs.com
82+
83+
> ⚠️ **Important**: This must be done BEFORE the first publish attempt with the new workflow.
84+
85+
1. Log in to [npmjs.com](https://www.npmjs.com) with an account that has publish access
86+
2. Go to: https://www.npmjs.com/package/@cube-dev/ui-kit/settings
87+
3. Scroll to the **"Trusted Publisher"** section
88+
4. Click the **"GitHub Actions"** button
89+
5. Fill in the configuration **exactly** as shown:
90+
91+
| Field | Value |
92+
|-------|-------|
93+
| Organization or user | `cube-js` |
94+
| Repository | `cube-ui-kit` |
95+
| Workflow filename | `publish.yml` |
96+
| Environment name | _(leave empty)_ |
97+
98+
6. Click **Save** (or the equivalent button)
99+
100+
### Step 2: Verify the Setup with a Test PR
101+
102+
1. Create a test branch and PR with minimal changes
103+
2. Watch the GitHub Actions for the canary release job
104+
3. Verify the canary package appears on npm with the correct version
105+
4. Check that provenance badge appears on the npm package page
106+
107+
### Step 3: Test Full Release Flow
108+
109+
1. Add a changeset to your test branch: `pnpm changeset`
110+
2. Merge the test PR to `main`
111+
3. Verify a "Release Pull Request" is created automatically
112+
4. Merge the Release PR
113+
5. Verify the package is published with:
114+
- Correct version
115+
- Provenance attestation (visible on npm package page)
116+
117+
### Step 4: (Recommended) Restrict Token Access
118+
119+
After verifying trusted publishing works for both canary and release:
120+
121+
1. Go to npm package settings → **Publishing access**
122+
2. Select **"Require two-factor authentication and disallow tokens"**
123+
3. Click **Update Package Settings**
124+
125+
> This prevents accidental token-based publishes and enhances security.
126+
127+
### Step 5: Clean Up NPM_TOKEN Secret
128+
129+
Once everything is working:
130+
131+
1. Go to GitHub repo: Settings → Secrets and variables → Actions
132+
2. Delete the `NPM_TOKEN` secret
133+
3. This is optional but recommended for security
134+
135+
> ⚠️ Keep the token until you're 100% confident the new setup works.
136+
137+
---
138+
139+
## Workflow Files
140+
141+
| File | Purpose |
142+
|------|---------|
143+
| `publish.yml` | Reusable workflow for npm publishing (canary and release) |
144+
| `main.yml` | Release workflow triggered on push to main |
145+
| `pull-request.yml` | PR workflow for tests, canary releases, and Chromatic |
146+
| `size-limit.yml` | Bundle size measurement |
147+
| `codeql-analysis.yml` | Security analysis |
148+
149+
---
150+
151+
## Pre-Merge Checklist
152+
153+
Before merging the trusted publishing PR, verify:
154+
155+
- [ ] You have maintainer access to the package on npmjs.com (to configure trusted publisher)
156+
- [ ] Trusted publisher configured on npmjs.com for `publish.yml`
157+
- [ ] Configuration matches exactly: `cube-js/cube-ui-kit/publish.yml`
158+
159+
---
160+
161+
## Troubleshooting
162+
163+
### "Unable to authenticate" error
164+
165+
- Verify the workflow filename matches **exactly** (`publish.yml`, not `Publish.yml`)
166+
- Ensure all fields are case-sensitive and match exactly
167+
- Check that you're using GitHub-hosted runners (not self-hosted)
168+
- Verify the repository and organization names are correct (`cube-js`, `cube-ui-kit`)
169+
170+
### Provenance not generated
171+
172+
- Provenance is only generated for **public** repositories
173+
- Ensure the package is public
174+
- Private repositories cannot generate provenance even for public packages
175+
176+
### Canary releases failing
177+
178+
- Check that the workflow has `id-token: write` permission
179+
- Verify the trusted publisher is configured for `publish.yml`
180+
- Ensure npm version is 11.5.1+ (the workflow updates this automatically)
181+
182+
### Changesets action not publishing
183+
184+
- Changesets action uses npm internally, so trusted publishing should work
185+
- If issues persist, check GitHub Actions logs for OIDC token errors
186+
- Verify `GITHUB_TOKEN` is passed (needed for creating Release PRs)
187+
188+
### Workflow file validation failed
189+
190+
npm does not validate the trusted publisher configuration when you save it. Double-check:
191+
- Repository name matches exactly
192+
- Organization/username matches exactly
193+
- Workflow filename includes `.yml` extension
194+
- No trailing spaces in any field

‎.github/workflows/main.yml‎

Lines changed: 10 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -8,54 +8,19 @@ on:
88
concurrency: ${{ github.workflow }}-${{ github.ref }}
99

1010
permissions:
11-
contents: write # Read-only access to repository contents
12-
issues: write # Write access to issues
13-
pull-requests: write # Write access to pull requests
14-
statuses: write # Write access to commit statuses
11+
contents: write
12+
issues: write
13+
pull-requests: write
14+
statuses: write
15+
id-token: write # Required for trusted publishing (OIDC)
1516

1617
jobs:
1718
publish:
18-
runs-on: ubuntu-latest
19-
env:
20-
NODE_OPTIONS: --max-old-space-size=4096
21-
outputs:
22-
published: ${{ steps.changesets.outputs.published }}
23-
steps:
24-
- uses: actions/checkout@v4
25-
26-
- name: Update Corepack
27-
run: npm i -g corepack@latest
28-
29-
- name: Enable Corepack (pre)
30-
run: corepack enable
31-
32-
- name: Prepare pnpm (pre)
33-
run: corepack prepare [email protected] --activate
34-
35-
- name: Setup Node.js
36-
uses: actions/setup-node@v4
37-
with:
38-
node-version-file: '.nvmrc'
39-
cache: 'pnpm'
40-
41-
- name: Enable Corepack
42-
run: corepack enable
43-
44-
- name: Prepare pnpm
45-
run: corepack prepare [email protected] --activate
46-
47-
- name: Install Dependencies
48-
run: pnpm install
49-
50-
- name: Create Release Pull Request or Publish to npm
51-
id: changesets
52-
uses: changesets/action@v1
53-
with:
54-
publish: pnpm release
55-
commit: 'chore: release'
56-
env:
57-
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
58-
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
19+
name: 'Publish release'
20+
uses: ./.github/workflows/publish.yml
21+
with:
22+
publish-type: release
23+
secrets: inherit
5924

6025
deploy-chromatic:
6126
name: 'Deploy storybook to Chromatic'

0 commit comments

Comments
 (0)