Publishing

The publish key contains a set of options instructing electron-builder on how it should publish artifacts and build update info files for auto update.

Configuration Format

String | Object | Array<Object | String> where Object can be any of the provider configurations below. Order is important - the first item will be used as a default auto-update server. Can be specified in the top-level configuration or any platform- (mac, linux, win) or target- (e.g. nsis) specific configuration.

When using a generic server, you have to upload the built application and metadata files yourself.

Default Behavior

If GH_TOKEN or GITHUB_TOKEN is defined - defaults to [{provider: "github"}]
If KEYGEN_TOKEN is defined and GH_TOKEN or GITHUB_TOKEN is not - defaults to [{provider: "keygen"}]
If GITHUB_RELEASE_TOKEN is defined, it will be used instead of GH_TOKEN or GITHUB_TOKEN to publish your release
- The GITHUB_TOKEN will still be used when your app checks for updates
- You could make your GITHUB_TOKEN “Read-only” when creating a fine-grained personal access token, and “Read and write” for the GITHUB_RELEASE_TOKEN
- “Contents” fine-grained permission was sufficient (as of Apr 2024)

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, please 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.

Snap Store: snap target by default publishes to snap store (the app store for Linux). To force publishing to another provider, explicitly specify publish configuration for snap.

Multiple Publishers

You can publish to multiple providers. Order is important - the first item will be used as a default auto-update server.

{
  "build": {
    "win": {
      "publish": ["github", "bitbucket"]
    }
  }
}

You can also configure publishing using CLI arguments:

electron-builder -c.snap.publish=github

How to Publish

CLI Options

electron-builder --publish <option>

Value	Description
`onTag`	On tag push only
`onTagOrDraft`	On tag push or if draft release exists
`always`	Always publish
`never`	Never publish

Automatic Rules

Instead of explicitly specifying --publish, you can rely on automatic rules:

CI server detected - onTagOrDraft
CI server reports tag was pushed - onTag (Release will be drafted if doesn’t already exist and artifacts published only if tag was pushed)
npm script named release - always

Add to scripts in your development package.json:

{
  "scripts": {
    "release": "electron-builder"
  }
}

Then run npm run release to draft a release and publish artifacts.

Workflows

Recommended GitHub Releases Workflow

Draft a new release. Set the “Tag version” to the value of version in your application package.json, and prefix it with v. “Release title” can be anything you want.
- For example, if your application package.json version is 1.0, your draft’s “Tag version” would be v1.0
Push some commits. Every CI build will update the artifacts attached to this draft.
Once you are done, publish the release. GitHub will tag the latest commit for you.

The benefit of this workflow is that it allows you to always have the latest artifacts, and the release can be published once it is ready.

Continuous Deployment Workflow on Amazon S3

This example workflow is modelled on how releases are handled in maven (it is an example of one of many possible workflows):

Setup your CI to publish on each commit. E.g. "dist": "electron-builder --publish always" in your package.json
Set your version in your application package.json to 1.9.0-snapshot (or 1.9.0-master or whatever you want your development channel to be named). This will publish a file named snapshot.yml and a build named something-snapshot.exe (and corresponding for mac) to S3.
When you are ready to deploy, simply change your package version to 1.9.0 and push. This will then produce a latest.yml and something.exe on S3. Usually you’ll git-tag this version as well (just to keep track of it).
Change the version back to a snapshot version right after, i.e. 1.10.0-snapshot, and commit it.

GitHub Repository Detection

Detected automatically using:

repository in the application or development package.json
If not set, from environment variables:
- TRAVIS_REPO_SLUG
- APPVEYOR_REPO_NAME
- CIRCLE_PROJECT_USERNAME/CIRCLE_PROJECT_REPONAME
If no environment variables, from .git/config origin url

File Macros

In all publish options File Macros are supported.

Base Configuration

All publish providers extend these base configuration options:

provider

string

required

The provider name (github, s3, spaces, generic, etc.)

publishAutoUpdate

boolean

default:true

Whether to publish auto update info files.Auto update relies only on the first provider in the list (you can specify several publishers). Thus, probably, there’s no need to upload the metadata files for the other configured providers. But by default will be uploaded.

requestHeaders

OutgoingHttpHeaders

Any custom request headers

timeout

number

default:120000

Request timeout in milliseconds. (Default is 2 minutes; 0 is ignored)

GitHub

