Skip to main content

publish

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.

String | Object | Array<Object | String> where Object it is Keygen, Generic Server, GitHub, S3, Spaces or Snap Store options. Order is important — 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.

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

Travis and AppVeyor support publishing artifacts. But it requires additional configuration for each CI and you need to configure what to publish. electron-builder makes publishing dead simple.

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.

  • e.g. mac: export GITHUB_RELEASE_TOKEN=<my token>
  • the GITHUB_TOKEN will still be used when your app checks for updates, etc.
  • 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. (at time of writing - Apr 2024)
Deprecation Notice: Implicit Publishing

electron-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 providers, explicitly specify publish configuration for snap.

You can publish to multiple providers. For example, to publish Windows artifacts to both GitHub and Bitbucket (order is important — first item will be used as a default auto-update server, so, in this example app will use github as auto-update provider):

{
  "build": {
    "win": {
      "publish": ["github", "bitbucket"]
    }
  }
}
win:
  publish:
      # an object provider for github with additional options
    - provider: github
      protocol: https
      # a string provider for bitbucket that will use default options
    - bitbucket

You can also configure publishing using CLI arguments, for example, to force publishing snap not to Snap Store, but to GitHub: -c.snap.publish=github

Custom publish provider can be used if need.

Macros

In all publish options File Macros are supported.

How to Publish​

Excerpt from CLI Usage of electron-builder command:

Publishing:
  --publish, -p  [choices: "onTag", "onTagOrDraft", "always", "never"]

CLI --publish option values:

ValueDescription
onTagon tag push only
onTagOrDrafton tag push or if draft release exists
alwaysalways publish
nevernever publish

But please consider using automatic rules instead of explicitly specifying publish:

  • If CI server detected, — onTagOrDraft.

  • If CI server reports that tag was pushed, — onTag.

    Release will be drafted (if doesn't already exist) and artifacts published only if tag was pushed.

  • If npm script named release, — always.

Add to scripts in the development package.json:

"release": "electron-builder"

and if you run yarn release, a release will be drafted (if doesn't already exist) and artifacts published.

  1. 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.

  2. Push some commits. Every CI build will update the artifacts attached to this draft.

  3. 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 and other non-GitHub​

This example workflow is modelled on how releases are handled in maven (it is an example of one of many possible workflows, you are not forced to follow it).

  1. Setup your CI to publish on each commit. E.g. "dist": "electron-builder --publish always" in your package.json.
  2. 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.
  3. When you are ready to deploy, simply change you 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).
  4. Change the version back to a snapshot version right after, i.e. 1.10.0-snapshot, and commit it.

GitHub Repository​

Detected automatically using:

  • repository in the application or development package.json,
  • if not set, env
    • TRAVIS_REPO_SLUG
    • or APPVEYOR_REPO_NAME
    • or CIRCLE_PROJECT_USERNAME/CIRCLE_PROJECT_REPONAME,
  • if no env, from .git/config origin url.

Publishers

Bitbucket​

Interface: BitbucketOptions

Bitbucket options. https://bitbucket.org/ 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}`
}

Extends​

Properties​

channel?​

readonly optional channel?: string | null

The channel.

Default​

latest

owner​

readonly owner: string

Repository owner

provider​

readonly provider: "bitbucket"

The provider. Must be bitbucket.

Overrides​

PublishConfiguration.provider

publishAutoUpdate?​

readonly optional publishAutoUpdate?: boolean

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.

Default​

true

Inherited from​

PublishConfiguration.publishAutoUpdate

requestHeaders?​

readonly optional requestHeaders?: OutgoingHttpHeaders

Any custom request headers

Inherited from​

PublishConfiguration.requestHeaders

slug​

readonly slug: string

Repository slug/name

timeout?​

readonly optional timeout?: number | null

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

Default​

120000

Inherited from​

PublishConfiguration.timeout

token?​

readonly optional token?: string | null

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

username?​

readonly optional username?: string | null

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

Github​

Interface: GithubOptions

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.

Extends​

