Deployment & Release Guide

October 2, 2025 ยท View on GitHub

This document explains how to create releases and deploy the Gapstars AI Setup package.

Overview

This repository uses GitHub Actions to automatically build and release the AI setup package. When you push a version tag, the workflow:

  1. Packages the Claude Code setup files (CLAUDE.md, README-CLAUDE-CODE.md, .claude/)
  2. Creates a GitHub Release with versioned artifacts
  3. Provides a stable URL for downloading the latest version

Creating a Release

Use the helper script to create and push a versioned tag:

# Patch release (0.0.X) - for bug fixes and small updates
./scripts/tag-release.sh patch

# Minor release (0.X.0) - for new features
./scripts/tag-release.sh minor

# Major release (X.0.0) - for breaking changes
./scripts/tag-release.sh major

The script will:

  • Calculate the next version number
  • Ask for confirmation
  • Create an annotated git tag
  • Push the tag to GitHub
  • Trigger the release workflow

Manual Method

If you prefer to create tags manually:

# Create an annotated tag
git tag -a v1.0.0 -m "Release v1.0.0"

# Push the tag
git push origin v1.0.0

Download URLs

Once a release is created, users can download the package at:

Latest Version (Always Updated)

https://github.com/YOUR_USERNAME/gapstars-upskilling/releases/latest/download/gapstars-ai-setup.zip

Specific Version

https://github.com/YOUR_USERNAME/gapstars-upskilling/releases/download/v1.0.0/gapstars-ai-setup.zip

Testing Locally

Before creating a release, test the package script locally:

# Run the packaging script
./scripts/package.sh

# Inspect the generated zip
unzip -l gapstars-ai-setup-*.zip

# Test extraction
mkdir test-extract
cd test-extract
unzip ../gapstars-ai-setup-*.zip
ls -la

Version Strategy

Follow Semantic Versioning:

  • MAJOR (X.0.0): Breaking changes to the workflow or structure
  • MINOR (0.X.0): New agents, significant features, or improvements
  • PATCH (0.0.X): Bug fixes, documentation updates, small tweaks

Workflow Details

The GitHub Actions workflow (.github/workflows/release.yml) runs automatically when you push a tag matching v*.*.*.

It performs these steps:

  1. Checks out the code
  2. Runs scripts/package.sh to build the artifact
  3. Creates a GitHub Release with release notes
  4. Uploads both versioned and "latest" zip files

Troubleshooting

Workflow doesn't trigger

  • Check that your tag matches the pattern v*.*.* (e.g., v1.0.0)
  • Verify you pushed the tag: git push origin <tagname>

Package is incomplete

  • Ensure CLAUDE.md, README-CLAUDE-CODE.md, and .claude/ exist
  • Run ./scripts/package.sh locally to test

Permission errors

  • Verify the repository has Actions enabled
  • Check that the workflow has contents: write permission (already configured)

Git Worktrees

For parallel feature development, use git worktrees:

# Create worktree for a new feature
git worktree add ../gapstars-upskilling-worktrees/feature-name -b feature/feature-name

# List all worktrees
git worktree list

# Remove when done
git worktree remove ../gapstars-upskilling-worktrees/feature-name

Worktrees are stored in /Users/jeroen/Projects/gapstars-upskilling-worktrees/ (one level above the main repo).