github-release

jezweb ｜ 部署與發布 ｜ 原文 ｜ MIT

先清掉 secret 和個人檔案，再打 tag 發布 GitHub release

---
name: github-release
description: "準備並發布 GitHub release。會先把程式碼清理到適合公開發布（掃 secret、清個人檔案、檢查 LICENSE/README），建立版本 tag，再用 gh CLI 發布。用 'release'、'publish'、'open source'、'prepare for release'、'create release' 或 'github release' 觸發。"
compatibility: claude-code-only
---

# GitHub Release

把專案清理乾淨並 release 到 GitHub。分兩階段：先做安全檢查，再打 tag 發布。

## 前置條件

- 已安裝 `gh` CLI 並完成認證（`gh auth status`）
- 已安裝 `gitleaks` 用來掃 secret（`brew install gitleaks` 或從 GitHub 下載）
- Git repository 已設定 remote

## 工作流程

### 階段 1：清理

任何公開發布之前都要先跑這些檢查。遇到 blocker 就停。

#### 1. 掃描 secret（BLOCKER）

```bash
gitleaks detect --no-git --source=. --verbose
```

如果找到 secret：**停下來**。把 secret 移掉，改放環境變數。用 `git log -S "secret_value"` 檢查 git 歷史，如果歷史裡有，就用 BFG Repo-Cleaner。

如果沒裝 gitleaks，就手動檢查：

```bash
# Check for .env files
find . -name ".env*" -not -path "*/node_modules/*"

# Check config files for hardcoded secrets
grep -ri "api_key\|token\|secret\|password" wrangler.toml wrangler.jsonc .dev.vars 2>/dev/null
```

#### 2. 移除個人檔案

檢查並移除不該發布的 session/規劃檔案：

- `SESSION.md`：session 狀態
- `planning/`、`screenshots/`：工作用資料夾
- `test-*.ts`、`test-*.js`：本機測試檔

要嘛刪掉，要嘛加進 `.gitignore`。

#### 3. 驗證 LICENSE

```bash
ls LICENSE LICENSE.md LICENSE.txt 2>/dev/null
```

如果沒有：建立一個。先看 repo 的可見度（`gh repo view --json visibility -q '.visibility'`）。public repo 用 MIT。private repo 可以考慮改用專有授權。

#### 4. 驗證 README

檢查 README 存在，而且有基本的章節：

```bash
grep -i "## Install\|## Usage\|## License" README.md
```

缺章節的話，release 前先補上。

#### 5. 檢查 .gitignore

確認必要的規則都在：

```bash
grep -E "node_modules|\.env|dist/|\.dev\.vars" .gitignore
```

#### 6. Build 測試（不擋 release）

```bash
npm run build 2>&1
```

#### 7. 相依套件稽核（不擋 release）

```bash
npm audit --audit-level=high
```

#### 8. 建立清理 commit

如果清理過程有任何改動：

```bash
git add -A
git commit -m "chore: prepare for release"
```

### 階段 2：發布

#### 1. 決定版本

看 `package.json` 目前的版本，或問使用者。確保版本號以 `v` 開頭。

#### 2. 確認 tag 不存在

```bash
git tag -l "v[version]"
```

如果已存在，問使用者要刪掉重建還是換一個版本。

#### 3. 顯示這次要發布的內容

```bash
LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
if [ -z "$LAST_TAG" ]; then
  git log --oneline --no-merges HEAD | head -20
else
  git log --oneline --no-merges ${LAST_TAG}..HEAD
fi
```

#### 4. 建立 tag 並 push

```bash
git tag -a v[version] -m "Release v[version]"
git push origin $(git branch --show-current)
git push origin --tags
```

#### 5. 建立 GitHub Release

```bash
gh release create v[version] \
  --title "Release v[version]" \
  --notes "[auto-generated from commits]"
```

預先發布版加 `--prerelease`，草稿加 `--draft`。

#### 6. 回報

給使用者看：
- Release 網址
- 後續步驟（有的話，像是 npm publish、對外公告）

