From becf880c087bc7a4da68e6355e5a6efc207ef1ca Mon Sep 17 00:00:00 2001 From: Erick Zhao Date: Mon, 15 Jul 2024 21:19:33 +0000 Subject: [PATCH] GITBOOK-191: Standardize Publisher docs --- config/publishers/bitbucket.md | 29 +++++++------------- config/publishers/electron-release-server.md | 12 ++++++-- config/publishers/gcs.md | 24 +++++++++++----- config/publishers/github.md | 18 ++++++++---- config/publishers/nucleus.md | 12 +++++--- config/publishers/s3.md | 14 ++++++++-- config/publishers/snapcraft.md | 18 +++++++++--- 7 files changed, 83 insertions(+), 44 deletions(-) diff --git a/config/publishers/bitbucket.md b/config/publishers/bitbucket.md index 29fa5d5..b06f0e0 100644 --- a/config/publishers/bitbucket.md +++ b/config/publishers/bitbucket.md @@ -1,19 +1,21 @@ ---- -description: >- - The Bitbucket publish target allows you to publish your artifacts directly to - Bitbucket where users will be able to download them. ---- - # Bitbucket +The Bitbucket publish target allows you to publish your artifacts directly to Bitbucket where users will be able to download them. + {% hint style="warning" %} This publish target is for [Bitbucket Cloud](https://bitbucket.org) only and will not work with self hosted Bitbucket Server instances. {% endhint %} -Full configuration options are documented in [`PublisherBitbucketConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_publisher\_bitbucket.PublisherBitbucketConfig.html). +## Installation + +```bash +npm install --save-dev @electron-forge/publisher-bitbucket +``` ## Usage +To use `@electron-forge/publisher-bitbucket`, add it to the `publishers` array in your [Forge configuration](../configuration.md): + {% code title="forge.config.js" %} ```javascript module.exports = { @@ -37,18 +39,7 @@ module.exports = { ``` {% endcode %} -you can (and should) use environment variables for the authentication - -{% code title="env.sh" %} -```bash -BITBUCKET_USERNAME="myusername" -BITBUCKET_APP_PASSWORD="mysecretapppassword" -``` -{% endcode %} - -```bash -$ source env.sh -``` +Full configuration options are documented in [`PublisherBitbucketConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_publisher\_bitbucket.PublisherBitbucketConfig.html). {% hint style="info" %} Your artifacts can be found under the `Downloads` tab of your Bitbucket repository. diff --git a/config/publishers/electron-release-server.md b/config/publishers/electron-release-server.md index 71a559d..0460dda 100644 --- a/config/publishers/electron-release-server.md +++ b/config/publishers/electron-release-server.md @@ -4,9 +4,15 @@ The Electron Release Server target publishes all your artifacts to a hosted inst Please note that Electron Release Server is a community powered project and is not associated with Electron Forge or the Electron project directly. -Configuration options are documented in [`PublisherERSConfig`](https://js.electronforge.io/interfaces/_electron_forge_publisher_electron_release_server.PublisherERSConfig.html). +## Installation -### Usage +```bash +npm install --save-dev @electron-forge/publisher-electron-release-server +``` + +## Usage + +To use `@electron-forge/publisher-electron-release-server`, add it to the `publishers` array in your [Forge configuration](../configuration.md): {% code title="forge.config.js" %} ```javascript @@ -25,3 +31,5 @@ module.exports = { }; ``` {% endcode %} + +Configuration options are documented in [`PublisherERSConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_publisher\_electron\_release\_server.PublisherERSConfig.html). diff --git a/config/publishers/gcs.md b/config/publishers/gcs.md index 3ac679b..ce1dd27 100644 --- a/config/publishers/gcs.md +++ b/config/publishers/gcs.md @@ -10,15 +10,15 @@ This Publisher was added in Electron Forge **v7.1.0**. The Google Cloud Storage target publishes all your artifacts to a [Google Cloud Storage bucket](https://cloud.google.com/storage/docs). -## Authentication +## Installation -Under the hood, the Google Cloud Storage Publisher uses the `@google-cloud/storage` SDK and its associated authentication options. - -We recommend following [Google's authentication documentation for client libraries](https://cloud.google.com/docs/authentication/client-libraries#node.js) to get authentication configured. +```bash +npm install --save-dev @electron-forge/publisher-gcs +``` ## Usage -To pass options into the Google Cloud Storage SDK's [Storage constructor](https://cloud.google.com/nodejs/docs/reference/storage/latest/storage/storageoptions), use the `config.storageOptions` parameter. +To use `@electron-forge/publisher-gcs`, add it to the `publishers` array in your [Forge configuration](../configuration.md): {% code title="forge.config.js" %} ```javascript @@ -42,14 +42,24 @@ module.exports = { ``` {% endcode %} +Additional configuration options are documented in [`PublisherGCSConfig`](http://js.electronforge.io/interfaces/\_electron\_forge\_publisher\_gcs.PublisherGCSConfig.html). + +To pass options into the Google Cloud Storage SDK's [Storage constructor](https://cloud.google.com/nodejs/docs/reference/storage/latest/storage/storageoptions), use the `config.storageOptions` parameter. + +### Output location + When executed, the Publisher will publish to your GCS bucket under the following key: ``` ${config.folder || version}/${artifactName} ``` -Additional configuration options are documented in [`PublisherGCSConfig`](http://js.electronforge.io/interfaces/\_electron\_forge\_publisher\_gcs.PublisherGCSConfig.html). - {% hint style="warning" %} If you run publish twice with the same version on the same platform, it is possible for your old artifacts to get overwritten in Storage. It is your responsibility to ensure that you don't overwrite your own releases. {% endhint %} + +### Authentication + +Under the hood, the Google Cloud Storage Publisher uses the `@google-cloud/storage` SDK and its associated authentication options. + +We recommend following [Google's authentication documentation for client libraries](https://cloud.google.com/docs/authentication/client-libraries#node.js) to get authentication configured. diff --git a/config/publishers/github.md b/config/publishers/github.md index 7d2bbe4..5031eac 100644 --- a/config/publishers/github.md +++ b/config/publishers/github.md @@ -1,15 +1,17 @@ # GitHub -The GitHub target publishes all your artifacts to GitHub releases, this allows your users to download the files straight from your repository or if your repository is open source you can use [update.electronjs.org](https://github.com/electron/update.electronjs.org) and get a free hosted update service. +The GitHub target publishes all your artifacts to GitHub releases, this allows your users to download the files straight from your repository. If your repository is open source you can use [update.electronjs.org](https://github.com/electron/update.electronjs.org) and get a free hosted update service. -Configuration options are documented in [`PublisherGitHubConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_publisher\_github.PublisherGitHubConfig.html) +## Installation -{% hint style="info" %} -You can use this target to publish to GitHub Enterprise using the host configuration options of `octokitOptions`. Check out the configuration options linked above. -{% endhint %} +```bash +npm install --save-dev @electron-forge/publisher-github +``` ## Usage +To use `@electron-forge/publisher-github`, add it to the `publishers` array in your [Forge configuration](../configuration.md): + {% code title="forge.config.js" %} ```javascript module.exports = { @@ -30,6 +32,12 @@ module.exports = { ``` {% endcode %} +Configuration options are documented in [`PublisherGitHubConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_publisher\_github.PublisherGitHubConfig.html). + +### Uploading to GitHub Enterprise instances + +You can use this target to publish to GitHub Enterprise using the host configuration options of `octokitOptions`. Check out the configuration options linked above. + ### Auto updating from GitHub Updating from a GitHub release for a **public** repository is as simple as adding the [`update-electron-app`](https://github.com/electron/update-electron-app) module to your app's main process. diff --git a/config/publishers/nucleus.md b/config/publishers/nucleus.md index 09ae4a8..aad13b6 100644 --- a/config/publishers/nucleus.md +++ b/config/publishers/nucleus.md @@ -2,14 +2,16 @@ The Nucleus target publishes all your artifacts to an instance of Nucleus Update Server, this update service supports all three platforms. Check out the README at [`atlassian/nucleus`](https://github.com/atlassian/nucleus) for more information on this project. -Configuration options are documented in [`PublisherNucleusConfig`](https://js.electronforge.io/interfaces/_electron_forge_publisher_nucleus.PublisherNucleusConfig.html) +## Installation -{% hint style="warning" %} -We recommend you set the `token` option using an environment variable, don't hard code it into your config -{% endhint %} +```bash +npm install --save-dev @electron-forge/publisher-nucleus +``` ## Usage +To use `@electron-forge/publisher-nucleus`, add it to the `publishers` array in your [Forge configuration](../configuration.md): + {% code title="forge.config.js" %} ```javascript module.exports = { @@ -28,3 +30,5 @@ module.exports = { }; ``` {% endcode %} + +Configuration options are documented in [`PublisherNucleusConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_publisher\_nucleus.PublisherNucleusConfig.html). diff --git a/config/publishers/s3.md b/config/publishers/s3.md index e89c070..0bd73ca 100644 --- a/config/publishers/s3.md +++ b/config/publishers/s3.md @@ -6,13 +6,15 @@ description: How to publish your distributable Electron app artifacts to Amazon The S3 target publishes your Make artifacts to an Amazon S3 bucket. -## Authentication +## Installation -It is recommended to follow the [Amazon AWS guide](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-credentials-node.html) and set either a shared credentials guide or the proper environment variables. However, if that is not possible, the publisher config allows the setting of the `accessKeyId` and `secretAccessKey` configuration options. +```bash +npm install --save-dev @electron-forge/publisher-s3 +``` ## Usage -Configuration options are documented in [`PublisherS3Config`](https://js.electronforge.io/interfaces/\_electron\_forge\_publisher\_s3.PublisherS3Config.html). +To use `@electron-forge/publisher-s3`, add it to the `publishers` array in your [Forge configuration](../configuration.md): {% code title="forge.config.js" %} ```javascript @@ -31,6 +33,12 @@ module.exports = { ``` {% endcode %} +Configuration options are documented in [`PublisherS3Config`](https://js.electronforge.io/interfaces/\_electron\_forge\_publisher\_s3.PublisherS3Config.html). + +### Authentication + +It is recommended to follow the [Amazon AWS guide](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-credentials-node.html) and set either a shared credentials guide or the proper environment variables. However, if that is not possible, the publisher config allows the setting of the `accessKeyId` and `secretAccessKey` configuration options. + ### Key management By default, the S3 publisher will upload its objects to the `{prefix}/{platform}/{arch}/{name}` key, where: diff --git a/config/publishers/snapcraft.md b/config/publishers/snapcraft.md index 6ceebef..160c7f2 100644 --- a/config/publishers/snapcraft.md +++ b/config/publishers/snapcraft.md @@ -1,12 +1,20 @@ # Snapcraft -The Snapcraft target publishes your `.snap` artifacts to the [Snap Store](https://snapcraft.io/store). All configuration of your package is done via the [Snapcraft maker](../makers/snapcraft.md). +The Snapcraft target publishes your `.snap` artifacts to the [Snap Store](https://snapcraft.io/store). All configuration of your package is done via the [snapcraft.md](../makers/snapcraft.md "mention") maker. -This target requires that the system has the `snapcraft` utility installed. +## Requirements -Configuration options are documented in [`PublisherSnapConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_publisher\_snapcraft.PublisherSnapcraftConfig.html) +You can only publish to the Snap Store on Linux systems with the [`snapcraft`](https://snapcraft.io/) package installed. -### Usage +## Installation + +```bash +npm install --save-dev @electron-forge/publisher-snapcraft +``` + +## Usage + +To use `@electron-forge/publisher-snapcraft`, add it to the `publishers` array in your [Forge configuration](../configuration.md): {% code title="forge.config.js" %} ```javascript @@ -23,3 +31,5 @@ module.exports = { }; ``` {% endcode %} + +Configuration options are documented in [`PublisherSnapConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_publisher\_snapcraft.PublisherSnapcraftConfig.html).