Skip to content

Commit 7db1b8b

Browse files
pankgeorgpankgeorg
committed
ci(release): take 2
1 parent 8f528a1 commit 7db1b8b

2 files changed

Lines changed: 195 additions & 3 deletions

File tree

‎.github/workflows/release.yml‎

Lines changed: 20 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,13 @@ on:
44
push:
55
branches:
66
- main # semantic-release works on branch pushes, not tags
7+
workflow_dispatch: # Allow manual trigger
8+
inputs:
9+
dry_run:
10+
description: 'Run in dry-run mode (no actual release)'
11+
required: false
12+
type: boolean
13+
default: false
714

815
permissions:
916
contents: write # Required for creating releases and pushing commits
@@ -27,7 +34,8 @@ jobs:
2734
uses: actions/checkout@v4
2835
with:
2936
fetch-depth: 0 # Fetch all history for semantic-release
30-
persist-credentials: false # Use custom token for pushing
37+
token: ${{ secrets.GH_PAT || secrets.GITHUB_TOKEN }}
38+
persist-credentials: true # Need credentials for semantic-release to push
3139

3240
- name: Setup Node.js
3341
uses: actions/setup-node@v4
@@ -53,10 +61,19 @@ jobs:
5361
5462
- name: Run semantic-release
5563
env:
56-
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
64+
GITHUB_TOKEN: ${{ secrets.GH_PAT || secrets.GITHUB_TOKEN }}
5765
VSCE_PAT: ${{ secrets.VSCE_PAT }}
66+
GIT_AUTHOR_NAME: github-actions[bot]
67+
GIT_AUTHOR_EMAIL: github-actions[bot]@users.noreply.github.com
68+
GIT_COMMITTER_NAME: github-actions[bot]
69+
GIT_COMMITTER_EMAIL: github-actions[bot]@users.noreply.github.com
5870
run: |
59-
npx semantic-release
71+
if [ "${{ github.event.inputs.dry_run }}" = "true" ]; then
72+
echo "Running in dry-run mode..."
73+
npx semantic-release --dry-run
74+
else
75+
npx semantic-release
76+
fi
6077
6178
- name: Upload VSIX to release (fallback if semantic-release fails)
6279
if: failure()

