Development Guide¶

Repository layout¶

cmd/              # Manager entry point (main.go)
api/v1alpha1/     # CRD type definitions (Go structs + kubebuilder markers)
internal/
  controller/     # One reconciler per CRD + helpers
  concourse/      # HTTP client construction and cache
config/
  crd/            # Generated CRD YAML manifests
  rbac/           # Generated RBAC resources
  samples/        # Example CRs for all 7 resource types
  default/        # Default kustomization (metrics, cert patches)
test/
  e2e/            # End-to-end tests
  integration/    # Integration tests (require live Concourse)
docs/             # This documentation site

Setting up the development environment¶

git clone https://github.com/jakobmoellerdev/concourse-operator
cd concourse-operator
go mod download

Optionally use the provided dev container:

# VSCode: "Reopen in Container"
# Or manually:
docker build -f .devcontainer/Dockerfile -t concourse-operator-dev .

Running locally¶

# Install CRDs into your current cluster context
make install

# Run the operator process locally (hot-reloads on ^C + re-run)
make run

Code generation¶

After modifying type definitions in api/v1alpha1/:

# Regenerate DeepCopy methods (zz_generated.deepcopy.go)
make generate

# Regenerate CRD YAML, RBAC from kubebuilder markers
make manifests

Always run both after changing types.

Linting¶

make lint       # run golangci-lint
make lint-fix   # auto-fix where possible

The linter configuration lives in .golangci.yml.

Building the container image¶

make docker-build IMG=<registry>/concourse-operator:dev
make docker-push  IMG=<registry>/concourse-operator:dev

Commit conventions¶

This project uses Conventional Commits:

feat: add Resource pinnedVersion support
fix: evict cache entry on instance finalizer
docs: add authentication guide
test: add integration test for team deletion
chore: bump go-concourse to v4.2.2

Contributing¶

Fork the repository
Create a feature branch: git checkout -b feat/my-feature
Write tests first (see Testing)
Implement the change
Run make lint test — both must pass
Submit a pull request against main