Add testing guidelines with fork repos

[hossain-rayhan]

No description provided.

[Copilot]

Pull request overview

Adds a new developer guide describing how to run end-to-end tests using container images built from a contributor’s fork (GHCR) and installing the local Helm chart to validate changes on a real Kubernetes cluster.

Changes:

• Introduces a step-by-step “fork images” workflow for building operator images and (intended) database images.
• Documents Helm install/upgrade commands and iterative update approaches.
• Adds an example DocumentDB manifest and cleanup steps.

[Copilot]

Step 1 instructs passing documentdb_extension_github_repo and documentdb_gateway_image_repo inputs to RELEASE - Build DocumentDB Candidate Images, but .github/workflows/build_documentdb_images.yml currently only defines a version input and hardcodes DOCUMENTDB_RELEASE_REPO / GATEWAY_SOURCE_IMAGE_REPO. Either update the workflow to accept these inputs or adjust the guide to match the actual workflow behavior.

Suggested change

	3. **In your operator fork**, run **Actions → `RELEASE - Build DocumentDB Candidate Images` → Run workflow**. Provide these inputs:
	- `version`: `0.110.0` (or whatever you released in step 2)
	- `documentdb_extension_github_repo`: `<your-gh-user>/documentdb`
	- `documentdb_gateway_image_repo`: `ghcr.io/<your-gh-user>/documentdb/documentdb-local`
	3. **In your operator fork**, run **Actions → `RELEASE - Build DocumentDB Candidate Images` → Run workflow**. Provide this input:
	- `version`: `0.110.0` (or whatever you released in step 2)
	The workflow currently only exposes `version` as a manual input. The DocumentDB release repository and gateway source image repository are set inside the workflow, so you do **not** need to provide `documentdb_extension_github_repo` or `documentdb_gateway_image_repo` when starting the run.

[Copilot]

The example DocumentDB manifest uses namespace: documentdb-test and references a credentials Secret, but the guide doesn’t include creating the namespace and documentdb-credentials Secret first. Add a short “create namespace + Secret” step (similar to docs/operator-public-documentation/preview/getting-started/quickstart-kind.md) to make the end-to-end flow runnable.

[Copilot]

The example output tags in Step 1 (e.g. .../documentdb:0.110.0) and the note about the workflow retagging to the bare <version> don’t match the current build_documentdb_images.yml behavior: it produces only the computed image_tag (<version>-build-...) and does not retag to <version> (retagging happens in release_documentdb_images.yml). Please update the example image references and wording accordingly.

Suggested change

	ghcr.io/<your-gh-user>/documentdb-kubernetes-operator/documentdb:0.110.0
	ghcr.io/<your-gh-user>/documentdb-kubernetes-operator/gateway:0.110.0
	```
	(The actual published tag is the `image_tag` output computed by the workflow — usually `<version>-build-<run_id>-<attempt>-<sha>`. The workflow also retags it with the bare `<version>` for convenience; check the run summary.)
	ghcr.io/<your-gh-user>/documentdb-kubernetes-operator/documentdb:0.110.0-build-<run_id>-<attempt>-<sha>
	ghcr.io/<your-gh-user>/documentdb-kubernetes-operator/gateway:0.110.0-build-<run_id>-<attempt>-<sha>
	```
	(The workflow publishes the computed `image_tag` output — usually `<version>-build-<run_id>-<attempt>-<sha>`. It does not retag these candidate images to the bare `<version>`; that happens later in [`release_documentdb_images.yml`](../../.github/workflows/release_documentdb_images.yml). Check the run summary for the exact tag.)

[Copilot]

Step 3 says the Helm chart lets you point “each image” at your fork via --set flags, but the chart values only allow overriding operator/sidecar (and documentDbVersion), not the documentdb/gateway repositories (those are fixed in code unless overridden per-CR via spec.documentDBImage / spec.gatewayImage). Also DB_TAG is defined but unused in the Helm command. Please clarify what is controlled by Helm vs the DocumentDB CR, and either use or remove DB_TAG.

Suggested change

	The Helm chart in this repo (`operator/documentdb-helm-chart/`) lets you point each image at your fork via `--set` flags.
	```bash
	GH_USER=<your-gh-user>
	OP_TAG=0.2.0-tls-test-1-test # from Step 2
	DB_TAG=0.110.0 # from Step 1, or upstream e.g. 0.110.0
	The Helm chart in this repo (`operator/documentdb-helm-chart/`) lets you point the **operator** and **sidecar** images at your fork via `--set` flags. The `documentdb` and `gateway` container images are not redirected by this Helm command; if you need to test forked database images, set them on the `DocumentDB` custom resource with `spec.documentDBImage` and `spec.gatewayImage`.
	```bash
	GH_USER=<your-gh-user>
	OP_TAG=0.2.0-tls-test-1-test # from Step 2

[Copilot]

In Step 3 you cd operator/documentdb-helm-chart, but the CRD reapply command uses operator/documentdb-helm-chart/crds/ (which will be a wrong path from inside that directory). Use ./crds/ (or explicitly state the command should be run from the repo root).

