update extensions build chart workflow to only work with tagged relea…

…ses (rancher#11946) * update extensions build chart workflow to only work with tagged releases * improve docs on publishing extensions * Update docusaurus/docs/extensions/publishing.md Co-authored-by: Jordon Leach <[email protected]> * Update docusaurus/docs/extensions/publishing.md Co-authored-by: Jordon Leach <[email protected]> * Update docusaurus/docs/extensions/publishing.md Co-authored-by: Jordon Leach <[email protected]> * Update docusaurus/docs/extensions/publishing.md Co-authored-by: Jordon Leach <[email protected]> --------- Co-authored-by: Jordon Leach <[email protected]>
aalves08 · Sep 20, 2024 · b8ad980 · b8ad980
1 parent 437aef0
commit b8ad980
Show file tree

Hide file tree

Showing 2 changed files with 60 additions and 101 deletions.
diff --git a/.github/workflows/build-extension-charts.yml b/.github/workflows/build-extension-charts.yml
@@ -7,7 +7,7 @@ on:
         required: true
         type: string
       tagged_release:
-        required: false
+        required: true
         type: string
 
 env:

diff --git a/docusaurus/docs/extensions/publishing.md b/docusaurus/docs/extensions/publishing.md
@@ -9,7 +9,58 @@ As discussed in the [Getting Started](./extensions-getting-started#creating-a-re
 
 > Note: An explanation on the workflow files can be found in the [Additional Release Configuration](#additional-release-configuration) section.
 
-# Publish Script Usage
+## Automatic Approach - Triggering a Github Workflow on Tagged Release
+
+If your extensions repository doesn't include a github workflow to automate the publishing procedure (ignore this step if you have it already), you can create one in `.github/workflows/build.yaml` on your extension folder, with the following content:
+
+```yaml
+name: Build and Release Extension Charts
+
+on:
+  workflow_dispatch:
+  release:
+    types: [released]
+
+defaults:
+  run:
+    shell: bash
+    working-directory: ./
+
+jobs:
+  build-extension-charts:
+    uses: rancher/dashboard/.github/workflows/build-extension-charts.yml@master
+    permissions:
+      actions: write
+      contents: write
+      deployments: write
+      pages: write
+    with:
+      target_branch: gh-pages
+      tagged_release: ${{ github.ref_name }}
+```
+
+This will leverage the usage of our reusable workflow and give your Github extension repo the ability to publish to the `gh-pages` branch via a **Tagged Release**. 
+
+It's mandatory that release type is **Tagged Release**, otherwise the `build-extension-charts.yml` workflow won't run properly, which is crucial for the success of the publish operation.
+
+When creating a Tagged Release, the tag name **_MUST_** match the proper Extension name depending on the type of build. As it was mentioned above, the Extension Charts (published in the specified branch) and ECI (published in the specified registry) are determined by different versions.
+
+### Proper Tagged Release naming scheme to build Extension Charts
+
+- The name **_MUST_** match the Extension Package folder name (`./pkg/<-YOUR-EXT-DIR->`), followed by the version (determined by the `version` property in `./pkg/<-YOUR-EXT-DIR->/package.json`). 
+
+  If the extension folder in named **my-awesome-extension** and the `version` property value in `./pkg/<-YOUR-EXT-DIR->/package.json` is **1.2.3**, then a correct tag to build the Extension Helm Chart would be: `my-awesome-extension-1.2.3`
+
+### Proper Tagged Release naming scheme to build Extension Catalog Image
+
+The name **_MUST_** match the main Extension name (determined by the `name` property in `./package.json`) followed by the version (determined by the `name` property in `./package.json`). 
+
+  If the `name` property in `./package.json` is **my-extension** and the `version` property is **8.0.1**, then a correct tag to build the Catalog Image would be: `my-extension-8.0.1`
+
+---
+
+
+## Manual Approach - Publish Script Usage
 
 **_Usage_**
 
@@ -28,7 +79,7 @@ Usage: yarn publish-pkgs [<options>] [plugins]
   -l           Specify Podman container build
 ```
 
-# Manually Publishing the Extension Helm Charts
+## Manually Publishing the Extension Helm Charts
 
 > Note: Currently, we only support publishing Extension Helm charts into a **public** Github repository, if you inted to deploy an extension from a private repository/registry, we recommend utilizing the [Extension Catalog Image](#manually-publishing-an-extension-catalog-image) method.
 
@@ -37,7 +88,7 @@ Running this script will bundle each extension package as a node.js app, create
 
 After the Helm assets have been built, you will need to commit them into a publicly accessible Github repository. This repository will then need to be added into the Cluster Repositories list within a Rancher instance, that will then populate the Extension marketplace with the charts built from the previous step.
 
-## Prerequisites
+### Prerequisites
 
 > Note: This has been tested on Linux and MacOS machines
 
@@ -50,7 +101,7 @@ This method requires a few tools to be installed:
 - [yq](https://github.com/mikefarah/yq/#install) ( >= `4.0.0` )
 - [helm](https://helm.sh/docs/intro/install/) ( >= `3.0.0` )
 
-## Running the Publish Script
+### Running the Publish Script to generate the extension Helm Chart
 
 To start the build, run the `publish-pkgs` script with two options:
 
@@ -83,11 +134,11 @@ git push origin production
 
 Once the files are accessible on Github, add the repository within the Rancher "local" cluster - The charts will then be available on the Extensions page, under the "Available" tab.
 
-# Manually Publishing an Extension Catalog Image
+## Manually Publishing an Extension Catalog Image
 
 Publishing an ECI into the registry of your choice can also be accomplished with the `publish-pkgs` script declared in the extension's `package.json`. This script will build a Docker image for each extension package, as well as a Helm chart that can be used to deploy the images. Given the option, the script can automatically push the built images and chart into a specified registry.
 
-## Prerequisites
+### Prerequisites
 
 Publishing an ECI has a few requirements, namely:
 
@@ -106,7 +157,7 @@ This method also requires a few tools to be installed:
 - [yq](https://github.com/mikefarah/yq/#install) ( >= `4.0.0` )
 - [helm](https://helm.sh/docs/intro/install/) ( >= `3.0.0` )
 
-## Running the Publish Script
+### Running the Publish Script for a Catalog Image
 
 You can simply run the `publish-pkgs` script with three options:
 
@@ -128,7 +179,7 @@ Running any of the commands above will only build your images - in order to publ
 yarn publish-pkgs -c -p -r <REGISTRY> -o <ORGANIZATION>
 ```
 
-# Additional Release Configuration
+## Additional Release Configuration
 
 Depending on your use case, there are multiple options on building and creating releases. When building an extension within a Github repository, you have the option of utilizing an action that triggers [prebuilt workflows](https://github.com/rancher/dashboard/tree/master/creators/extension/app/files/.github/workflows). When added to your extension, the `./github/workflows` directory will contain the files: `build-extension-charts.yml` and `build-extension-catalog.yml`. These workflows accomplish two seperate actions:
 
@@ -173,95 +224,3 @@ The Pipeline will run automatically when a change to the root level `package.jso
 
 Once the ECI has been published to the Container Registry, it can then be imported into the Rancher UI by following the steps in the [Importing section](./advanced/air-gapped-environments#importing-the-extension-catalog-image).
 
-## Triggering a Github Workflow on Tagged Release
-
-The workflow `build-extension-charts` will create tagged releases whenever a build is published, this is accomplished by the [`helm/chart-releaser-action`](https://github.com/helm/chart-releaser-action). Instead of having the workflow run before a release is tagged, you can modify the workflow file to be triggered by a [tagged release](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#release). This allows you to push code to the `main` branch and create pre-releases without worrying about the automated builds kicking off.
-
-### Requirements
-
-When creating a Tagged Release, the tag name **_MUST_** match the proper Extension name depending on the type of build. As it was mentioned above, the Extension Charts (published in the specified branch) and ECI (published in the specified registry) are determined by different versions.
-
-**Proper Tagged Release naming scheme:**
-
-- _**Extension Charts**_: The name **_MUST_** match the Extension Package name (determined by the package directory name) followed by the version.
-  - For example: `my-extension-package-0.1.1`
-- _**Extension Catalog Image**_: The name **_MUST_** match the main Extension name (determined by the `name` property in `./package.json`) followed by the version
-  - For example: `my-extension-0.1.0`
-
----
-
-### Workflow Configuration
-
-To configure the workflows you will need to modify two sections, namely the [`on`](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on) stanza and the `with` property in both jobs.
-
-**Adding the Tagged Release event:**
-
-```yaml
-on:
-  release:
-    types: [released]
-```
-
-> Note: A `release` event has multiple `types` to specify, `released` will cause the workflow to only be triggered when a release is published and not considered a pre-release. More info can be found in the [Github documentation](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#release).
-
-**Modify the `with` property with the tag**
-
-With a `release` event type configured, you will need to modify the `with` property within each of the workflow jobs by adding the environment variable `tagged_release: ${{ github.ref_name }}`:
-
-```yaml
-with:
-  tagged_release: ${{ github.ref_name }}
-```
-
-This will provide the `publish-pkgs` script within the resuable workflow with the released tag name and ensure only the specified build is accomplished.
-
-### Extension Charts Workflow Example
-
-An example of modifying the `build-extensions.yml` workflow file to build when a tag is released:
-
-```yaml
-# .github/workflows/build-extension-charts.yml
-name: Build and Release Extension Charts
-
-on:
-  release:
-    types: [released]
-...
-jobs:
-  build-extension-artifact:
-    ...
-    with:
-      target_branch: gh-pages
-      tagged_release: ${{ github.ref_name }}
-```
-
-### Extension Catalog Image Workflow Example
-
-The same steps apply for the `build-extension-catalog` job as `${{ github.ref_name }}` will use the commit `ref` name, the release tag in this case, which triggered the action:
-
-```yaml
-# .github/workflows/build-extension-catalog.yml
-name: Build and release Extension Catalog Image to registry
-
-on:
-  release:
-    types: [released]
-
-env:
-  REGISTRY: ghcr.io
-
-jobs:
-  ...
-  build-extension-catalog:
-    ...
-    with:
-      registry_target: ghcr.io
-      registry_user: ${{ github.actor }}
-      tagged_release: ${{ github.ref_name }}
-```
-
-### Sequence of Events
-
-Once the modifications have been made to the workflow files, all that is required for a build to be initiated is to create a Release tag with the desired extension to be built. This will then trigger both of the workflows, the `parse-ext-name` script will determine if the provided tag name matches either the main Extension name or one of the Extension packages names.
-
-If the Tagged Release does not match the main Extension name, the ECI build will be canceled. Alternatively, if the Tagged Release name does not match an Extension package name, it will be skipped.