Sparkler LogoSparkler
HomeDocsGuidesGitHub Integration

GitHub Integration

Learn how to connect your GitHub repository to Sparkler and automate your macOS app update workflow. With this integration, you can automatically upload, sign, and publish updates when you create a new release on GitHub.

Benefits

  • Automated workflow: Push a tag, create a release, and let Sparkler handle the rest.
  • Secure signing: Your app binaries are automatically signed with your EdDSA key.
  • Changelog synchronization: Pull release notes directly from your GitHub release or CHANGELOG.md.
  • Version tracking: Sparkler keeps track of all your GitHub releases and tags.

1Connect Your GitHub Account

Begin by connecting your GitHub account to Sparkler:

  1. Log in to your Sparkler dashboard
  2. Go to "Settings" → "Integrations"
  3. Click "Connect GitHub Account"
  4. Authorize Sparkler to access your GitHub repositories

Note: Sparkler will only request the minimum permissions needed to access your repositories and releases. You can always revoke access later from your GitHub settings.

2Link Your Repository

After connecting your GitHub account, you can link specific repositories to your Sparkler apps:

  1. In your Sparkler dashboard, click "Add New App" or select an existing app
  2. Navigate to the "Integrations" tab
  3. Select the GitHub repository that contains your macOS app
  4. Configure which branches and tags to monitor (default: all tags)
Link Repository Screenshot

3Set Up GitHub Actions

To automate the upload of your app binaries to Sparkler when you create a new release, you'll need to set up a GitHub Action:

  1. Create a .github/workflows/release.yml file in your repository
  2. Add the Sparkler GitHub Action to your workflow
  3. Configure the action with your Sparkler API key and app ID

Here's a sample GitHub Actions workflow:

name: Release
on:
  release:
    types: [published]
    
jobs:
  upload-to-sparkler:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: Build App
        run: |
          # Your build steps here
          # ...
          
      - name: Upload to Sparkler
        uses: sparkler-app/upload-action@v1
        with:
          api-key: ${{ secrets.SPARKLER_API_KEY }}
          app-id: your-app-id
          artifact-path: path/to/your/app.zip
          version: ${{ github.event.release.tag_name }}
          release-notes: ${{ github.event.release.body }}

4Store Your API Key

For security, store your Sparkler API key as a GitHub secret:

  1. In your Sparkler dashboard, go to "Settings" → "API Keys"
  2. Generate a new API key with appropriate permissions
  3. In your GitHub repository, go to "Settings" → "Secrets" → "Actions"
  4. Click "New repository secret"
  5. Name the secret SPARKLER_API_KEY and paste your API key

Security Tip: Create a dedicated API key with minimal permissions for CI/CD usage. You can revoke or rotate this key at any time.

5Create a GitHub Release

Now that everything is set up, you can create a new release on GitHub:

  1. Tag your repository with a new version (e.g., v1.2.0)
  2. Go to the "Releases" section in your GitHub repository
  3. Click "Draft a new release"
  4. Select your tag, add a title and release notes
  5. If not using GitHub Actions, attach your app binary
  6. Publish the release

Your GitHub Action will automatically run and upload your build to Sparkler. If you're not using Actions, you'll need to manually upload the binary in the Sparkler dashboard.

6Publish the Update

Once your app binary is uploaded to Sparkler, you can publish the update:

  1. In your Sparkler dashboard, go to the "Releases" tab
  2. Find your new version in the list
  3. Review the release details, including version number and release notes
  4. Click "Publish" to make the update available to your users
  5. Optionally, configure a phased rollout
Publish Update Screenshot

Advanced Configuration

Automatic Publishing

You can configure Sparkler to automatically publish updates when they're uploaded:

  1. In your Sparkler dashboard, go to the app's "Settings" → "Automation"
  2. Enable "Auto-publish" for new releases
  3. Optionally, configure default rollout settings

Using CHANGELOG.md

Sparkler can automatically extract release notes from your CHANGELOG.md file:

  1. Ensure your CHANGELOG.md follows a standard format
  2. In your app's "Settings" → "Integrations", enable "Extract from CHANGELOG"
  3. Specify the format of your changelog (e.g., Keep a Changelog, Release Radar)

Troubleshooting

GitHub Action Failed

If your GitHub Action fails to upload your app:

  • Check that your API key is correctly set in GitHub secrets
  • Verify that your artifact path is correct
  • Ensure your app ID matches the one in Sparkler
  • Check the GitHub Actions log for detailed error messages

Repository Not Showing

If your repository isn't appearing in Sparkler:

  • Verify that you've granted Sparkler access to that repository
  • Try disconnecting and reconnecting your GitHub account
  • Check if the repository is private and ensure Sparkler has the right permissions