Github Release

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)

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:

# 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

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:

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

If missing sections, add them before release.

5. Check .gitignore

Verify essential patterns are present:

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

6. Build Test (non-blocking)

npm run build 2>&1

7. Dependency Audit (non-blocking)

npm audit --audit-level=high

8. Create Sanitization Commit

If any changes were made during sanitization:

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

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

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

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

5. Create GitHub Release

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

Release Workflow

Detailed reference for the tag-push-release mechanics.

Version Detection

Check package.json first:

node -p "require('./package.json').version" 2>/dev/null

If no package.json, ask user for version. Always prefix with v (e.g., v1.0.0).

Monorepo Tags

In monorepos, use scoped tags:

# Single repo
git tag -a v1.0.0 -m "Release v1.0.0"

# Monorepo
git tag -a mypackage-v1.0.0 -m "Release mypackage v1.0.0"

Tag Conflicts

If tag already exists locally:

# Delete local tag
git tag -d v1.0.0

# If also on remote (dangerous — confirm with user)
git push origin :refs/tags/v1.0.0

Push Sequence

Always push branch first, then tags:

BRANCH=$(git branch --show-current)
git push origin ${BRANCH}
git push origin --tags

If push fails:

• Set upstream: git push -u origin ${BRANCH}
• Check auth: gh auth status
• Verify remote: git remote -v

Release Notes

Generate from commits since last tag:

LAST_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")

if [ -z "$LAST_TAG" ]; then
  git log --oneline --no-merges HEAD
else
  git log --oneline --no-merges ${LAST_TAG}..HEAD
fi

Format as markdown bullet list under ## What's New.

gh release create

# Standard release
gh release create v1.0.0 --title "Release v1.0.0" --notes "## What's New
- Feature A
- Bug fix B"

# Pre-release (beta/rc)
gh release create v1.0.0-beta.1 --title "v1.0.0 Beta 1" --notes "..." --prerelease

# Draft (not published)
gh release create v1.0.0 --title "Release v1.0.0" --notes "..." --draft

Post-Release

Depending on project type:

• npm package: npm publish
• Announce: Social media, relevant communities
• Update docs: Ensure README references latest version

Safety Checklist

Pre-release safety checks for public repositories.

Blockers (must pass)

Warnings (should fix)

Common Secret Patterns

Package.json Fields

For npm packages, verify these fields before publish:

{
  "name": "@scope/package",
  "version": "1.0.0",
  "description": "Clear description",
  "license": "MIT",
  "repository": { "type": "git", "url": "https://github.com/..." },
  "keywords": ["relevant", "terms"]
}