Skip to main content
The publish configuration in electron-builder controls how artifacts and update info files are published for auto-update. Publishing can be configured for multiple providers simultaneously.

​
Configuration

The publish key accepts:
  • String: Provider name (e.g., "github", "s3", "spaces")
  • Object: Provider configuration with options
  • Array<Object | String>: Multiple providers
Order matters! The first item in the array will be used as the default auto-update server.
You can specify publish configuration in:
  • Top-level configuration
  • Platform-specific configuration (mac, linux, win)
  • Target-specific configuration (e.g., nsis)

​
Auto-Detection

electron-builder automatically detects publish providers based on environment variables:
  • If GH_TOKEN or GITHUB_TOKEN is defined → defaults to [{provider: "github"}]
  • If KEYGEN_TOKEN is defined (and GitHub tokens are not) → defaults to [{provider: "keygen"}]
  • If GITHUB_RELEASE_TOKEN is defined → used instead of GH_TOKEN/GITHUB_TOKEN for publishing
Deprecation Notice: Implicit Publishingelectron-builder currently auto-detects when to publish based on CI environment conditions:
  • Running via npm run release → publishes always
  • Git tag detected in CI → publishes on tag
  • CI environment detected → publishes to draft releases
This implicit publishing behavior is deprecated and will be disabled in electron-builder v27.To prepare for this change, explicitly specify your publish intent using the --publish CLI flag (e.g., --publish always, --publish onTag) or set the publish configuration in your package.json or electron-builder.yml.

​
Multiple Publishers

You can publish to multiple providers. The first provider will be used as the default auto-update server: 
{
  "build": {
    "win": {
      "publish": ["github", "bitbucket"]
    }
  }
}
You can also configure publishing via CLI arguments: 
electron-builder -c.snap.publish=github

​
How to Publish

The --publish CLI flag controls when to publish:
ValueDescription
onTagPublish only on tag push
onTagOrDraftPublish on tag push or if draft release exists
alwaysAlways publish
neverNever publish
electron-builder --publish always

​
Automatic Publishing Rules

Instead of explicitly specifying --publish, electron-builder follows these automatic rules:
  1. CI server detected → onTagOrDraft
  2. Tag pushed in CI → onTag (release drafted if doesn’t exist, artifacts published only on tag push)
  3. npm script named release → always
{
  "scripts": {
    "release": "electron-builder"
  }
}
Running npm run release or yarn release will draft a release (if doesn’t exist) and publish artifacts.

​
Publishing Workflows

1

Draft a new release

Draft a new release on GitHub. Set the “Tag version” to your application’s package.json version prefixed with v.Example: If your package.json version is 1.0, set “Tag version” to v1.0.
2

Push commits

Push commits to your repository. Every CI build will update the artifacts attached to this draft release.
3

Publish the release

Once ready, publish the release. GitHub will tag the latest commit for you.
This workflow allows you to always have the latest artifacts, and the release can be published when ready.

​
Continuous Deployment on S3 and Non-GitHub Providers

This workflow is modeled on Maven release handling:
1

Configure CI to publish on each commit

package.json
{
  "scripts": {
    "dist": "electron-builder --publish always"
  }
}
2

Use snapshot versions during development

Set your package.json version to 1.9.0-snapshot (or 1.9.0-master). This will publish:
  • snapshot.yml metadata file
  • something-snapshot.exe build (and corresponding files for other platforms)
3

Deploy production version

When ready to deploy, change your version to 1.9.0 and push. This will produce:
  • latest.yml metadata file
  • something.exe build
Tag this version in git for tracking.
4

Revert to snapshot version

Change the version back to a snapshot version (e.g., 1.10.0-snapshot) and commit.

​
GitHub Repository Detection

The GitHub repository is automatically detected from:
  1. repository field in package.json
  2. Environment variables:
    • TRAVIS_REPO_SLUG
    • APPVEYOR_REPO_NAME
    • CIRCLE_PROJECT_USERNAME/CIRCLE_PROJECT_REPONAME
  3. .git/config origin URL

