@electron-releases/provider-github

GitHub provider for Electron auto-update servers. Fetches releases and assets directly from GitHub Releases.

Installation

npm install @electron-releases/provider-github
# or
yarn add @electron-releases/provider-github
# or
bun add @electron-releases/provider-github

Quick Start

import { configureGithubProvider } from "@electron-releases/provider-github";

const githubProvider = configureGithubProvider({
  token: process.env.GITHUB_TOKEN!,
  owner: "your-org",
  repo: "your-app",
});

// Use with an adapter
import { configureNextjsAdapter } from "@electron-releases/adapter-nextjs";

export const GET = configureNextjsAdapter({
  releases: githubProvider.releases,
  assets: githubProvider.assets,
});

Configuration

configureGithubProvider({
  // Required: GitHub personal access token
  token: process.env.GITHUB_TOKEN!,

  // Required: Repository owner (user or organization)
  owner: "your-org",

  // Required: Repository name
  repo: "your-app",

  // Optional: Release channels (default: ["alpha", "beta", "stable"])
  channels: ["alpha", "beta", "stable"],
});

GitHub Token

Create a Personal Access Token at github.com/settings/tokens:

| Repository Type | Required Scope | |-----------------|----------------| | Public | public_repo | | Private | repo (full) |

GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Release Channels

The provider automatically categorizes releases by channel based on:

1. Tag suffix - Version tags with -alpha, -beta, etc.
2. Prerelease flag - GitHub's prerelease checkbox

| Version Tag | Prerelease | Channel | |-------------|------------|---------| | 1.0.0 | No | stable | | 1.0.0-beta.1 | Yes | beta | | 1.0.0-alpha.3 | Yes | alpha |

Important: The last channel in your array is the "stable" channel (non-prerelease releases).

configureGithubProvider({
  // ...
  channels: ["nightly", "beta", "stable"], // "stable" = default channel
});

Using the Provider Directly

You can use the releases and assets providers independently:

import { 
  configureGithubReleases, 
  configureGithubAssets 
} from "@electron-releases/provider-github";

// Just releases
const releases = configureGithubReleases({
  token: process.env.GITHUB_TOKEN!,
  owner: "your-org",
  repo: "your-app",
});

// Get latest stable release
const latest = await releases.getRelease();

// Get latest beta
const beta = await releases.getRelease({ channel: "beta" });

// Get specific version
const specific = await releases.getRelease({ version: "1.2.3" });

// Get all channel releases
const all = await releases.getReleases();
// { stable: ReleaseInfo, beta: ReleaseInfo, alpha: ReleaseInfo }

// Just assets
const assets = configureGithubAssets({
  token: process.env.GITHUB_TOKEN!,
  owner: "your-org",
  repo: "your-app",
});

// Get signed download URL
const downloadUrl = await assets.getSignedDownloadUrl(platformAsset);

Expected Asset Naming

The provider automatically detects platforms from asset filenames:

| Platform | File Patterns | |----------|---------------| | darwin | *mac*.zip, *darwin*.zip | | darwin_arm64 | *mac*arm64*.zip, *darwin*arm64*.zip | | dmg | *.dmg | | dmg_arm64 | *arm64*.dmg | | exe | *.exe | | exe_arm64 | *arm64*.exe | | deb | *.deb | | rpm | *.rpm | | AppImage | *.AppImage |

Example Release Assets

For a release tagged v1.2.3, your assets might look like:

MyApp-1.2.3-mac.zip          → darwin
MyApp-1.2.3-mac-arm64.zip    → darwin_arm64
MyApp-1.2.3.dmg              → dmg
MyApp-1.2.3-arm64.dmg        → dmg_arm64
MyApp-1.2.3.exe              → exe
MyApp-1.2.3.deb              → deb
MyApp-1.2.3.rpm              → rpm
MyApp-1.2.3.AppImage         → AppImage
RELEASES                     → Windows Squirrel file

Windows Squirrel Support

For Squirrel.Windows updates, include a RELEASES file in your GitHub release assets. The provider automatically:

1. Fetches the RELEASES file content
2. Rewrites relative .nupkg paths to absolute URLs
3. Serves it for Windows update checks

Private Repository Downloads

For private repos, the provider generates authenticated download URLs using your GitHub token. These are time-limited signed URLs that work for direct downloads.

const assets = configureGithubAssets({
  token: process.env.GITHUB_TOKEN!, // Needs 'repo' scope
  // ...
});

// Returns a signed URL that works without authentication
const signedUrl = await assets.getSignedDownloadUrl(asset);

API Reference

configureGithubProvider(config)

Returns both releases and assets providers:

const { releases, assets } = configureGithubProvider(config);

configureGithubReleases(config)

Returns a ReleasesProvider:

interface ReleasesProvider {
  getRelease(options?: {
    channel?: string;
    version?: string | "latest";
  }): Promise<ReleaseInfo | null>;

  getReleases(options?: {
    channels?: string[];
  }): Promise<Record<string, ReleaseInfo | null>>;

  getChannelFromVersion(version: string): string;
}

configureGithubAssets(config)

Returns an AssetsProvider:

interface AssetsProvider {
  getSignedDownloadUrl(asset: PlatformAsset): Promise<string | null>;
}

ReleaseInfo

interface ReleaseInfo {
  version: string;      // "1.2.3"
  notes: string;        // Release body/changelog
  pub_date: string;     // ISO date
  channel: string;      // "stable", "beta", etc.
  platforms: Record<string, PlatformAsset>;
  files: Record<string, string>;  // e.g., { RELEASES: "..." }
}

PlatformAsset

interface PlatformAsset {
  name: string;         // "MyApp-1.2.3-mac.zip"
  api_url: string;      // GitHub API URL
  url: string;          // Browser download URL
  content_type: string; // "application/zip"
  size: number;         // Size in MB
}

Publishing Releases

When publishing releases on GitHub:

1. Tag format: Use semver tags (1.0.0, 1.0.0-beta.1)
2. Prerelease checkbox: Check for non-stable channels
3. Assets: Upload all platform binaries
4. Release notes: Add changelog in the body

electron-builder Integration

If using electron-builder, configure it to publish to GitHub:

{
  "build": {
    "publish": {
      "provider": "github",
      "owner": "your-org",
      "repo": "your-app"
    }
  }
}

Then publish with:

# Stable release
electron-builder --publish always

# Beta release
electron-builder --publish always -c.publish.releaseType=prerelease

TypeScript Support

Full TypeScript support with exported types:

import type {
  GithubConfig,
  ReleaseInfo,
  PlatformAsset,
  ReleasesProvider,
  AssetsProvider,
} from "@electron-releases/provider-github";

Rate Limiting

The provider uses the GitHub REST API via Octokit. Be aware of GitHub's rate limits:

| Authentication | Limit | |----------------|-------| | With token | 5,000 requests/hour | | Without token | 60 requests/hour |

For high-traffic apps, consider caching responses.

Related Packages

• @electron-releases/core - Core types and routing
• @electron-releases/adapter-nextjs - Next.js adapter

License

MIT