‎docs/RELEASE_SETUP.md‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
# Release Setup Guide
2+
3+
This document explains how to configure releases for the Pluto Notebook extension with protected main branch.
4+
5+
## Problem
6+
7+
When the `main` branch is protected, semantic-release cannot push version bump commits directly, causing the release workflow to fail.
8+
9+
## Solution
10+
11+
We use a Personal Access Token (PAT) with bypass permissions to allow semantic-release to push to protected branches.
12+
13+
## Setup Instructions
14+
15+
### 1. Create a Personal Access Token (PAT)
16+
17+
1. Go to GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens
18+
2. Click "Generate new token"
19+
3. Configure the token:
20+
- **Name**: `semantic-release-bypass` (or similar)
21+
- **Expiration**: Set as needed (recommend 1 year)
22+
- **Repository access**: Select "Only select repositories" → Choose this repository
23+
- **Permissions**:
24+
- **Repository permissions**:
25+
- Contents: Read and write
26+
- Pull requests: Read and write
27+
- Issues: Read and write
28+
- Metadata: Read-only (automatically selected)
29+
30+
4. Click "Generate token" and copy the token value
31+
32+
### 2. Add Token as Repository Secret
33+
34+
1. Go to your repository on GitHub
35+
2. Navigate to Settings → Secrets and variables → Actions
36+
3. Click "New repository secret"
37+
4. Add:
38+
- **Name**: `GH_PAT`
39+
- **Secret**: Paste the token you created
40+
41+
### 3. Configure Branch Protection Rules
42+
43+
1. Go to Settings → Branches → Branch protection rules
44+
2. Edit the rule for `main`
45+
3. Enable "Allow specified actors to bypass required pull requests"
46+
4. Add the GitHub Actions bot or your PAT user to the bypass list
47+
48+
Alternatively, you can allow the GitHub Actions bot to bypass protection:
49+
- In branch protection, check "Do not allow bypassing the above settings" = OFF
50+
- Or specifically allow `github-actions[bot]` to bypass
51+
52+
### 4. Workflow Configuration
53+
54+
The release workflow (`.github/workflows/release.yml`) is configured to:
55+
56+
- Use `GH_PAT` if available, fall back to `GITHUB_TOKEN`
57+
- Allow manual triggering via `workflow_dispatch`
58+
- Support dry-run mode for testing
59+
- Set proper git committer information
60+
61+
## Manual Release Trigger
62+
63+
You can manually trigger a release from the GitHub Actions tab:
64+
65+
1. Go to Actions → Release workflow
66+
2. Click "Run workflow"
67+
3. Choose options:
68+
- **Branch**: main
69+
- **Dry run**: Check to test without creating a release
70+
4. Click "Run workflow"
71+
72+
## Testing the Setup
73+
74+
### Dry Run Test
75+
76+
```bash
77+
# Manually trigger with dry-run from GitHub UI
78+
# OR locally test semantic-release:
79+
npx semantic-release --dry-run
80+
```
81+
82+
### Check Configuration
83+
84+
```bash
85+
# Verify git credentials in workflow
86+
git config user.name
87+
git config user.email
88+
```
89+
90+
## How It Works
91+
92+
1. **Token Priority**: Workflow uses `GH_PAT` secret if available, otherwise `GITHUB_TOKEN`
93+
2. **Credentials**: Checkout action uses the PAT to authenticate git operations
94+
3. **Git Identity**: Workflow sets git author/committer to `github-actions[bot]`
95+
4. **Bypass**: PAT with proper permissions can push to protected branches
96+
5. **Manual Trigger**: `workflow_dispatch` allows on-demand releases
97+
98+
## Semantic Release Flow
99+
100+
When the workflow runs:
101+
102+
1. CI runs (lint, test, build)
103+
2. Checkout with PAT credentials
104+
3. Build VSIX package
105+
4. Run semantic-release:
106+
- Analyzes commits since last release
107+
- Determines version bump (major/minor/patch)
108+
- Updates package.json and CHANGELOG.md
109+
- Creates git tag
110+
- Pushes commit and tag (using PAT)
111+
- Creates GitHub release with VSIX attached
112+
113+
## Alternative: No Version Commits
114+
115+
If you prefer not to push version commits to main, update `.releaserc.json`:
116+
117+
```json
118+
{
119+
"branches": ["main"],
120+
"plugins": [
121+
"@semantic-release/commit-analyzer",
122+
"@semantic-release/release-notes-generator",
123+
["@semantic-release/changelog", { "changelogFile": "CHANGELOG.md" }],
124+
["@semantic-release/npm", { "npmPublish": false }],
125+
["semantic-release-vsce", { "packageVsix": true }],
126+
[
127+
"@semantic-release/github",
128+
{
129+
"assets": [
130+
{ "path": "*.vsix", "label": "VS Code Extension (VSIX)" },
131+
{ "path": "CHANGELOG.md", "label": "Changelog" }
132+
]
133+
}
134+
]
135+
// Remove @semantic-release/git to skip version commits
136+
]
137+
}
138+
```
139+
140+
This creates releases without pushing version bumps back to main.
141+
142+
## Troubleshooting
143+
144+
### "refusing to allow a Personal Access Token to create or update workflow"
145+
146+
Solution: The PAT needs "Workflows" permission. Recreate the token with this permission added.
147+
148+
### "protected branch hook declined"
149+
150+
Solution: Ensure the PAT user or github-actions[bot] is in the bypass list for branch protection.
151+
152+
### "Author identity unknown"
153+
154+
Solution: The workflow sets `GIT_AUTHOR_NAME` and `GIT_AUTHOR_EMAIL` environment variables. Check they're properly configured.
155+
156+
### Dry-run succeeds but real run fails
157+
158+
Check:
159+
1. `GH_PAT` secret is properly set
160+
2. PAT has not expired
161+
3. PAT has correct permissions
162+
4. Branch protection allows bypass
163+
164+
## Security Notes
165+
166+
- **PAT Security**: Store PAT only as a GitHub secret, never commit it
167+
- **Token Scope**: Use fine-grained tokens with minimal required permissions
168+
- **Expiration**: Set reasonable expiration dates and rotate tokens regularly
169+
- **Audit**: Review GitHub audit logs for PAT usage
170+
171+
## References
172+
173+
- [Semantic Release GitHub Action](https://github.com/semantic-release/semantic-release/blob/master/docs/recipes/ci-configurations/github-actions.md)
174+
- [GitHub PAT Documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)
175+
- [Branch Protection Bypass](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches)

0 commit comments

Comments
 (0)