Add comprehensive .github/copilot-instructions.md for coding agents
Co-authored-by: yxxhero <11087727+yxxhero@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
parent
481d8ed433
commit
206d07a25e
|
|
@ -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.
|
||||||
Loading…
Reference in New Issue