GitHub options. GitHub personal access token is required. You can generate by going to https://github.com/settings/tokens/new. The access token should have the repo scope/permission. Define GH_TOKEN environment variable.

provider

string

required

Must be github

repo

string

The repository name. Detected automatically.

owner

string

The owner

vPrefixedTagName

boolean

default:true

Deprecated: Please use tagNamePrefix instead

Whether to use v-prefixed tag name.

tagNamePrefix

string

If defined, sets the prefix of the tag name that comes before the semver number.Examples: "v" in "v1.2.3" or "test" in "test1.2.3"Overrides vPrefixedTagName

host

string

default:"github.com"

The host (including the port if needed)

protocol

'https' | 'http'

default:"https"

The protocol. GitHub Publisher supports only https.

token

string

The access token to support auto-update from private github repositories. Never specify it in the configuration files. Only for setFeedURL.

private

boolean

Whether to use private github auto-update provider if GH_TOKEN environment variable is defined. See Private GitHub Update Repo.

channel

string

default:"latest"

The channel

releaseType

'draft' | 'prerelease' | 'release'

default:"draft"

The type of release. By default draft release will be created.Also you can set release type using environment variable. If EP_DRAFT is set to true - draft, if EP_PRE_RELEASE is set to true - prerelease.

Example

{
  "build": {
    "publish": {
      "provider": "github",
      "owner": "electron-userland",
      "repo": "electron-builder"
    }
  }
}

GitLab

GitLab options. GitLab personal access token is required for private repositories. You can generate one by going to your GitLab profile settings. Define GITLAB_TOKEN environment variable.

provider

string

required

Must be gitlab

projectId

string | number

The GitLab project ID or path (e.g., “12345678” or “namespace/project”)

host

string

default:"gitlab.com"

The GitLab host (including the port if needed)

token

string

The access token to support auto-update from private GitLab repositories. Never specify it in the configuration files.

vPrefixedTagName

boolean

default:true

Whether to use v-prefixed tag name

channel

string

default:"latest"

The channel

uploadTarget

'project_upload' | 'generic_package'

default:"project_upload"

Upload target method. Can be “project_upload” for GitLab project uploads or “generic_package” for GitLab generic packages.

Example

{
  "build": {
    "publish": {
      "provider": "gitlab",
      "projectId": "namespace/project"
    }
  }
}

Amazon S3

Amazon S3 options. AWS credentials are required, please see getting your credentials. To set credentials define AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables directly, or use ~/.aws/credentials file, or use ~/.aws/config file. For the last method to work you will also need to define AWS_SDK_LOAD_CONFIG=1 environment variable.

provider

string

required

Must be s3

bucket

string

required

The bucket name

region

string

The region. Is determined and set automatically when publishing.

channel

string

default:"latest"

The update channel

path

string

default:"/"

The directory path

acl

'private' | 'public-read'

default:"public-read"

The ACL. Set to null to not add.Please see required permissions for the S3 provider.

storageClass

'STANDARD' | 'REDUCED_REDUNDANCY' | 'STANDARD_IA'

default:"STANDARD"

The type of storage to use for the object

encryption

'AES256' | 'aws:kms'

Server-side encryption algorithm to use for the object

endpoint

string

The endpoint URI to send requests to. The default endpoint is built from the configured region.The endpoint should be a string like https://{service}.{region}.amazonaws.com.

accelerate

boolean

If set to true, this will enable the s3 accelerated endpoint.These endpoints have a particular format of: ${bucketname}.s3-accelerate.amazonaws.com

forcePathStyle

boolean

When true, force a path-style endpoint to be used where the bucket name is part of the path.Path-style Access

Example

{
  "build": {
    "publish": {
      "provider": "s3",
      "bucket": "my-bucket",
      "region": "us-east-1"
    }
  }
}

DigitalOcean Spaces

DigitalOcean Spaces options. Access key is required, define DO_KEY_ID and DO_SECRET_KEY environment variables.

provider

string

required

Must be spaces

name

string

required

The space name

region

string

required

The region (e.g. nyc3)

channel

string

default:"latest"

The update channel

path

string

default:"/"

The directory path

acl

'private' | 'public-read'

default:"public-read"

The ACL. Set to null to not add.

Example

{
  "build": {
    "publish": {
      "provider": "spaces",
      "name": "my-space",
      "region": "nyc3"
    }
  }
}

Keygen

Keygen options. Define KEYGEN_TOKEN environment variable.

