SageTube/.github/CI_CD_README.md

YTSage CI/CD Workflow

This repository uses GitHub Actions to automatically build and release YTSage for multiple platforms when version tags are pushed.

How It Works

Trigger

The workflow is triggered when you push a git tag that starts with v (e.g., v4.9.1, v4.9.1).

Build Process

1. Setup: Uses Python 3.13.6 on all platforms
2. Builds: Creates platform-specific executables using cx_Freeze
3. Packages: Generates native package formats for each platform
4. Release: Creates a draft GitHub release with all artifacts

Usage

Creating a Release

1. Update version in your source code if needed

2. Commit your changes:

   git add .
   git commit -m "Release v4.9.1"
   

3. Create and push a tag:

   git tag v4.9.1
   git push origin v4.9.1
   

4. Watch the action: Go to Actions tab in GitHub to monitor progress

5. Review draft release: Once complete, check the Releases section for the draft

Release Artifacts

The workflow creates the following files based on the platform:

Windows

• YTSage-v{version}-portable.zip - Standard portable version
• YTSage-v{version}-ffmpeg-portable.zip - FFmpeg bundle portable

Linux

• YTSage-v{version}-{arch}.AppImage - AppImage portable
• YTSage-v{version}-{arch}.rpm - RPM package
• YTSage-v{version}-{arch}.deb - Debian package

macOS

• YTSage-v{version}-{arch}.app.zip - Zipped application bundle
• YTSage-v{version}-{arch}.dmg - Disk image installer

Workflow Features

Multi-Platform Support

• Windows: Uses PowerShell scripts with cx_Freeze
• Linux: Uses Bash scripts with cx_Freeze, creates AppImage, RPM, and DEB
• macOS: Matrix build for both Intel (x64) and Apple Silicon (arm64)

Automatic Version Detection

• Extracts version from git tag (removes 'v' prefix)
• Names all artifacts consistently across platforms

Caching

• Python dependencies are cached to speed up builds
• Virtual environment is cached between runs

Error Handling

• Comprehensive error checking at each step
• Detailed logging for troubleshooting
• Artifact verification before upload

Security

• Uses official GitHub Actions
• No external dependencies
• Secure token handling

Manual Intervention

After Workflow Completion

1. Review the draft release in GitHub
2. Test the artifacts if needed
3. Edit release notes if desired
4. Publish the release when ready

Troubleshooting

If the workflow fails:

1. Check the Actions logs for error details
2. Ensure all required files are present
3. Verify the tag format is correct (v*)
4. Check that dependencies are properly listed

Configuration

Modifying the Workflow

The workflow files are located in .github/workflows/:

• build-windows.yml - Windows builds
• build-linux.yml - Linux builds
• build-macos.yml - macOS builds

Key Configuration Options

• PYTHON_VERSION: Python version (currently 3.13.6)
• Artifact naming patterns
• Release note templates
• Build optimization settings

Adding New Build Types

To add new platform packages:

1. Create or modify workflow files in .github/workflows/
2. Target the appropriate OS runner (windows-latest, ubuntu-latest, macos-latest)
3. Use cx_Freeze or PyInstaller for packaging
4. Package the build output in platform-native formats
5. Upload the artifacts and include them in the release

Notes

• All builds use cx_Freeze for packaging
• FFmpeg binaries are bundled where needed
• Screenshots are removed from builds to reduce size
• Draft releases allow for review before publication
• macOS builds run on both Intel and Apple Silicon runners

Example Tag Commands

# For a new release
git tag v4.8.1
git push origin v4.8.1

# For a patch release
git tag v4.8.1
git push origin v4.8.1

# To delete a tag (if needed)
git tag -d v4.8.1
git push origin :refs/tags/v4.8.1