Properties​

channel?​

readonly optional channel?: string | null

The channel.

Default​

latest

host?​

readonly optional host?: string | null

The host (including the port if need).

Default​

github.com

owner?​

readonly optional owner?: string | null

The owner.

private?​

readonly optional private?: boolean | null

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

protocol?​

readonly optional protocol?: "https" | "http" | null

The protocol. GitHub Publisher supports only https.

Default​

https

provider​

readonly provider: "github"

The provider. Must be github.

Overrides​

PublishConfiguration.provider

publishAutoUpdate?​

readonly optional publishAutoUpdate?: boolean

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.

Default​

true

Inherited from​

PublishConfiguration.publishAutoUpdate

releaseType?​

optional releaseType?: "draft" | "prerelease" | "release" | null

The type of release. By default draft release will be created.

Also you can set release type using environment variable. If EP_DRAFTis set to true — draft, if EP_PRE_RELEASEis set to true — prerelease.

Default​

draft

repo?​

readonly optional repo?: string | null

The repository name. Detected automatically.

requestHeaders?​

readonly optional requestHeaders?: OutgoingHttpHeaders

Any custom request headers

Inherited from​

PublishConfiguration.requestHeaders

tagNamePrefix?​

readonly optional tagNamePrefix?: string

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

timeout?​

readonly optional timeout?: number | null

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

Default​

120000

Inherited from​

PublishConfiguration.timeout

token?​

readonly optional token?: string | null

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

~~vPrefixedTagName?~~​

readonly optional vPrefixedTagName?: boolean

Whether to use v-prefixed tag name.

Default​

true

Deprecated​

please use #tagNamePrefix instead.

GitLab​

Interface: GitlabOptions

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.

Extends​

Properties​

channel?​

readonly optional channel?: string | null

The channel.

Default​

latest

host?​

readonly optional host?: string | null

The GitLab host (including the port if need).

Default​

gitlab.com

projectId?​

readonly optional projectId?: string | number | null

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

provider​

readonly provider: "gitlab"

The provider. Must be gitlab.

Overrides​

PublishConfiguration.provider

publishAutoUpdate?​

readonly optional publishAutoUpdate?: boolean

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.

Default​

true

Inherited from​

PublishConfiguration.publishAutoUpdate

requestHeaders?​

readonly optional requestHeaders?: OutgoingHttpHeaders

Any custom request headers

Inherited from​

PublishConfiguration.requestHeaders

timeout?​

readonly optional timeout?: number | null

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

Default​

120000

Inherited from​

PublishConfiguration.timeout

token?​

readonly optional token?: string | null

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

uploadTarget?​

readonly optional uploadTarget?: "project_upload" | "generic_package" | null

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

Default​

"project_upload"

vPrefixedTagName?​

readonly optional vPrefixedTagName?: boolean

Whether to use v-prefixed tag name.

Default​

true

Keygen​

Interface: KeygenOptions

Keygen options. https://keygen.sh/ Define KEYGEN_TOKEN environment variable.

Extends​

Properties​

account​

readonly account: string

Keygen account's UUID

channel?​

readonly optional channel?: "stable" | "rc" | "beta" | "alpha" | "dev" | null

The channel.

Default​

stable

host?​

readonly optional host?: string

Keygen host for self-hosted instances

Default​

"api.keygen.sh"

platform?​

readonly optional platform?: string | null

The target Platform. Is set programmatically explicitly during publishing.

product​

readonly product: string

Keygen product's UUID

provider​

readonly provider: "keygen"

The provider. Must be keygen.

Overrides​

PublishConfiguration.provider

publishAutoUpdate?​

readonly optional publishAutoUpdate?: boolean

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.

Default​

true

Inherited from​

PublishConfiguration.publishAutoUpdate

requestHeaders?​

readonly optional requestHeaders?: OutgoingHttpHeaders

Any custom request headers

Inherited from​

PublishConfiguration.requestHeaders

timeout?​

readonly optional timeout?: number | null

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

Default​

120000

