From 206d07a25ea65e416288c26f135e40d3b9ca8916 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 14 Aug 2025 00:46:42 +0000 Subject: [PATCH] Add comprehensive .github/copilot-instructions.md for coding agents Co-authored-by: yxxhero <11087727+yxxhero@users.noreply.github.com> --- .github/copilot-instructions.md | 231 ++++++++++++++++++++++++++++++++ 1 file changed, 231 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000..8ba024a7 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,231 @@ +# Copilot Instructions for Helmfile + +## Repository Overview + +Helmfile is a declarative spec for deploying Helm charts that manages Kubernetes deployments as code. It provides templating, environment management, and GitOps workflows for Helm chart deployments. + +**Key Details:** +- **Language:** Go 1.24.2+ +- **Type:** CLI tool / Kubernetes deployment management +- **Size:** Large codebase (~229MB binary, 200+ dependencies) +- **Runtime:** Requires Helm 3.x as external dependency +- **Target Platform:** Linux/macOS/Windows, Kubernetes clusters + +## Build and Validation Commands + +### Essential Setup +Helmfile requires Helm 3.x as a runtime dependency: +```bash +# Check for Helm dependency (REQUIRED) +helm version # Must show version 3.x + +# Initialize Helm plugins after helmfile installation +./helmfile init # Installs required helm-diff plugin + +# Alternative: Force install without prompts +./helmfile init --force +``` + +### Build Process +```bash +# Standard build (takes 2-3 minutes due to many dependencies) +make build + +# Alternative direct build +go build -o helmfile . + +# Build with test tools (required for integration tests, ~1 minute) +make build-test-tools # Creates diff-yamls and downloads dyff + +# Cross-platform builds +make cross +``` + +**Build Timing:** First build downloads 200+ Go packages and takes 2-3 minutes. Subsequent builds are faster due to module cache. Test tools build is faster (~1 minute). + +### Validation Pipeline +Run in this exact order to match CI requirements: + +```bash +# 1. Code formatting and linting +make check # Run go vet (required - always works) +# Note: make fmt requires gci tool (go install github.com/daixiang0/gci@latest) + +# 2. Unit tests (fast, ~30 seconds) +go test -v ./pkg/... -race -p=1 + +# 3. Integration tests (requires Kubernetes - see Environment Setup) +make integration # Takes 5-10 minutes, needs minikube/k8s cluster + +# 4. E2E tests (optional, needs expect package) +sudo apt-get install expect # On Ubuntu/Debian +bash test/e2e/helmfile-init/init_linux.sh +``` + +### Linting Configuration +Uses golangci-lint with configuration in `.golangci.yaml`. Install via: +```bash +# For local development +curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v2.1.6 +golangci-lint run +``` + +**Critical Lint Rules:** staticcheck, errcheck, revive, unused. Fix lint errors before committing. + +## Environment Setup Requirements + +### Dependencies for Development +```bash +# Required for building/testing +go version # Must be 1.24.2+ +helm version # Must be 3.x +kubectl version # For K8s integration + +# Required for integration tests +minikube start # Or other K8s cluster +kustomize version # v5.2.1+ for some tests +``` + +### Integration Test Environment +Integration tests require a running Kubernetes cluster: + +```bash +# Using minikube (recommended for CI) +minikube start +export KUBECONFIG=$(minikube kubeconfig-path) + +# Using kind (alternative) +kind create cluster --name helmfile-test + +# Verify cluster access +kubectl cluster-info +``` + +**Timing:** Integration tests take 5-10 minutes and may fail due to timing issues in resource-constrained environments. + +## Project Architecture and Layout + +### Core Directory Structure +``` +/ +├── main.go # Entry point - CLI initialization and signal handling +├── cmd/ # CLI commands (apply, diff, sync, template, etc.) +│ ├── root.go # Main cobra command setup and global flags +│ ├── apply.go # helmfile apply command +│ ├── diff.go # helmfile diff command +│ └── ... # Other subcommands +├── pkg/ # Core library packages +│ ├── app/ # Main application logic and execution +│ ├── state/ # Helmfile state management and chart dependencies +│ ├── helmexec/ # Helm execution and command wrapper +│ ├── tmpl/ # Go template processing and functions +│ ├── environment/ # Environment and values management +│ └── ... # Other core packages +├── test/ # Test suites +│ ├── integration/ # Integration tests with real K8s clusters +│ ├── e2e/ # End-to-end user workflow tests +│ └── advanced/ # Advanced feature tests +├── docs/ # Documentation (mkdocs format) +├── examples/ # Example helmfile configurations +└── .github/workflows/ # CI/CD pipeline definitions +``` + +### Key Source Files +- **main.go:** Signal handling, CLI execution entry point +- **cmd/root.go:** Global CLI configuration, error handling, logging setup +- **pkg/app/app.go:** Main application orchestration, state management +- **pkg/state/state.go:** Helmfile state parsing, release management +- **pkg/helmexec/exec.go:** Helm command execution, version detection + +### Configuration Files +- **go.mod/go.sum:** Go dependencies (many cloud providers, k8s libraries) +- **.golangci.yaml:** Linting rules and settings +- **Makefile:** Build targets and development workflows +- **mkdocs.yml:** Documentation generation configuration +- **.github/workflows/ci.yaml:** Complete CI pipeline definition + +## Continuous Integration Pipeline + +### GitHub Actions Workflow (`.github/workflows/ci.yaml`) +1. **Lint Job:** golangci-lint with custom configuration (~5 minutes) +2. **Test Job:** Unit tests + binary build (~10 minutes) +3. **Integration Job:** Tests with multiple Helm/Kustomize versions (~15-20 minutes each) +4. **E2E Job:** User workflow validation (~5 minutes) + +**Matrix Testing:** CI tests against multiple Helm versions (3.17.x, 3.18.x) and Kustomize versions (5.2.x, 5.4.x). + +### Pre-commit Validation Steps +Always run these locally before pushing: +```bash +make check # Format and vet (required) +go test ./pkg/... # Unit tests +make build # Verify build works +# Note: make fmt requires gci tool: go install github.com/daixiang0/gci@latest +``` + +### Common CI Failure Causes +- **Linting errors:** Run `golangci-lint run` locally first +- **Integration test timeouts:** K8s cluster setup timing issues +- **Version compatibility:** Ensure Go 1.24.2+ and Helm 3.x +- **Race conditions:** Some tests are sensitive to parallel execution + +## Development Gotchas and Known Issues + +### Build Issues +- **Long initial build time:** First `make build` downloads 200+ packages (~2-3 minutes) +- **Memory usage:** Large binary size due to embedded dependencies +- **Git tags:** Build may show version warnings if not on tagged commit +- **Tool dependencies:** `make fmt` requires `gci` tool installation + +### Testing Issues +- **Integration tests require K8s:** Will fail without cluster access +- **Test isolation:** Use `-p=1` flag to avoid race conditions +- **Minikube timing:** May need to wait for cluster ready state +- **Plugin dependencies:** Tests need helm-diff and helm-secrets plugins + +### Runtime Requirements +- **Helm dependency:** Always required at runtime, not just build time (available in CI) +- **kubectl access:** Most operations need valid kubeconfig +- **Plugin management:** `helmfile init` must be run after installation + +### Common Error Patterns +```bash +# Missing Helm +"helm: command not found" → Install Helm first + +# Plugin missing +"Error: plugin 'diff' not found" → Run helmfile init + +# K8s access +"connection refused" → Check kubectl cluster-info + +# Permission errors +"permission denied" → Check kubeconfig and cluster access + +# Missing tools +"gci: No such file or directory" → go install github.com/daixiang0/gci@latest +``` + +## Working with the Codebase + +### Making Changes +- **Small, focused changes:** Each PR should address single concern +- **Test coverage:** Add unit tests for new pkg/ functionality +- **Integration tests:** Update test-cases/ for new CLI features +- **Documentation:** Update docs/ for user-facing changes + +### Key Packages to Understand +- **pkg/app:** Main business logic, start here for feature changes +- **pkg/state:** Helmfile parsing and release orchestration +- **cmd/:** CLI interface changes and new subcommands +- **pkg/helmexec:** Helm integration and command execution + +### Architecture Patterns +- **Dependency injection:** App uses interfaces for testability +- **State management:** Immutable state objects, functional transforms +- **Error handling:** Custom error types with exit codes +- **Plugin system:** Extensible via Helm plugins and Go templates + +--- + +**Trust these instructions:** This information is validated against the current codebase. Only search for additional details if these instructions are incomplete or found to be incorrect for your specific task. \ No newline at end of file