## 參考檔案

| 什麼時候 | 讀什麼 |
|------|------|
| 詳細的安全檢查 | [references/safety-checklist.md](references/safety-checklist.md) |
| Release 的實際流程 | [references/release-workflow.md](references/release-workflow.md) |

---
name: github-release
description: "Prepare and publish GitHub releases. Sanitizes code for public release (secrets scan, personal artifacts, LICENSE/README validation), creates version tags, and publishes via gh CLI. Trigger with 'release', 'publish', 'open source', 'prepare for release', 'create release', or 'github release'."
compatibility: claude-code-only
---

# GitHub Release

Sanitize and release projects to GitHub. Two-phase workflow: safety checks first, then tag and publish.

## Prerequisites

- `gh` CLI installed and authenticated (`gh auth status`)
- `gitleaks` installed for secrets scanning (`brew install gitleaks` or download from GitHub)
- Git repository with a remote configured

## Workflow

### Phase 1: Sanitize

Run these checks before any public release. Stop on blockers.

#### 1. Scan for Secrets (BLOCKER)

```bash
gitleaks detect --no-git --source=. --verbose
```

If secrets found: **STOP**. Remove secrets, move to environment variables. Check git history with `git log -S "secret_value"` — if in history, use BFG Repo-Cleaner.

If gitleaks not installed, do manual checks:

```bash
# Check for .env files
find . -name ".env*" -not -path "*/node_modules/*"

# Check config files for hardcoded secrets
grep -ri "api_key\|token\|secret\|password" wrangler.toml wrangler.jsonc .dev.vars 2>/dev/null
```

#### 2. Remove Personal Artifacts

Check for and remove session/planning files that shouldn't be published:

- `SESSION.md` — session state
- `planning/`, `screenshots/` — working directories
- `test-*.ts`, `test-*.js` — local test files

Either delete them or add to `.gitignore`.

#### 3. Validate LICENSE

```bash
ls LICENSE LICENSE.md LICENSE.txt 2>/dev/null
```

If missing: create one. Check the repo visibility (`gh repo view --json visibility -q '.visibility'`). Use MIT for public repos. For private repos, consider a proprietary license instead.

#### 4. Validate README

Check README exists and has basic sections:

```bash
grep -i "## Install\|## Usage\|## License" README.md
```

If missing sections, add them before release.

#### 5. Check .gitignore

Verify essential patterns are present:

```bash
grep -E "node_modules|\.env|dist/|\.dev\.vars" .gitignore
```

#### 6. Build Test (non-blocking)

```bash
npm run build 2>&1
```

#### 7. Dependency Audit (non-blocking)

```bash
npm audit --audit-level=high
```

#### 8. Create Sanitization Commit

If any changes were made during sanitization:

```bash
git add -A
git commit -m "chore: prepare for release"
```

### Phase 2: Release

#### 1. Determine Version

Check `package.json` for current version, or ask the user. Ensure version starts with `v` prefix.

#### 2. Check Tag Doesn't Exist

```bash
git tag -l "v[version]"
```

If it exists, ask user whether to delete and recreate or use a different version.

#### 3. Show What's Being Released

```bash
LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
if [ -z "$LAST_TAG" ]; then
  git log --oneline --no-merges HEAD | head -20
else
  git log --oneline --no-merges ${LAST_TAG}..HEAD
fi
```

#### 4. Create Tag and Push

```bash
git tag -a v[version] -m "Release v[version]"
git push origin $(git branch --show-current)
git push origin --tags
```

#### 5. Create GitHub Release

```bash
gh release create v[version] \
  --title "Release v[version]" \
  --notes "[auto-generated from commits]"
```

For pre-releases add `--prerelease`. For drafts add `--draft`.

#### 6. Report

Show the user:
- Release URL
- Next steps (npm publish if applicable, announcements)

## Reference Files

| When | Read |
|------|------|
| Detailed safety checks | [references/safety-checklist.md](references/safety-checklist.md) |
| Release mechanics | [references/release-workflow.md](references/release-workflow.md) |