Inherited from​

PublishConfiguration.timeout

S3​

Interface: S3Options

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.

Example configuration:

{
 "build":
   "publish": {
     "provider": "s3",
     "bucket": "bucket-name"
   }
 }
}

Extends​

Properties​

accelerate?​

readonly optional 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

acl?​

readonly optional acl?: "private" | "public-read" | null

The ACL. Set to null to not add.

Please see required permissions for the S3 provider.

Default​

public-read

Overrides​

BaseS3Options.acl

bucket​

readonly bucket: string

The bucket name.

channel?​

optional channel?: string | null

The update channel.

Default​

latest

Inherited from​

BaseS3Options.channel

encryption?​

readonly optional encryption?: "AES256" | "aws:kms" | null

Server-side encryption algorithm to use for the object.

endpoint?​

readonly optional endpoint?: string | null

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.

forcePathStyle?​

readonly optional forcePathStyle?: boolean

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

path?​

readonly optional path?: string | null

The directory path.

Default​

/

Inherited from​

BaseS3Options.path

provider​

readonly provider: "s3"

The provider. Must be s3.

Overrides​

BaseS3Options.provider

publishAutoUpdate?​

readonly optional publishAutoUpdate?: boolean

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.

Default​

true

Inherited from​

BaseS3Options.publishAutoUpdate

region?​

optional region?: string | null

The region. Is determined and set automatically when publishing.

requestHeaders?​

readonly optional requestHeaders?: OutgoingHttpHeaders

Any custom request headers

Inherited from​

BaseS3Options.requestHeaders

storageClass?​

readonly optional storageClass?: "STANDARD" | "REDUCED_REDUNDANCY" | "STANDARD_IA" | null

The type of storage to use for the object.

Default​

STANDARD

timeout?​

readonly optional timeout?: number | null

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

Default​

120000

Inherited from​

BaseS3Options.timeout

Snap Store​

Interface: SnapStoreOptions

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

Extends​

Properties​

channels?​

readonly optional channels?: string | string[] | null

The list of channels the snap would be released.

Default​

["edge"]

provider​

readonly provider: "snapStore"

The provider. Must be snapStore.

Overrides​

PublishConfiguration.provider

publishAutoUpdate?​

readonly optional publishAutoUpdate?: boolean

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.

Default​

true

Inherited from​

PublishConfiguration.publishAutoUpdate

repo?​

readonly optional repo?: string

snapcraft repo name

requestHeaders?​

readonly optional requestHeaders?: OutgoingHttpHeaders

Any custom request headers

Inherited from​

PublishConfiguration.requestHeaders

timeout?​

readonly optional timeout?: number | null

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

Default​

120000

Inherited from​

PublishConfiguration.timeout

Spaces​

Interface: SpacesOptions

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

Extends​

Properties​

acl?​

readonly optional acl?: "private" | "public-read" | null

The ACL. Set to null to not add.

Default​

public-read

Inherited from​

BaseS3Options.acl

channel?​

optional channel?: string | null

The update channel.

Default​

latest

Inherited from​

BaseS3Options.channel

name​

readonly name: string

The space name.

path?​

readonly optional path?: string | null

The directory path.

Default​

/

Inherited from​

BaseS3Options.path

provider​

readonly provider: "spaces"

The provider. Must be spaces.

Overrides​

BaseS3Options.provider

publishAutoUpdate?​

readonly optional publishAutoUpdate?: boolean

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.

Default​

true

Inherited from​

BaseS3Options.publishAutoUpdate

region​

readonly region: string

The region (e.g. nyc3).

requestHeaders?​

readonly optional requestHeaders?: OutgoingHttpHeaders

Any custom request headers

Inherited from​

BaseS3Options.requestHeaders

timeout?​

readonly optional timeout?: number | null

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

Default​

120000

Inherited from​

BaseS3Options.timeout

BYO Generic (create-your-own)​

(And maybe submit it upstream in a PR!) {!./builder-util-runtime.Interface.GenericServerOptions.md!}