Suggested change

	> kubectl apply -f operator/documentdb-helm-chart/crds/
	> kubectl apply -f ./crds/

[Copilot]

The iteration section repeats kubectl apply -f operator/documentdb-helm-chart/crds/. Depending on the reader’s current working directory (Step 3 cds into the chart), this path may be wrong. Consider using a consistent relative path (./crds/) or stating “from repo root”.

Suggested change

	If the CRD changed between iterations, reapply: `kubectl apply -f operator/documentdb-helm-chart/crds/`.
	If the CRD changed between iterations, reapply: `kubectl apply -f ./crds/`.

[Copilot]

This guide hardcodes 0.110.0 in multiple places, but the repo defaults/workflow examples currently use 0.109.0 (e.g., operator/documentdb-helm-chart/values.yaml and build_documentdb_images.yml). Consider using placeholders (<version>) or referencing the current default to avoid the doc going stale.

[Copilot]

The prerequisites list cert-manager as v1.13.2+, but the rest of the repo docs/version matrix call out cert-manager 1.19+ (e.g. docs/operator-public-documentation/preview/getting-started/before-you-start.md, AGENTS.md). Please align this guide’s minimum cert-manager version (and consider noting the container runtime requirement for ImageVolume: containerd/CRI-O; Docker runtime won’t work).

Suggested change

	- A Kubernetes cluster with cert-manager installed (`v1.13.2+`) and Kubernetes `1.35+`
	- `kubectl`, `helm 3.x`, `git`
	- A Kubernetes cluster with cert-manager installed (`v1.19+`) and Kubernetes `1.35+`
	- `kubectl`, `helm 3.x`, `git`
	- If your test path uses `ImageVolume`, use a cluster runtime backed by `containerd` or `CRI-O`; Docker runtime will not work.

[Copilot]

This GHCR tag verification snippet uses curl and jq, but those tools aren’t listed in the prerequisites. Add them (or adjust the snippet) so readers don’t hit missing-command errors.

[documentdb-triage-tool]

🤖 Auto-triaged by documentdb-triage-tool.

Applied: documentation, enhancement
Project fields suggested: Component docs · Priority P3 · Effort M · Status Needs Review
Confidence: 0.60 (mixed)

Reasoning

component from path globs (docs); effort from diff stats (181+0 LOC, 1 files); LLM: PR adds testing guidelines documentation with no body details, likely a small markdown addition covering fork repo workflows.

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.

[WentingWu666666]

Thanks for adding this guide -- the Helm install/CR sections are accurate and useful. Two blockers and a few small items below.

❌ 1. Step 1 inputs depend on PR #354 (currently unmerged)

The doc instructs users to set documentdb_extension_github_repo and documentdb_gateway_image_repo when dispatching build_documentdb_images.yml, but on main that workflow only declares one input (version). Those two inputs are added by #354 ("Build DocumentDB images from custom gitHub sources"), which is still open.

As written, anyone following this doc today will get a workflow-dispatch error. Please either:

• Land #354 first and rebase this PR on top, or
• Merge them together,

so the doc is correct the moment it ships. A "requires #354" note in the doc itself ages badly.

❌ 2. The bare :<version> tag is not produced by build_documentdb_images.yml

Step 1.4 says:

"The workflow also retags it with the bare <version> for convenience; check the run summary."

That is not what the workflow does. build_documentdb_images.yml only publishes the candidate tag <version>-build-<run_id>-<attempt>-<sha> (and per-arch -amd64 / -arm64 variants). Its own summary explicitly directs the user to run release_documentdb_images.yml next:

- candidate_version: 0.110.0-build-12345-1-abc1234

The bare-version retag actually happens in release_documentdb_images.yml:

- name: Retag existing manifest
  env:
    SOURCE_TAG: ${{ inputs.candidate_version }}
    TARGET_TAG: ${{ inputs.version }}

So after only running the build workflow, ghcr.io/<fork>/documentdb-kubernetes-operator/documentdb:0.110.0 does not exist on the user's fork -- and the example in Step 3 will fail to pull.

Please pick one fix:

• (A) Use the long candidate tag in the example. Replace the :0.110.0 references in Step 3's CR snippet with the long candidate tag the build workflow actually produces, and explain how to read it from the run summary.
• (B) Add a "Step 1.5: Promote candidate to release tag" that runs release_documentdb_images.yml with candidate_version=<long tag> and version=0.110.0, then keep the :0.110.0 examples.

(B) is closer to how the operator track works and matches what the build workflow's summary tells users to do.

⚠️ Minor

• Private GHCR + imagePullSecrets: the doc explains how to make the fork's packages public, but if a reviewer skips that step, the install will silently fail at pod startup. Either add an imagePullSecrets example for the documentdb-operator-system namespace, or call out that the packages must be public for the helm install to succeed.
• cert-manager v1.13.2+: AGENTS.md's version compatibility matrix lists cert-manager 1.19.2 as the version the project tests against. Worth aligning so users don't pick an older version we don't validate.

Happy to re-review once #354 is in and the bare-tag step is reconciled.