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.
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"}]
.
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"]
--publish
option values:
Value | Description |
---|---|
onTag |
on tag push only |
onTagOrDraft |
on tag push or if draft release exists |
always |
always publish |
never |
never 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.
Recommended GitHub Releases Workflow¶
-
Draft a new release. Set the “Tag version” to the value of
version
in your applicationpackage.json
, and prefix it withv
. “Release title” can be anything you want.For example, if your application
package.json
version is1.0
, your draft’s “Tag version” would bev1.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 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).
- Setup your CI to publish on each commit. E.g.
"dist": "electron-builder --publish always"
in yourpackage.json
. - Set your version in your application
package.json
to1.9.0-snapshot
(or1.9.0-master
or whatever you want your development channel to be named). This will publish a file namedsnapshot.yml
and a build namedsomething-snapshot.exe
(and corresponding for mac) to S3. - When you are ready to deploy, simply change you package version to
1.9.0
and push. This will then produce alatest.yml
andsomething.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¶
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¶
Options Available: - GenericServerOptions - GithubOptions - SnapStoreOptions - SpacesOptions - KeygenOptions - BitbucketOptions - S3Options
GenericServerOptions
Generic (any HTTP(S) server) options. In all publish options File Macros are supported.
provider
“generic” - The provider. Must begeneric
.url
String - The base url. e.g.https://bucket_name.s3.amazonaws.com
.channel
=latest
String | “undefined” - The channel.useMultipleRangeRequest
Boolean - Whether to use multiple range requests for differential update. Defaults totrue
ifurl
doesn’t contains3.amazonaws.com
.
Inherited from PublishConfiguration
:
-
publishAutoUpdate
=true
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.
-
requestHeaders
module:http.OutgoingHttpHeaders - Any custom request headers -
timeout
=120000
Number | “undefined” - Request timeout in milliseconds. (Default is 2 minutes; O is ignored)
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.
-
provider
“github” - The provider. Must begithub
. -
repo
String | “undefined” - The repository name. Detected automatically. -
owner
String | “undefined” - The owner. -
vPrefixedTagName
=true
Boolean - Whether to usev
-prefixed tag name. -
host
=github.com
String | “undefined” - The host (including the port if need). -
protocol
=https
“https” | “http” | “undefined” - The protocol. GitHub Publisher supports onlyhttps
. -
token
String | “undefined” - The access token to support auto-update from private github repositories. Never specify it in the configuration files. Only for setFeedURL. -
private
Boolean | “undefined” - Whether to use private github auto-update provider ifGH_TOKEN
environment variable is defined. See Private GitHub Update Repo. -
channel
=latest
String | “undefined” - The channel. -
releaseType
=draft
“draft” | “prerelease” | “release” | “undefined” - The type of release. By defaultdraft
release will be created.Also you can set release type using environment variable. If
EP_DRAFT
is set totrue
—draft
, ifEP_PRE_RELEASE
is set totrue
—prerelease
.
Inherited from PublishConfiguration
:
-
publishAutoUpdate
=true
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.
-
requestHeaders
module:http.OutgoingHttpHeaders - Any custom request headers -
timeout
=120000
Number | “undefined” - Request timeout in milliseconds. (Default is 2 minutes; O is ignored)
SnapStoreOptions
Snap Store options. To publish directly to Snapcraft, see Snapcraft authentication options for local or CI/CD authentication options.
provider
“snapStore” - The provider. Must besnapStore
.repo
String - snapcraft repo namechannels
=["edge"]
String | Array<String> | “undefined” - The list of channels the snap would be released.
Inherited from PublishConfiguration
:
-
publishAutoUpdate
=true
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.
-
requestHeaders
module:http.OutgoingHttpHeaders - Any custom request headers -
timeout
=120000
Number | “undefined” - Request timeout in milliseconds. (Default is 2 minutes; O is ignored)
SpacesOptions
DigitalOcean Spaces options.
Access key is required, define DO_KEY_ID
and DO_SECRET_KEY
environment variables.
provider
“spaces” - The provider. Must bespaces
.name
String - The space name.region
String - The region (e.g.nyc3
).channel
=latest
String | “undefined” - The update channel.path
=/
String | “undefined” - The directory path.acl
=public-read
“private” | “public-read” | “undefined” - The ACL. Set tonull
to not add.
KeygenOptions
Keygen options.
https://keygen.sh/
Define KEYGEN_TOKEN
environment variable.
provider
“keygen” - The provider. Must bekeygen
.account
String - Keygen account’s UUIDproduct
String - Keygen product’s UUIDchannel
=stable
“stable” | “rc” | “beta” | “alpha” | “dev” | “undefined” - The channel.platform
String | “undefined” - The target Platform. Is set programmatically explicitly during publishing.
Inherited from PublishConfiguration
:
-
publishAutoUpdate
=true
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.
-
requestHeaders
module:http.OutgoingHttpHeaders - Any custom request headers -
timeout
=120000
Number | “undefined” - Request timeout in milliseconds. (Default is 2 minutes; O is ignored)
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}`
}
provider
“bitbucket” - The provider. Must bebitbucket
.owner
String - Repository ownertoken
String | “undefined” - The app password to support auto-update from private bitbucket repositories.username
String | “undefined” - The user name to support auto-update from private bitbucket repositories.slug
String - Repository slug/namechannel
=latest
String | “undefined” - The channel.
Inherited from PublishConfiguration
:
-
publishAutoUpdate
=true
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.
-
requestHeaders
module:http.OutgoingHttpHeaders - Any custom request headers -
timeout
=120000
Number | “undefined” - Request timeout in milliseconds. (Default is 2 minutes; O is ignored)
S3Options
Amazon S3 options.
AWS credentials are required, please see getting your credentials.
Define AWS_ACCESS_KEY_ID
and AWS_SECRET_ACCESS_KEY
environment variables.
Or in the ~/.aws/credentials.
Example configuration:
{
"build":
"publish": {
"provider": "s3",
"bucket": "bucket-name"
}
}
}
-
provider
“s3” - The provider. Must bes3
. -
bucket
String - The bucket name. -
region
String | “undefined” - The region. Is determined and set automatically when publishing. -
acl
=public-read
“private” | “public-read” | “undefined” - The ACL. Set tonull
to not add.Please see required permissions for the S3 provider.
-
storageClass
=STANDARD
“STANDARD” | “REDUCED_REDUNDANCY” | “STANDARD_IA” | “undefined” - The type of storage to use for the object. -
encryption
“AES256” | “aws:kms” | “undefined” - Server-side encryption algorithm to use for the object. -
endpoint
String | “undefined” - The endpoint URI to send requests to. The default endpoint is built from the configured region. The endpoint should be a string likehttps://{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 -
channel
=latest
String | “undefined” - The update channel. -
path
=/
String | “undefined” - The directory path.
CustomPublishOptions
undefined
provider
“custom” - The provider. Must becustom
.updateProvider
module:builder-util-runtime/out/publishOptions.__type - The Provider to provide UpdateInfo regarding available updates. Required to use custom providers with electron-updater.
Inherited from PublishConfiguration
:
-
publishAutoUpdate
=true
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.
-
requestHeaders
module:http.OutgoingHttpHeaders - Any custom request headers -
timeout
=120000
Number | “undefined” - Request timeout in milliseconds. (Default is 2 minutes; O is ignored)