Release Workflow

Release Workflow

Bill Organizer uses a GitHub Actions CI/CD pipeline to automatically build, package, and publish production-ready releases.

---

Overview

File: .github/workflows/release.yml

The workflow:

1. Installs all dependencies
2. Type-checks TypeScript
3. Compiles frontend assets with Vite
4. Packages a clean ZIP (dev files excluded)
5. Auto-increments the patch version
6. Creates a draft GitHub Release with the ZIP attached

---

Triggers

Automatic — Push to main

Every merge or push to main triggers a new release build:

git push origin main

Manual — Workflow Dispatch

1. Go to your repository's Actions tab
2. Select the Release workflow
3. Click Run workflow
4. Choose the branch (typically main)
5. Click Run workflow

---

Pipeline Steps

Step	Description
Checkout	Full git history for version tag detection
Setup PHP 8.3	Installs PHP with all required extensions
Setup Node.js 22	Configures Node with Yarn cache
Composer cache	Caches vendor directory for faster builds
Install Composer deps	Production-only dependencies
Install Yarn deps	yarn install --frozen-lockfile
Generate app key	php artisan key:generate
Ziggy routes	php artisan ziggy:generate
TypeScript check	Validates all TypeScript types
Vite build	Compiles and bundles frontend assets
Package artifacts	rsync copy excluding dev files
Create ZIP	zip -r production archive
Generate version	Auto-increments patch from latest git tag
Create draft release	Publishes draft with ZIP attachment
Upload artifact	Stores ZIP for 30 days (GitHub Actions artifacts)

---

Versioning Strategy

The workflow automatically determines the next version from the latest git tag:

• If tags exist and follow semver (v1.2.3) → increments patch → v1.2.4
• If no tags exist → starts at v0.0.1

Releases are created as drafts so you can review before publishing.

Customizing the Version Strategy

Minor version increment:

NEW_MINOR=$((MINOR + 1))
NEW_VERSION="v${MAJOR}.${NEW_MINOR}.0"

Major version increment:

NEW_MAJOR=$((MAJOR + 1))
NEW_VERSION="v${NEW_MAJOR}.0.0"

Pre-release (beta/RC):

if [[ "${{ github.ref }}" == "refs/heads/develop" ]]; then
  NEW_VERSION="${NEW_VERSION}-beta.${GITHUB_RUN_NUMBER}"
fi

---

What the ZIP Contains

The production ZIP includes only files needed at runtime:

bill-organizer-vX.X.X.zip
├── app/
├── bootstrap/
├── config/
├── database/
├── public/
│   └── build/      ← compiled Vite assets
├── resources/
│   └── views/
├── routes/
├── storage/
├── vendor/         ← production Composer dependencies
├── .env.example
├── artisan
└── composer.json

Excluded from the ZIP:

• tests/
• node_modules/
• .github/
• Dev config files (.eslintrc, vite.config.ts, etc.)
• resources/js/ source files
• .env (never committed or packaged)

---

Deploying a Release

1. Download the ZIP from GitHub Releases
2. Extract to your web server directory
3. Set up .env:

   cp .env.example .env
   php artisan key:generate

4. Configure database and run migrations:

   php artisan migrate --force

5. Set file permissions:

   chmod -R 755 storage bootstrap/cache
   chown -R www-data:www-data storage bootstrap/cache

6. Point web server to public/

See Deployment for a full guide.

---

Customizing the Workflow

Change PHP or Node Version

- name: Setup PHP
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.4'   # ← update here

- name: Setup Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20'   # ← update here

Exclude Additional Files from ZIP

Modify the rsync command in the workflow:

rsync -av \
  --exclude='custom-config/' \
  --exclude='*.custom' \
  # ... existing excludes ...

Publish Releases Automatically (skip draft)

Change the release step flag:

- name: Create Release
  uses: softprops/action-gh-release@v1
  with:
    draft: false   # ← change to false to publish immediately

---

Security

• Uses GITHUB_TOKEN with minimal required permissions
• .env is never included in build artifacts
• Development files (tests, configs) are excluded from releases
• Build artifacts are retained for 30 days only

---

Troubleshooting

Problem	Solution
Composer dependency error	Ensure all deps are compatible with PHP 8.3
Yarn lockfile mismatch	Commit the updated yarn.lock
TypeScript type errors	Fix type errors locally before pushing
Vite build failure	Check vite.config.ts and asset imports
Wrong version generated	Verify git tags follow v1.2.3 semver format
Tag conflict	Check if the generated tag already exists and delete it
ZIP upload failure	Verify the ZIP was created in the packaging step logs
Missing GitHub Actions permissions	Enable write permissions in repo settings → Actions