provider

string

required

Must be keygen

account

string

required

Keygen account’s UUID

product

string

required

Keygen product’s UUID

host

string

default:"api.keygen.sh"

Keygen host for self-hosted instances

channel

'stable' | 'rc' | 'beta' | 'alpha' | 'dev'

default:"stable"

The channel

platform

string

The target Platform. Is set programmatically explicitly during publishing.

Example

{
  "build": {
    "publish": {
      "provider": "keygen",
      "account": "your-account-uuid",
      "product": "your-product-uuid"
    }
  }
}

Bitbucket

Bitbucket options. Define BITBUCKET_TOKEN environment variable. For converting an app password to a usable token, you can utilize this:

convertAppPassword(owner: string, appPassword: string) {
  const base64encodedData = Buffer.from(`${owner}:${appPassword.trim()}`).toString("base64")
  return `Basic ${base64encodedData}`
}

provider

string

required

Must be bitbucket

owner

string

required

Repository owner

slug

string

required

Repository slug/name

token

string

The app password to support auto-update from private bitbucket repositories.

username

string

The user name to support auto-update from private bitbucket repositories

channel

string

default:"latest"

The channel

Example

{
  "build": {
    "publish": {
      "provider": "bitbucket",
      "owner": "my-workspace",
      "slug": "my-repo"
    }
  }
}

Snap Store

Snap Store options. To publish directly to Snapcraft, see Snapcraft authentication options for local or CI/CD authentication options.

provider

string

required

Must be snapStore

repo

string

Snapcraft repo name

channels

string | Array<string>

default:["edge"]

The list of channels the snap would be released

Example

{
  "build": {
    "publish": {
      "provider": "snapStore",
      "channels": ["stable", "candidate"]
    }
  }
}

Generic Server

Generic (any HTTP(S) server) options. In all publish options File Macros are supported.

When using a generic server, you have to upload the built application and metadata files yourself.

provider

string

required

Must be generic

url

string

required

The base url. e.g. https://bucket_name.s3.amazonaws.com

channel

string

default:"latest"

The channel

useMultipleRangeRequest

boolean

Whether to use multiple range requests for differential update. Defaults to true if url doesn’t contain s3.amazonaws.com.

Example

{
  "build": {
    "publish": {
      "provider": "generic",
      "url": "https://example.com/downloads"
    }
  }
}

Custom Publisher

Custom publish provider can be used if needed.

provider

string

required

Must be custom

updateProvider

class

The Provider to provide UpdateInfo regarding available updates. Required to use custom providers with electron-updater.

Example

{
  "build": {
    "publish": {
      "provider": "custom",
      "updateProvider": "MyCustomProvider"
    }
  }
}

Common

macOS

Windows

Linux

Publishing

Configuration Format

Default Behavior

Multiple Publishers

How to Publish

CLI Options

Automatic Rules

Workflows

Recommended GitHub Releases Workflow

Continuous Deployment Workflow on Amazon S3

GitHub Repository Detection

File Macros

Base Configuration

GitHub

Example

GitLab

Example

Amazon S3

Example

DigitalOcean Spaces

Example

Keygen

Example

Bitbucket

Example

Snap Store

Example

Generic Server

Example

Custom Publisher

Example

Build docs developers (and LLMs) love

Common

macOS

Windows

Linux

Publishing

​Configuration Format

​Default Behavior

​Multiple Publishers

​How to Publish

​CLI Options

​Automatic Rules

​Workflows

​Recommended GitHub Releases Workflow

​Continuous Deployment Workflow on Amazon S3

​GitHub Repository Detection

​File Macros

​Base Configuration

​GitHub

​Example

​GitLab

​Example

​Amazon S3

​Example

​DigitalOcean Spaces

​Example

​Keygen

​Example

​Bitbucket

​Example

​Snap Store

​Example

​Generic Server

​Example

​Custom Publisher

​Example

Build docs developers (and LLMs) love

Configuration Format

Default Behavior

Multiple Publishers

How to Publish

CLI Options

Automatic Rules

Workflows

Recommended GitHub Releases Workflow

Continuous Deployment Workflow on Amazon S3

GitHub Repository Detection

File Macros

Base Configuration

GitHub

Example

GitLab

Example

Amazon S3

Example

DigitalOcean Spaces

Example

Keygen

Example

Bitbucket

Example

Snap Store

Example

Generic Server

Example

Custom Publisher

Example