electron-releases-provider-github

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:

• Tag suffix - Version tags with -alpha, -beta, etc.
• 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:

• Fetches the RELEASES file content
• Rewrites relative .nupkg paths to absolute URLs
• 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:

• Tag format: Use semver tags (1.0.0, 1.0.0-beta.1)
• Prerelease checkbox: Check for non-stable channels
• Assets: Upload all platform binaries
• 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