GitHub Actions Integration

Automate your release process with GitHub Actions.

Quick Start

1. Copy the example workflow to your repo:

   .github/workflows/publish-release.yml
   

2. Set up secrets in GitHub:

3. Go to Settings > Secrets and variables > Actions

4. Add PATCHER_API_KEY with your API key

5. Configure environment variables in the workflow file

6. Push a tag to trigger the release

Example Workflow

See example_full_workflow.yml in the nova-apis repository for a complete example.

Key Features

• Automatic on Tags: Triggers when you push v* tags (e.g., v1.2.0)
• Manual Dispatch: Run manually from GitHub Actions UI
• Large File Support: Handles files of any size via signed URLs
• Full Metadata: Includes all patcher fields

Customizing the Workflow

Update Environment Variables

env:
  PATCHER_API_URL: "https://apis.novasuite.one/api/patcher"
  PATCHER_API_KEY: ${{ secrets.PATCHER_API_KEY }}
  PATCHER_DEV_NAME: "your-dev-name"      # ← Change this
  PATCHER_APP_NAME: "your.app.id"        # ← Change this

Customize Build Step

Replace this section with your actual build process:

- name: Build
  run: |
    # Your build commands here
    npm run build
    # or
    cargo build --release
    # or
    pyinstaller your_app.py

Adjust Defaults

Change the default channel or display mode:

- name: Prep Metadata
  run: |
    echo "CHANNEL=beta" >> $GITHUB_ENV        # ← Release to beta by default
    echo "DISPLAY_MODE=passive" >> $GITHUB_ENV # ← Use passive updates

Triggering Releases

Method 1: Git Tags (Recommended)

# Create and push a new tag
git tag v1.2.0
git push origin v1.2.0

The workflow will: 1. Extract version 1.2.0 from the tag 2. Auto-detect channel (tags with "beta" → beta channel) 3. Build and publish automatically

Method 2: Manual Dispatch

1. Go to Actions tab in GitHub
2. Select your workflow
3. Click Run workflow
4. Choose options (channel, publish mode, etc.)

Method 3: Push to Branch

Configure to run on every push to main:

on:
  push:
    branches:
      - main

Windows-Specific Workflow

If you're building Windows apps (like the Netsurf example):

Key Differences: - Uses runs-on: windows-latest - Uses PowerShell for scripting - Handles Windows paths correctly - Includes pip caching for Python dependencies

See netsurf_patcher_workflow.yml for a complete example.

Caching Dependencies

Speed up builds by caching pip packages:

- name: Cache Pip Packages
  uses: actions/cache@v3
  with:
    path: ~\AppData\Local\pip\Cache
    key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
    restore-keys: |
      ${{ runner.os }}-pip-

This reduces build time from ~5 minutes to ~30 seconds on subsequent runs.

Multi-Platform Builds

To build for multiple platforms:

jobs:
  release:
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        include:
          - os: ubuntu-latest
            platform: Linux
          - os: windows-latest
            platform: Windows
          - os: macos-latest
            platform: macOS
    runs-on: ${{ matrix.os }}

    steps:
      # ... build steps ...

      - name: Publish Metadata
        run: |
          # Use ${{ matrix.platform }} in the API call
          -d '{"platform": "${{ matrix.platform }}", ...}'

Advanced: Channel-Based Workflows

Create separate workflows for different channels:

.github/workflows/release-production.yml:

on:
  push:
    tags:
      - 'v*'
env:
  CHANNEL: "production"
  AUTO_PUBLISH: "true"

.github/workflows/release-beta.yml:

on:
  push:
    tags:
      - 'v*-beta*'
env:
  CHANNEL: "beta"
  AUTO_PUBLISH: "true"

.github/workflows/nightly.yml:

on:
  schedule:
    - cron: '0 0 * * *'  # Every day at midnight
env:
  CHANNEL: "dev"
  AUTO_PUBLISH: "true"

Troubleshooting

"Failed to get upload URL"

Cause: Invalid JSON or authentication issue

Fix: 1. Check that PATCHER_API_KEY secret is set correctly 2. Verify JSON syntax in the request 3. Ensure dev_name and app_name match registered values

"S3 Upload Failed"

Cause: URL expired or network issue

Fix: 1. Ensure you upload within 15 minutes of getting the URL 2. Check internet connectivity in the runner 3. Verify file exists before upload

"Metadata Upload Failed"

Cause: Missing required fields or database constraint violation

Fix: 1. Check that SHA256 hash is calculated correctly 2. Ensure all required fields are present 3. Verify version/platform combination is unique (or use upsert correctly)

Best Practices

1. Use Tags for Versions: Keep a clean version history
2. Test in Beta First: Use manual dispatch to test the workflow
3. Cache Dependencies: Speed up builds significantly
4. Version Automatically: Extract version from git tags or package.json
5. Calculate Hash Correctly: Use the exact file that will be downloaded
6. Use Secrets: Never hardcode API keys in the workflow file

Complete Example

The example_full_workflow.yml includes: - ✅ Tag-based and manual triggers - ✅ Version extraction - ✅ Build step (customizable) - ✅ SHA-256 calculation - ✅ Signed URL upload - ✅ Metadata registration - ✅ All patcher fields

Copy and customize it for your project!