docs: DOC-2409: GHCR helm chart workaround (#9676)

achuribooks · svetlana-efimova · web-flow · commit ce5c583feb13 · 2026-03-05T08:56:46.000-05:00
* docs: DOC-2409: GHCR registry workaround

* Apply suggestions from code review

* ci: auto-formatting prettier issues

* Minor cleanup; ECR does not need self-certs

* Apply suggestions from code review

* Apply suggestions from code review

Co-authored-by: svetlana-efimova &lt;svetlana.efimova@spectrocloud.com&gt;

* Combining AWS Credential tables

---------

Co-authored-by: achuribooks &lt;182707758+achuribooks@users.noreply.github.com&gt;
Co-authored-by: svetlana-efimova &lt;svetlana.efimova@spectrocloud.com&gt;
diff --git a/_partials/profiles/_add-on-namespace.mdx b/_partials/profiles/_add-on-namespace.mdx
@@ -3,8 +3,10 @@ partial_category: profiles
 partial_name: add-on-namespace
 ---
 
-Configure parameters as needed. Ensure you specify a namespace; otherwise, the manifest will be deployed to the
-`Default` namespace. For examples of Helm-based pack structures, 
+For GitHub Container Registry (GHCR), paste the default chart values and make any necessary changes. For other registries, modify the existing values as necessary.
+
+Ensure you specify a namespace; otherwise, the manifest will be deployed to the
+`default` namespace. For examples of Helm-based pack structures, 
 review our <VersionedLink text="Deploy a Pack" url="/tutorials/packs-registries/deploy-pack#build-a-pack" />
 guide, and select the appropriate tab.
 
diff --git a/docs/docs-content/profiles/cluster-profiles/create-cluster-profiles/create-addon-profile/create-helm-addon.md b/docs/docs-content/profiles/cluster-profiles/create-cluster-profiles/create-addon-profile/create-helm-addon.md
@@ -10,6 +10,9 @@ tags: ["profiles", "cluster profiles", "helm", "add-on"]
 You can extend the list of integrations by adding Helm charts from a public or private registry to your cluster profile.
 Take the following steps to create a cluster profile by adding layers using Helm charts.
 
+For guidance on adding Open Container Initiative (OCI)-based Helm chart registries to Palette, refer to our
+[Add OCI Helm Registry](../../../../registries-and-packs/registries/oci-registry/add-oci-helm.md) guide.
+
 ## Prerequisites
 
 <PartialsComponent category="profiles" name="create-profile-prerequisites" />
@@ -18,7 +21,8 @@ Take the following steps to create a cluster profile by adding layers using Helm
 
 <PartialsComponent category="profiles" name="create-profile-enablement" edition="Add-on" />
 
-5. Select the **Add Helm Chart** drop-down menu and choose **Public packs** or **Private packs**.
+5. From the **Add Helm Chart** drop-down menu, choose **Public packs** or **Private packs**. For GitHub Container
+   Registry (GHCR), select **Private packs**.
 
 <Tabs groupId="registry-type">
 
@@ -37,8 +41,12 @@ Take the following steps to create a cluster profile by adding layers using Helm
 6. To add a chart from a _private_ registry, on the **Profile Layers** page, select a **Registry** from the drop-down
    menu. Next, select **Chart name** and **Chart version**.
 
-7. (Optional) If desired, add configurable **Chart Values** and specify the layer
-   [install order](./create-addon-profile.md#install-order).
+   For GHCR, enter the chart name and version _exactly_ as they appear in the endpoint. For example, for an endpoint of
+   `oci://ghcr.io/controlplaneio-fluxcd/charts/flux-operator:0.39.0`, enter `flux-operator` for the **Chart name** and
+   `0.39.0` for the **Chart version**. For more information on adding Helm charts from GHCR in Palette, refer to our
+   [Add OCI Helm Registry](../../../../registries-and-packs/registries/oci-registry/add-oci-helm.md) guide.
+
+7. (Optional) If desired, specify the layer [install order](./create-addon-profile.md#install-order).
 
 </TabItem>
 
@@ -83,8 +91,12 @@ Take the following steps to create a cluster profile by adding layers using Helm
 5. To add a chart from a _private_ registry, on the **Profile Layers** page, select a **Registry** from the drop-down
    menu. Next, select **Chart name** and **Chart version**.
 
-6. (Optional) If desired, add configurable **Chart Values** and specify the layer
-   [install order](./create-addon-profile.md#install-order).
+   For GHCR, enter the chart name and version _exactly_ as they appear in the endpoint. For example, for an endpoint of
+   `oci://ghcr.io/controlplaneio-fluxcd/charts/flux-operator:0.39.0`, enter `flux-operator` for the **Chart name** and
+   `0.39.0` for the **Chart version**. For more information on adding Helm charts from GHCR in Palette, refer to our
+   [Add OCI Helm Registry](../../../../registries-and-packs/registries/oci-registry/add-oci-helm.md) guide.
+
+6. (Optional) If desired, specify the layer [install order](./create-addon-profile.md#install-order).
 
 </TabItem>
 
diff --git a/docs/docs-content/registries-and-packs/registries/oci-registry/add-oci-helm.md b/docs/docs-content/registries-and-packs/registries/oci-registry/add-oci-helm.md
@@ -4,11 +4,18 @@ title: "Add OCI Helm Registry"
 description: "Learn how to add your own OCI Helm Registry to Palette"
 icon: ""
 hide_table_of_contents: false
+toc_max_heading_level: 2
 sidebar_position: 10
 ---
 
 You can add an OCI type Helm registry to Palette and use the Helm Charts in your cluster profiles.
 
+## Limitations
+
+- GitHub Container Registry (GHCR) is not officially supported at this time. To add a Helm chart from GHCR, you must
+  create a separate OCI Helm registry in Palette for each chart. Refer to the
+  [Add OCI Helm Registry - GHCR](#add-oci-helm-registry) section for more information.
+
 ## Prerequisites
 
 - Tenant admin access to Palette.
@@ -85,127 +92,114 @@ registry you are adding.
 
 <Tabs groupId="registry">
 
-<TabItem value="no-authentication" label="No Authentication">
+<TabItem value="basic" label="Basic">
 
 1. Log in to [Palette](https://console.spectrocloud.com) as a Tenant administrator.
 
 2. From the left main menu, select **Tenant Settings**.
 
 3. From the **Tenant Settings Menu**, select **Registries**.
 
-4. On the**OCI Registries** tab, select **Add New OCI Registry**.
+4. On the **OCI Registries** tab, select **Add New OCI Registry**.
 
-5. Enter the **Name** of the registry. For **Provider** type, select **Helm**.
+5. Enter the **Name** of the registry. For the **Provider** type, select **Helm**.
 
 6. For **OCI Authentication Type**, select **Basic**.
 
-7. Toggle the **Synchronization** option to enable or disable synchronization for the registry. To learn more about the
-   synchronization behavior of Helm registries, refer to the [Helm Registry](../helm-charts.md#synchronization-behavior)
-   resource.
+7. Toggle the **Synchronization** option to enable or disable synchronization for the registry. For more information,
+   refer to the [Helm Registry - Synchronization Behavior](../helm-charts.md#synchronization-behavior) section.
 
 8. Provide the registry URL in the **Endpoint** field.
 
-9. For **Base Content Path**, enter the base path to the repository in the registry where the Helm Charts are stored.
-   You can specify multiple base paths by pressing the **ENTER** key after each path. Providing multiple base paths is
-   useful when Helm Charts are stored in different directories or projects, such as multiple projects in a Harbor
-   registry.
+9. If **Synchronization** is enabled, in the **Base Content Path** field, enter the base path to the repository in the
+   registry where the Helm charts are stored. You can specify multiple base paths by pressing the **ENTER** key after
+   each path. Providing multiple base paths is useful when Helm charts are stored in different directories or projects.
 
-10. Leave the **Username** and **Password** fields empty.
+10. Fill out the **Username** and **Password** fields with the credentials to access the registry. If the registry does
+    not require authentication, leave the **Username** and **Password** fields empty.
 
-11. If your OCI registry server is using a self-signed certificate or if the server certificate is not signed by a
-    trusted CA, check the **Insecure Skip TLS Verify** box to skip verifying the x509 certificate, and click **Upload
-    file** to upload the certificate.
+11. If your OCI registry server is using a self-signed certificate, select **Upload file** to upload the certificate. If
+    the server certificate is not signed by a trusted CA, select **Insecure Skip TLS Verify** to skip verifying the x509
+    certificate.
 
-12. Click **Confirm** to add the registry.
+12. Select **Confirm** to add the registry.
 
 </TabItem>
 
-<TabItem value="basic" label="Basic">
-
-1. Log in to the [Palette](https://console.spectrocloud.com) as a Tenant administrator.
-
-2. From the left **Main Menu** select **Tenant Settings**.
-
-3. From the **Tenant Settings Menu**, Select **Registries**.
-
-4. Click on the **OCI Registries** tab.
-
-5. Click **Add New OCI Registry**.
+<TabItem value="aws" label="Amazon ECR">
 
-6. Fill out the **Name** field and select **Helm** as the provider type.
+1. Log in to [Palette](https://console.spectrocloud.com) as a Tenant administrator.
 
-7. Select the **OCI Authentication Type** as **Basic**.
+2. From the left main menu, select **Tenant Settings**.
 
-8. Toggle the **Synchronization** option to enable or disable synchronization for the registry. To learn more about the
-   synchronization behavior of Helm registries, refer to the [Helm Registry](../helm-charts.md#synchronization-behavior)
-   resource.
+3. From the **Tenant Settings Menu**, select **Registries**.
 
-9. Provide the registry URL in the **Endpoint** field.
+4. On the **OCI Registries** tab, select **Add New OCI Registry**.
 
-10. Specify the base path in the **Base Content Path** field. The base path is the path to the repository in the
-    registry where the Helm Charts are stored. You can specify multiple base paths by pressing the Enter key after each
-    path. Providing multiple base paths is useful when Helm Charts are stored in different directories or projects, such
-    as multiple projects in a Harbor registry.
+5. Enter the **Name** of the registry. For the **Provider** type, select **Helm**.
 
-11. Fill out the **Username** and **Password** fields with the credentials to access the registry.
+6. For **OCI Authentication Type**, select **ECR**.
 
-12. If your OCI registry server is using a self-signed certificate or if the server certificate is not signed by a
-    trusted CA, check the **Insecure Skip TLS Verify** box to skip verifying the x509 certificate, and click **Upload
-    file** to upload the certificate.
+7. Toggle the **Synchronization** option to enable or disable synchronization for the registry. For more information,
+   refer to the [Helm Registry - Synchronization Behavior](../helm-charts.md#synchronization-behavior) section.
 
-13. Click **Confirm** to complete adding the registry.
+8. Provide the registry URL in the **Endpoint** field. Exclude the `https://` prefix.
 
-</TabItem>
+9. If **Synchronization** is enabled, in the **Base Content Path** field, enter the base path to the repository in the
+   registry where the Helm charts are stored. You can specify multiple base paths by pressing the **ENTER** key after
+   each path. Providing multiple base paths is useful when Helm charts are stored in different directories or projects.
 
-<TabItem value="aws" label="Amazon ECR">
+10. If you are using a private ECR, toggle the **Enable Authentication** option to expose the **AWS authentication
+    method** fields. Choose **Credentials** if you want to provide the static AWS credentials for an IAM user. Choose
+    **STS** if you want Palette to assume an IAM role that has access to the ECR through the Security Token Service
+    (STS). Refer to the table below to learn more about each credential type.
 
-1. Log in to the [Palette](https://console.spectrocloud.com) as a Tenant administrator.
+    | **Authentication Method** | **Field**             | **Description**                                                                                                                                                                                                            |
+    | ------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+    | **Credentials**           | **Access key**        | The access key ID of the IAM user.                                                                                                                                                                                         |
+    | **Credentials**           | **Secret access key** | The secret access key of the IAM user.                                                                                                                                                                                     |
+    | **STS**                   | **ARN**               | The Amazon Resource Name (ARN) of the IAM role to assume. Refer to the instructions exposed in the side-drawer to the right of the input field to review the IAM trust relationship changes you must add to your IAM role. |
 
-2. From the left **Main Menu** select **Tenant Settings**.
+    :::warning
 
-3. From the **Tenant Settings Menu**, Select **Registries**.
+    If you selected **STS** as the authentication method, you must add a trust relationship to the IAM role you are
+    using to access the ECR. Refer to the instructions exposed in the side-drawer to the right of the input field to
+    review the IAM trust relationship changes you must add to your IAM role. Failure to add the trust relationship will
+    result in an error when you attempt to validate the registry.
 
-4. Click on the **OCI Registries** tab.
+    :::
 
-5. Click **Add New OCI Registry**.
+11. Keep the default **TLS Configuration** settings.
 
-6. Fill out the **Name** field and select **Helm** as the provider type.
+12. Select **Confirm** to add the registry.
 
-7. Select the **OCI Authentication Type** as **ECR**.
+</TabItem>
 
-8. Provide the registry URL in the **Endpoint** field. Exclude the `https://` prefix.
+<TabItem value="GHCR" label="GHCR">
 
-9. If you are using a private ECR, toggle the **Enable Authentication** option to expose the authentication fields.
+1. Log in to [Palette](https://console.spectrocloud.com) as a Tenant administrator.
 
-10. Select the **AWS Authentication Method**. Choose **Credentials** if you want to provide the static AWS credentials
-    for an IAM user. Choose **STS** if you want Palette to assume an IAM role that has access to the ECR through the
-    Security Token Service (STS). Refer to the table below to learn more about each credential type.
+2. From the left main menu, select **Tenant Settings**.
 
-#### Credentials
+3. From the **Tenant Settings Menu**, select **Registries**.
 
-    | **Field** | **Description** |
-    | --- | --- |
-    | Access Key | The access key ID of the IAM user. |
-    | Secret access key | The secret access key of the IAM user. |
+4. On the **OCI Registries** tab, select **Add New OCI Registry**.
 
-#### STS
+5. Enter the **Name** of the registry. For the **Provider** type, select **Helm**.
 
-| **Field** | **Description**                                                                                                                                                                                                            |
-| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| ARN       | The Amazon Resource Name (ARN) of the IAM role to assume. Refer to the instructions exposed in the side-drawer to the right of the input field to review the IAM trust relationship changes you must add to your IAM role. |
+6. For **OCI Authentication Type**, select **Basic**.
 
-<br />
+7. Ensure **Synchronization** is disabled. For more information, refer to the
+   [Helm Registry - Synchronization Behavior](../helm-charts.md#synchronization-behavior) section.
 
-:::warning
+8. Enter the Helm chart endpoint, omitting the `oci://` scheme and ending with `/charts`. For example, for the endpoint
+   `oci://ghcr.io/controlplaneio-fluxcd/charts/flux-operator`, enter `ghcr.io/controlplaneio-fluxcd/charts`.
 
-If you selected **STS** as the authentication method, you must add a trust relationship to the IAM role you are using to
-access the ECR. Refer to the instructions exposed in the side-drawer to the right of the input field to review the IAM
-trust relationship changes you must add to your IAM role. Failure to add the trust relationship will result in an error
-when you attempt to validate the registry.
+9. Leave the **Username** and **Password** fields empty.
 
-:::
+10. Keep the default **TLS Configuration** settings.
 
-11. Click **Confirm** to complete adding the registry.
+11. Select **Confirm** to add the registry.
 
 </TabItem>
 
@@ -217,12 +211,21 @@ Use the following steps to validate that the OCI registry is added to Palette co
 
 1. Log in to the [Palette](https://console.spectrocloud.com).
 
-2. From the left **Main Menu**, click on **Profiles**.
+2. From the left main menu, select **Profiles**.
 
 3. Click **Add Cluster Profile**.
 
-4. Provide a name and select the type **Add-on**.
+4. Enter a unique **Name** for the cluster profile and choose the type **Add-on**. Select **Next**.
+
+5. On the **Profile Layers** screen, select **Add Helm Chart > Public Packs**. For GHCR, select **Private Packs**.
+
+6. Verify the Helm chart registry you added is displayed in the **Registry** drop-down menu.
 
-5. In the following screen, click **Add Helm Chart** and select **Public Packs**.
+## Next Steps
 
-6. Verify the Helm Chart registry you added is displayed in the **Registry drop-down Menu**.
+Once your registry is added, you can add Helm charts from these registries to
+[full](../../../profiles/cluster-profiles/create-cluster-profiles/create-full-profile.md) or
+[add-on cluster profiles](../../../profiles/cluster-profiles/create-cluster-profiles/create-addon-profile/create-addon-profile.md).
+Refer to our
+[Add a Helm Chart](../../../profiles/cluster-profiles/create-cluster-profiles/create-addon-profile/create-helm-addon.md)
+guide for more information.
diff --git a/docs/docs-content/registries-and-packs/registries/oci-registry/oci-registry.md b/docs/docs-content/registries-and-packs/registries/oci-registry/oci-registry.md
@@ -27,13 +27,13 @@ The following table describes the types of OCI registries that are supported.
 
 ## Limitations
 
-- Automatic synchronization is not supported for Zarf registries.
+- GitHub Container Registry (GHCR) is not officially supported at this time. To add a Helm chart from GHCR, you must
+  create a separate OCI Helm registry in Palette for each chart. Refer to [Add OCI Helm Registry](./add-oci-helm.md) for
+  more information.
 
 - OCI Helm registries created before Palette version 4.5.0 do not support automatic synchronization. To enable automatic
   synchronization, re-register the OCI Helm registry.
 
-<br />
-
 To add an OCI registry to Palette, refer to the respective guide for the OCI-type registry located in the
 [Resources](#resources) section.
 
@@ -53,4 +53,4 @@ system level scope, refer to the
 
 - [Add OCI Packs Registry](./add-oci-packs.md)
 
-- [Add OCI Zarf Registry](./oci-registry.md)
+- [Add OCI Zarf Registry](./add-oci-zarf.md)