​
Publishers

​
GitHub

Publish to GitHub Releases: 
{
  "build": {
    "publish": {
      "provider": "github",
      "owner": "your-username",
      "repo": "your-repo"
    }
  }
}
Environment Variables:
  • GH_TOKEN or GITHUB_TOKEN: GitHub personal access token
  • GITHUB_RELEASE_TOKEN: Optional separate token for publishing (allows read-only GITHUB_TOKEN)
For fine-grained personal access tokens, “Contents” permission with “Read and write” access is sufficient.

​
S3

Publish to Amazon S3: 
{
  "build": {
    "publish": {
      "provider": "s3",
      "bucket": "your-bucket-name",
      "region": "us-east-1"
    }
  }
}
Environment Variables:
  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_ACCESS_KEY

​
DigitalOcean Spaces

Publish to DigitalOcean Spaces: 
{
  "build": {
    "publish": {
      "provider": "spaces",
      "name": "your-space-name",
      "region": "nyc3"
    }
  }
}
Environment Variables:
  • DO_KEY_ID: DigitalOcean Spaces access key
  • DO_SECRET_KEY: DigitalOcean Spaces secret key

​
Keygen

Publish to Keygen: 
{
  "build": {
    "publish": {
      "provider": "keygen",
      "account": "your-account-id",
      "product": "your-product-id"
    }
  }
}
Environment Variables:
  • KEYGEN_TOKEN: Keygen API token

​
Bitbucket

Publish to Bitbucket: 
{
  "build": {
    "publish": {
      "provider": "bitbucket",
      "owner": "your-username",
      "slug": "your-repo-slug"
    }
  }
}

​
Snap Store

The snap target publishes to Snap Store by default: 
{
  "build": {
    "snap": {
      "publish": "github"
    }
  }
}
To force publishing to a different provider, explicitly specify the publish configuration for snap.

​
Generic Server (BYO)

Publish to your own generic HTTP(s) server: 
{
  "build": {
    "publish": {
      "provider": "generic",
      "url": "https://example.com/updates"
    }
  }
}
When using a generic server, you must manually upload the built application and metadata files. electron-builder will generate the files but won’t upload them.

​
File Macros

All publish options support File Macros for dynamic values: 
{
  "build": {
    "publish": {
      "provider": "s3",
      "bucket": "my-bucket",
      "path": "/releases/${version}"
    }
  }
}

​
Generated Files

electron-builder generates and uploads the following metadata files (except for bintray which doesn’t require them):
  • Windows: latest.yml
  • macOS: latest-mac.yml
  • Linux: latest-linux.yml
These files contain:
  • Version information
  • File paths
  • SHA-512 checksums
  • Optional staging percentage for rollouts
Example latest.yml: 
version: 1.0.0
path: MyApp Setup 1.0.0.exe
sha512: Dj51I0q8aPQ3ioaz9LMqGYujAYRbDNblAQbodDRXAMxmY6hsHqEl3F6SvhfJj5oPhcqdX1ldsgEvfMNXGUXBIw==
releaseDate: '2024-03-15T10:30:00.000Z'

​
CI Configuration Examples

​
GitHub Actions

.github/workflows/build.yml
name: Build and Release

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [macos-latest, ubuntu-latest, windows-latest]
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 18
      
      - name: Install dependencies
        run: npm ci
      
      - name: Build and publish
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: npm run release

​
Travis CI

.travis.yml
language: node_js
node_js:
  - 18

os:
  - linux
  - osx
  - windows

script:
  - npm run build

deploy:
  provider: script
  script: npm run release
  skip_cleanup: true
  on:
    tags: true

env:
  global:
    - secure: "encrypted-gh-token"

​
Custom Publish Provider

You can implement a custom publish provider if the built-in providers don’t meet your needs.

Build docs developers (and LLMs) love

Get started for freeTalk to us