jellytau/docs/BUILD_RELEASE.md

Build & Release Workflow

This document explains the automated build and release process for JellyTau.

Overview

The CI/CD pipeline automatically:

1. ✅ Runs all tests (frontend + Rust)
2. ✅ Builds Linux binaries (AppImage + DEB)
3. ✅ Builds Android APK and AAB
4. ✅ Creates releases with artifacts
5. ✅ Tags releases with version numbers

Workflow Triggers

Automatic Trigger

When you push a version tag:

git tag v1.0.0
git push origin v1.0.0

The workflow automatically:

1. Runs tests
2. Builds both platforms
3. Creates a GitHub release with artifacts
4. Tags it as release/prerelease based on version

Manual Trigger

In Gitea Actions UI:

1. Go to Actions tab
2. Click Build & Release workflow
3. Click Run workflow
4. Optionally specify a version
5. Workflow runs without creating a release

Version Tagging

Format

Version tags follow semantic versioning: v{MAJOR}.{MINOR}.{PATCH}

Examples:

• v1.0.0 - Release version
• v1.0.0-rc1 - Release candidate (marked as prerelease)
• v1.0.0-beta - Beta version (marked as prerelease)
• v0.1.0-alpha - Alpha version (marked as prerelease)

Creating a Release

# Create and push a version tag
git tag v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

# Or create from main branch
git tag -a v1.0.0 -m "Release version 1.0.0" main
git push origin v1.0.0

Release Status

Versions containing rc, beta, or alpha are marked as prerelease:

git tag v1.0.0-rc1      # ⚠️ Prerelease
git tag v1.0.0-beta     # ⚠️ Prerelease
git tag v1.0.0-alpha    # ⚠️ Prerelease
git tag v1.0.0          # ✅ Full release

Workflow Steps

1. Test Phase

Runs on all tags and manual triggers:

• Frontend tests (vitest)
• Rust tests (cargo test)
• TypeScript type checking

Failure: Stops workflow, no build/release

2. Build Linux Phase

Runs after tests pass:

• Installs system dependencies
• Builds with Tauri
• Generates:
  • AppImage - Universal Linux binary
  • DEB - Debian/Ubuntu package

Output: artifacts/linux/

3. Build Android Phase

Runs in parallel with Linux build:

• Installs Android SDK/NDK
• Configures Rust for Android targets
• Builds with Tauri
• Generates:
  • APK - Android app package (installable)
  • AAB - Android App Bundle (for Play Store)

Output: artifacts/android/

4. Create Release Phase

Runs after both builds succeed (only on version tags):

• Prepares release notes
• Downloads build artifacts
• Creates GitHub/Gitea release
• Uploads all artifacts
• Tags as prerelease if applicable

Artifacts

Linux Artifacts

AppImage

• File: jellytau_*.AppImage
• Size: ~100-150 MB
• Use: Run directly on any Linux distro
• Installation:

  chmod +x jellytau_*.AppImage
  ./jellytau_*.AppImage
  

DEB Package

• File: jellytau_*.deb
• Size: ~80-120 MB
• Use: Install on Debian/Ubuntu/similar
• Installation:

  sudo dpkg -i jellytau_*.deb
  jellytau
  

Android Artifacts

APK

• File: jellytau-release.apk
• Size: ~60-100 MB
• Use: Direct installation on Android devices
• Installation:

  adb install jellytau-release.apk
  # Or sideload via file manager
  

AAB (Android App Bundle)

• File: jellytau-release.aab
• Size: ~50-90 MB
• Use: Upload to Google Play Console
• Note: Cannot be installed directly; for Play Store distribution

Release Notes

Release notes are automatically generated with:

• Version number
• Download links
• Installation instructions
• System requirements
• Known issues link
• Changelog reference

Build Matrix

Platform	OS	Architecture	Format
Linux	Any	x86_64	AppImage, DEB
Android	8.0+	arm64, armv7, x86_64	APK, AAB

