Improve installation quickstart

[gjkim42]

What type of PR is this?

/kind docs

What this PR does / why we need it:

Reworks the README installation guide into an end-to-end quickstart. It separates CLI and control-plane installation, documents prerequisites and readiness checks, adds webhook validation, provides copy-pasteable GitHub App and runner provisioning, keeps namespaces consistent, and preserves a version-pinned Helm path for production and GitOps installs.

Which issue(s) this PR is related to:

N/A

Special notes for your reviewer:

make verify passes. README console blocks also pass shell syntax, local-link, and whitespace checks.

Does this PR introduce a user-facing change?

Improve the README installation quickstart with complete GitHub App, Project, and runner setup instructions.

[gjkim42]

/kelos claude-review

[kelos-bot]

🤖 Kelos Task Status

Task open-actions-claude-reviewer-issue-comment-f9f911bd7863 has succeeded. ✅

[kelos-bot]

🤖 Open Actions Claude Reviewer Agent @gjkim42

Review Summary

Verdict: APPROVE
Overall correctness: patch is correct
Scope: README-only rewrite of the installation guide into an end-to-end quickstart (CLI + control plane install, webhook validation, GitHub App setup, Project/RunnerSet provisioning, version-pinned Helm path).

Findings Overview

Priority	Count	File:Line	Summary
P0	0	—	none
P1	0	—	none
P2	0	—	none
P3	0	—	none

Findings

None. Every operational claim in the new quickstart was verified against the implementation:

• Installer (hack/install.sh): defaults to ~/.local/bin, verifies the SHA-256 checksum, and supports exactly Linux/macOS on AMD64/ARM64, as documented.
• open-actions install (cmd/open-actions/main.go:53, internal/installer/installer.go:69-72): exists, shells out to Helm with release name open-actions and namespace open-actions-system, and the embedded chart includes the CRDs under templates/crds/.
• Workload names: deployment/open-actions-controller, statefulset/open-actions-artifacts, and deployment/open-actions-console all match the chart templates, and artifacts.enabled/console.enabled default to true, so the three rollout-status commands are valid on a default install.
• Webhook check: the GitHub handler is the controller webhook server's top-level handler, and internal/webhook/github.go:184-188 returns 405 Method Not Allowed (with Allow: POST) for any non-POST request on any path, so the documented curl GET validation is accurate. Signatures are verified before any resource is created. The chart contains no Ingress or certificate resources, matching the TLS-termination note.
• Storage prerequisite: artifacts.persistence.size defaults to 20Gi with storageClass: null (cluster default), matching the default-StorageClass prerequisite.
• Project/RunnerSet YAML: field names and shapes match api/v1alpha1 and the in-repo samples. workflowDirectory defaults to .open-actions/workflows, and omitting forkPullRequests yields the safe default (approval required, read-only tokens, secrets withheld), so "keep the default fork policy" is consistent with the code.
• Readiness waits: the Project controller sets a Configured condition after locally validating both secret refs in the Project's namespace (internal/controller/project_controller.go:51-57), and the RunnerSet controller sets Ready=True when all desired Runners are ready (internal/controller/runnerset_controller.go:220-243). Runner readiness does not require pulling the job image, so the 2-minute timeouts are realistic.
• Version-pinned path: make release-chart rewrites tag: latest to the release tag and strips the v prefix from the chart version, and the release workflow publishes open-actions-runner under the same version tag, so both the pinned-chart claim and the "use that same release tag for the runner image" guidance are accurate.
• Links/anchors: docs/reference.md#workflow-api, docs/reference.md#external-actions, examples/runner/Dockerfile, config/samples/actions_v1alpha1_docker_runner.yaml, and internal/manifests/charts/open-actions/README.md#values all resolve, and the values README covers the storage/resources/pull-policy/Console topics cited.
• The "private actions" wording in step 3 matches the External actions reference ("the App must be installed on each private action repository used by a workflow").

Suggestions (optional)

• [P3] README.md:185-188 — When either kubectl wait times out, the failure reason is only visible in the resource's condition message (for example CredentialsUnavailable or RunnersNotReady). A one-line pointer such as "if a wait times out, check kubectl describe project default / kubectl describe runnerset linux" would keep first-time users unblocked without lengthening the happy path.

Key takeaways

• Docs-only change; no code, API, or generated files are touched, so no make update artifacts are expected.
• All resource names, ports, CRD fields, condition types, defaults, and release-tagging claims in the new quickstart were verified against the chart, CLI, and controllers — the README documents implemented behavior only.
• PR hygiene is in order: /kind docs, a release-note block, a clean commit message, and no whitespace issues in the diff.