From 081d18f9ca1a942e1556e6a1994972643b3ae797 Mon Sep 17 00:00:00 2001 From: sylviamoss Date: Tue, 15 Dec 2020 10:28:17 +0100 Subject: [PATCH 1/4] write plugin release step by step docs --- website/content/docs/extending/plugins.mdx | 30 ++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/website/content/docs/extending/plugins.mdx b/website/content/docs/extending/plugins.mdx index ff5607b4d..4cd2ce443 100644 --- a/website/content/docs/extending/plugins.mdx +++ b/website/content/docs/extending/plugins.mdx @@ -257,6 +257,36 @@ with "packer-builder-custom". Log output is _extremely_ helpful in debugging issues and you're encouraged to be as verbose as you need to be in order for the logs to be helpful. +### Creating a GitHub Release + +To create a GitHub release with the right assets that will be consumed by Packer, we provide a pre-defined release workflow configuration +using [GitHub Actions](https://docs.github.com/en/free-pro-team@latest/actions). We strongly encourage maintainers to use this configuration, +to make sure the release contains the necessary expected by Packer when loading a plugin. +[GitHub Actions](https://docs.github.com/en/free-pro-team@latest/actions) allow you to execute workflows when events on your repository occur. +You can use this to create releases whenever a new version tag is created on your repository. + +Here's what you need to use GitHub Actions to create releases: +1. Generate a GPG key to be used when signing releases (See [GitHub's detailed instructions](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/generating-a-new-gpg-key) +for help with this step) +2. Copy the [GoReleaser configuration from the packer-plugin-scaffolding repository](https://github.com/hashicorp/packer-plugin-scaffolding) to the root of your repository. +3. Copy the [GitHub Actions workflow from the packer-plugin-scaffolding repository](https://github.com/hashicorp/packer-plugin-scaffolding) to `.github/workflows/release.yml` in your repository. +4. Go to Settings > Secrets in your repository, and add the following secrets: + - `GPG_PRIVATE_KEY` - Your ASCII-armored GPG private key. You can export this with `gpg --armor --export-secret-keys [key ID or email]`. + - `PASSPHRASE` - The passphrase for your GPG private key. +5. Push a new valid version tag (e.g. `v1.2.3`) to test that the GitHub Actions releaser is working. +6. Make sure to [register your plugin](#registering-the-plugin) with us. + +### Registering the Plugin + +We like to keep all of our products and external plugins release assets together in the same place. To publish +an external plugin to [https://releases.hashicorp.com](https://releases.hashicorp.com), we require the maintainer's GPG public key to validate the asset authenticity. +To register your plugin with HashiCorp, send us your GPG public key and your plugin's GitHub repository via [maintainers@hashicorp.com](mailto://maintainers@hashicorp.com). + +To get you GPG public key in ASCII-armor format, use the following command, substituting the GPG key ID or email address: +```bash +$ gpg --armor --export "{Key ID or email address}" +``` + ### Plugin Development Tips Here are some tips for developing plugins, often answering common questions or From af316bbc9795ea4dc2988ec97a4539268b746595 Mon Sep 17 00:00:00 2001 From: sylviamoss Date: Tue, 15 Dec 2020 12:38:03 +0100 Subject: [PATCH 2/4] add more information to release doc --- website/content/docs/extending/plugins.mdx | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/website/content/docs/extending/plugins.mdx b/website/content/docs/extending/plugins.mdx index 4cd2ce443..65d82dd5f 100644 --- a/website/content/docs/extending/plugins.mdx +++ b/website/content/docs/extending/plugins.mdx @@ -259,13 +259,13 @@ the logs to be helpful. ### Creating a GitHub Release -To create a GitHub release with the right assets that will be consumed by Packer, we provide a pre-defined release workflow configuration -using [GitHub Actions](https://docs.github.com/en/free-pro-team@latest/actions). We strongly encourage maintainers to use this configuration, -to make sure the release contains the necessary expected by Packer when loading a plugin. +To create a GitHub release with the assets that will be consumed by Packer, we provide a pre-defined release workflow configuration +using [GitHub Actions](https://docs.github.com/en/free-pro-team@latest/actions). We strongly encourage maintainers to use this configuration +to make sure the release contains the expected by Packer when loading a plugin. [GitHub Actions](https://docs.github.com/en/free-pro-team@latest/actions) allow you to execute workflows when events on your repository occur. You can use this to create releases whenever a new version tag is created on your repository. -Here's what you need to use GitHub Actions to create releases: +Here's what you need to create releases using GitHub Actions: 1. Generate a GPG key to be used when signing releases (See [GitHub's detailed instructions](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/generating-a-new-gpg-key) for help with this step) 2. Copy the [GoReleaser configuration from the packer-plugin-scaffolding repository](https://github.com/hashicorp/packer-plugin-scaffolding) to the root of your repository. @@ -273,9 +273,12 @@ for help with this step) 4. Go to Settings > Secrets in your repository, and add the following secrets: - `GPG_PRIVATE_KEY` - Your ASCII-armored GPG private key. You can export this with `gpg --armor --export-secret-keys [key ID or email]`. - `PASSPHRASE` - The passphrase for your GPG private key. -5. Push a new valid version tag (e.g. `v1.2.3`) to test that the GitHub Actions releaser is working. +5. Push a new valid version tag (e.g. `v1.2.3`) to test that the GitHub Actions releaser is working. The tag must be a valid [Semantic Version](https://semver.org/) preceded with a `v`. 6. Make sure to [register your plugin](#registering-the-plugin) with us. +~> **Important:** Avoid modifying or replacing an already-released version of a plugin. Instead, if changes are necessary, +please release as a new version. + ### Registering the Plugin We like to keep all of our products and external plugins release assets together in the same place. To publish From 180feebaea48f0af5eef1843616fbaebb07a3e87 Mon Sep 17 00:00:00 2001 From: sylviamoss Date: Tue, 15 Dec 2020 12:52:40 +0100 Subject: [PATCH 3/4] make releases link prettier --- website/content/docs/extending/plugins.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/extending/plugins.mdx b/website/content/docs/extending/plugins.mdx index 65d82dd5f..f92787086 100644 --- a/website/content/docs/extending/plugins.mdx +++ b/website/content/docs/extending/plugins.mdx @@ -282,7 +282,7 @@ please release as a new version. ### Registering the Plugin We like to keep all of our products and external plugins release assets together in the same place. To publish -an external plugin to [https://releases.hashicorp.com](https://releases.hashicorp.com), we require the maintainer's GPG public key to validate the asset authenticity. +an external plugin to [releases.hashicorp.com](https://releases.hashicorp.com), we require the maintainer's GPG public key to validate the asset authenticity. To register your plugin with HashiCorp, send us your GPG public key and your plugin's GitHub repository via [maintainers@hashicorp.com](mailto://maintainers@hashicorp.com). To get you GPG public key in ASCII-armor format, use the following command, substituting the GPG key ID or email address: From 85eb704770e254c7902a6e0a0dba6eee90ae55e9 Mon Sep 17 00:00:00 2001 From: sylviamoss Date: Tue, 15 Dec 2020 14:59:25 +0100 Subject: [PATCH 4/4] improve text --- website/content/docs/extending/plugins.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/extending/plugins.mdx b/website/content/docs/extending/plugins.mdx index f92787086..9440e8a0b 100644 --- a/website/content/docs/extending/plugins.mdx +++ b/website/content/docs/extending/plugins.mdx @@ -261,7 +261,7 @@ the logs to be helpful. To create a GitHub release with the assets that will be consumed by Packer, we provide a pre-defined release workflow configuration using [GitHub Actions](https://docs.github.com/en/free-pro-team@latest/actions). We strongly encourage maintainers to use this configuration -to make sure the release contains the expected by Packer when loading a plugin. +to make sure the release contains the assets expected by Packer to load and use a plugin. [GitHub Actions](https://docs.github.com/en/free-pro-team@latest/actions) allow you to execute workflows when events on your repository occur. You can use this to create releases whenever a new version tag is created on your repository.