Troubleshooting

Build Fails During Test Phase

1. Check test output in Gitea Actions
2. Run tests locally: bun run test and bun run test:rust
3. Fix failing tests
4. Create new tag with fixed code

Linux Build Fails

1. Check system dependencies installed
2. Verify Tauri configuration
3. Check cargo dependencies
4. Clear cache: Delete .cargo and target/ directories

Android Build Fails

1. Check Android SDK/NDK setup
2. Verify Java 17 is installed
3. Check Rust Android targets: rustup target list
4. Clear cache and rebuild

Release Not Created

1. Tag must start with v (e.g., v1.0.0)
2. Tests must pass
3. Both builds must succeed
4. Check workflow logs for errors

GitHub Release vs Gitea

The workflow uses GitHub Actions SDK but is designed for Gitea. For Gitea-native releases:

1. Workflow creates artifacts
2. Artifacts are available in Actions artifacts
3. Download and manually create Gitea release, or
4. Set up Gitea API integration to auto-publish

Customization

Change Release Notes Template

Edit .gitea/workflows/build-release.yml, section Prepare release notes:

- name: Prepare release notes
  id: release_notes
  run: |
    # Add your custom release notes format here
    echo "Custom notes" > release_notes.md

Add New Platforms

To add macOS or Windows builds:

1. Add new build-{platform} job
2. Set appropriate runs-on runner
3. Add platform-specific dependencies
4. Update artifact upload
5. Include in needs: [build-linux, build-android, build-{platform}]

Change Build Targets

Modify Tauri configuration or add targets:

- name: Build for Linux
  run: |
    # Add target specification
    bun run tauri build -- --target x86_64-unknown-linux-gnu

Monitoring

Check Status

1. Go to Actions tab in Gitea
2. View Build & Release workflow runs
3. Click specific run to see logs

Notifications

Set up notifications for:

• Build failures
• Release creation
• Tag pushes

Performance

Build Times (Approximate)

• Test phase: 5-10 minutes
• Linux build: 10-15 minutes
• Android build: 15-20 minutes
• Total: 30-45 minutes

Caching

Workflow caches:

• Rust dependencies (cargo)
• Bun node_modules
• Android SDK components

Security

Secrets

The workflow uses:

• GITHUB_TOKEN - Built-in, no setup needed
• No credentials needed for Gitea

Verification

To verify build integrity:

1. Download artifacts
2. Verify signatures (if implemented)
3. Check file hashes
4. Test on target platform

Best Practices

Versioning

1. Follow semantic versioning: v{MAJOR}.{MINOR}.{PATCH}
2. Tag releases in git
3. Update CHANGELOG.md before tagging
4. Include release notes in tag message

Testing Before Release

# Local testing before release
bun run test          # Frontend tests
bun run test:rust     # Rust tests
bun run check         # Type checking
bun run tauri build   # Local build test

Documentation

1. Update CHANGELOG.md with changes
2. Update README.md with new features
3. Document breaking changes
4. Add migration guide if needed

Example Release Workflow

# 1. Update version in relevant files (package.json, Cargo.toml, etc.)
vim package.json
vim src-tauri/tauri.conf.json

# 2. Update CHANGELOG
vim CHANGELOG.md

# 3. Commit changes
git add .
git commit -m "Bump version to v1.0.0"

# 4. Create annotated tag
git tag -a v1.0.0 -m "Release version 1.0.0

Features:
- Feature 1
- Feature 2

Fixes:
- Fix 1
- Fix 2"

# 5. Push tag to trigger workflow
git push origin v1.0.0

# 6. Monitor workflow in Gitea Actions
# Wait for tests → Linux build → Android build → Release

# 7. Download artifacts and test
# Visit release page and verify downloads

References

• Tauri Documentation
• Semantic Versioning
• GitHub Release Best Practices
• Android App Bundle
• AppImage Documentation

---

Last Updated: 2026-02-13