feat: consolidate Helm chart distribution to OCI-only and drop GitHub Pages

[udsmicrosoft]

Closes #326.

Summary

Removes the GitHub Pages-based Helm repository (https://documentdb.github.io/documentdb-kubernetes-operator) and consolidates Helm chart distribution to the OCI registry already published to GHCR (oci://ghcr.io/documentdb/documentdb-operator). Updates workflows, actions, scripts, and docs that still consumed the chart from GH Pages.

Changes

Release pipeline (no more GH Pages publish)

• Deleted .github/workflows/repair_helm_pages_release.yml (the 300+ line reusable workflow that rebuilt index.yaml and committed it to the gh-pages branch).
• Removed the publish-helm-pages job from release_operator.yml and from the deprecated release_images.yml. OCI publication via helm push is unchanged.

CI consumers migrated to OCI

• .github/actions/setup-test-environment/action.yml: the released-chart-version install path now runs helm install … oci://ghcr.io/documentdb/documentdb-operator --version <X>.
• .github/workflows/test-upgrade-and-rollback.yml: dropped helm repo add documentdb / helm repo update.
• "latest" version resolution: OCI registries don't support helm search repo, so both call sites now resolve latest by listing GHCR tags directly (/v2/.../tags/list) and picking the highest stable SemVer. This better matches the prior helm search repo … | .[0].version semantics than gh api releases/latest would.
• GHCR Helm registry login is best-effort for public chart installs, and GHCR tag-list requests only send an Authorization header when a token was resolved.

Playground scripts

• documentdb-playground/aws-setup/scripts/create-cluster.sh: collapsed the "try GH Pages → fall back to OCI" structure into a single OCI install. GITHUB_USERNAME/GITHUB_TOKEN are optional for authenticated GHCR pulls.
• documentdb-playground/aks-fleet-deployment/install-documentdb-operator.sh: replaced GH Pages install with OCI; requires explicit CHART_VERSION env var when not building a local chart.

Docs

• Quickstart-style install snippets now use the OCI chart without hardcoding DOCUMENTDB_VERSION=0.2.0:

  helm install documentdb-operator oci://ghcr.io/documentdb/documentdb-operator \
    --namespace documentdb-operator --create-namespace --wait

• Production/repeatable-install guidance tells users to add --version <release-version> from GitHub Releases.
• Upgrade and production-oriented docs use <release-version> placeholders instead of literal release numbers.
• .github/workflows/deploy_docs.yml stamps <release-version> with the GitHub release tag before mike deploy, so versioned docs snapshots do not require per-release manual doc bumps.
• Files updated: README.md, index.md, getting-started/quickstart-kind.md, getting-started/quickstart-k3s.md, getting-started/deploy-on-eks.md, multi-region-deployment/setup.md, operations/upgrades.md, faq.md, documentdb-playground/aws-setup/README.md.
• Stale documentdb.github.io/... link in aws-setup/README.md repointed to documentdb.io/....

Root README

• New �� Install section between 📚 Documentation and 🚀 Quick Start, with a copy-paste OCI install snippet, version-pinning guidance, link to GitHub Releases for version discovery, and the Helm 3.8+ requirement.

Tradeoffs (per the issue)

• Users lose helm repo add + helm search repo discoverability — must consult GitHub Releases for available versions.
• Requires Helm 3.8+ (March 2022) for OCI support — already widely adopted.
• Significantly simpler release pipeline; no more gh-pages Helm-repo branch maintenance or index.yaml repair workflow.

Validation

• yaml.safe_load parses all modified workflows / composite action.
• bash -n parses both modified shell scripts.
• Final grep sweep for helm repo add documentdb, documentdb.github.io/documentdb-kubernetes-operator, helm search repo documentdb, helm repo update documentdb, repair_helm_pages, publish-helm-pages returns zero hits across the repo.
• Grep sweep for hardcoded DOCUMENTDB_VERSION=0.2.0 / TARGET_VERSION=0.2.0 returns zero hits in the public docs and README.
• Smoke-tested the GHCR tag-list resolver locally — returns 0.2.0.
• Confirmed oci://ghcr.io/documentdb/documentdb-operator is anonymously pullable with an isolated Helm registry config, so the quickstart snippets work without helm registry login.
• Smoke-tested the docs release-stamping command against a temporary copy of docs/operator-public-documentation.

Out of scope (intentionally untouched)

• The gh-pages branch used by deploy_docs.yml for mike-based docs hosting is left alone — it serves a different purpose than the deprecated Helm repository and is not what issue Consider consolidating Helm chart distribution to OCI-only (drop GitHub Pages) #326 targets.

[documentdb-triage-tool]

🤖 Auto-triaged by documentdb-triage-tool.

Applied: documentation, CI/CD, ecosystem, enhancement
Project fields suggested: Component docs · Priority P2 · Effort L · Status In Progress
Confidence: 0.82 (mixed)

Reasoning

component from path globs (docs, ci, playground); effort from diff stats (147+516 LOC, 16 files); LLM: Cross-cutting consolidation of Helm chart distribution from GitHub Pages to OCI-only, touching release pipelines, CI workflows, playground scripts, and docs across multiple files and components.

If a label is wrong, remove it manually and ping @patty-chow so the rules can be tuned. The bot will not re-label items that already have component labels.

[Copilot]

Pull request overview

This PR removes the GitHub Pages–hosted Helm repository and standardizes Helm chart consumption and publication on the GHCR OCI registry (oci://ghcr.io/documentdb/documentdb-operator) across CI, docs, and playground scripts.

Changes:

• Removed the GitHub Pages Helm repo publishing workflow and its usage from release workflows.
• Migrated CI and scripts from helm repo add/search flows to OCI installs, including “latest” resolution via GHCR tag listing.
• Updated documentation and READMEs to use OCI-based install/upgrade commands and updated links.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
documentdb-playground/aws-setup/scripts/create-cluster.sh	Simplifies operator install to OCI-only with optional GHCR auth.
documentdb-playground/aws-setup/README.md	Updates documentation link from GitHub Pages to documentdb.io.
documentdb-playground/aks-fleet-deployment/install-documentdb-operator.sh	Switches install flow from Helm repo to OCI and requires explicit version pinning.
docs/operator-public-documentation/preview/operations/upgrades.md	Reworks upgrade steps to remove Helm repo semantics and use OCI + version pinning.
docs/operator-public-documentation/preview/multi-region-deployment/setup.md	Updates multi-cluster install snippet to OCI-based Helm install.
docs/operator-public-documentation/preview/index.md	Updates primary install snippet to OCI-based Helm install with pinned version.
docs/operator-public-documentation/preview/getting-started/quickstart-kind.md	Updates quickstart install snippet to OCI.
docs/operator-public-documentation/preview/getting-started/quickstart-k3s.md	Updates quickstart install snippet to OCI.
docs/operator-public-documentation/preview/getting-started/deploy-on-eks.md	Replaces Helm repo setup docs/snippets with OCI distribution guidance.
docs/operator-public-documentation/preview/faq.md	Updates operator upgrade snippet to OCI + version pinning.
README.md	Adds an “Install” section documenting OCI installs and Helm version requirement.
.github/workflows/test-upgrade-and-rollback.yml	Removes Helm repo usage and resolves “latest” via GHCR tags.
.github/workflows/repair_helm_pages_release.yml	Deleted: removes GH Pages Helm repo repair/republish workflow.
.github/workflows/release_operator.yml	Removes GH Pages Helm publish job from operator release flow.
.github/workflows/release_images.yml	Removes GH Pages Helm publish job from deprecated images release flow.
.github/actions/setup-test-environment/action.yml	Updates released-chart install path to OCI and adds GHCR tag-based “latest” resolver.

[WentingWu666666]

Question on docs versioning + chart pin: avoid per-release manual bumps?

The PR pins DOCUMENTDB_VERSION=0.2.0 literally in several quickstart/operations pages. That works today, but combined with mike (which snapshots docs/ into /{release}/ on every release) it means every release needs a docs PR to bump the literal -- otherwise the /0.3.0/ snapshot will still tell users to install 0.2.0, and /latest/ (which aliases the new release) will be wrong.

Three patterns that get the same "docs match deployed chart" property without the per-release toil:

1. Placeholder + release-time substitution (lowest churn). Use a sentinel in markdown:

DOCUMENTDB_VERSION=__DOCUMENTDB_VERSION__
helm install documentdb-operator oci://ghcr.io/documentdb/documentdb-operator \
  --version ${DOCUMENTDB_VERSION} ...

And in deploy_docs.yml before mike deploy ${VERSION}:

- name: Stamp release version into docs
  if: github.event_name == 'release'
  run: |
    VERSION=${{ github.event.release.tag_name }}
    find docs -name '*.md' -exec sed -i "s/__DOCUMENTDB_VERSION__/${VERSION}/g" {} +

Main branch source stays evergreen, every release snapshot is correct, zero release-time work.

2. Drop the pin from quickstarts entirely. OCI charts support helm install ... oci://... without --version; Helm picks the highest non-prerelease SemVer tag. Argo CD and cert-manager both use this pattern in their getting-started pages, with a callout box for production:

Production: pin --version to a specific release for upgrade safety. See the release notes for available versions.

The version-snapshot problem then disappears -- /0.3.0/'s quickstart says "install latest," which is 0.3.0 at the time of that snapshot. Self-consistent. The CRD-coupling concern that motivates pinning is really an upgrade concern, not a fresh install concern, so quickstarts can lean toward "just give me the latest."

3. Hybrid (probably the right answer here).

• Quickstart pages -- drop the pin (pattern 2). Add a note pointing to the upgrade/operations page for production.
• Operations / upgrade pages -- keep an explicit --version example, using the placeholder pattern (pattern 1) so each snapshot stamps itself.
• documentdb-playground/*.sh -- keep these pinned to a literal version. They're branch-versioned by git, not mike-versioned, and reproducibility of example scripts matters more than freshness.

This way: zero per-release docs bumps, each snapshot is internally consistent, new users get the lowest-friction install, and production users get the explicit pinning guidance where it actually matters.

Verified locally that helm install ... oci://ghcr.io/documentdb/documentdb-operator with no --version resolves to 0.2.0 (highest non-prerelease tag; correctly skipped 0.1.2-test and 0.1.3-test).

Happy to send a follow-up PR with the placeholder + sed change if there's interest in pattern 1 or 3.

[udsmicrosoft]

Addressed in 54394ec using the hybrid approach you suggested:

• Quickstart-style install snippets no longer hardcode DOCUMENTDB_VERSION=0.2.0; they install the latest stable OCI chart and include a tip to add --version <release-version> for production/repeatable installs.
• Upgrade / production-oriented examples now use <release-version> instead of a literal version.
• deploy_docs.yml stamps <release-version> with the GitHub release tag before mike deploy, so release snapshots do not require a manual docs bump for the chart version.
• Kept the playground scripts pinned/explicit as branch-versioned examples.

I also updated the PR description to reflect this so it no longer says every snippet is pinned to a literal version.