Development and contribution

Repository map

Path	Contents
cmd/gbb, cmd/gbb-server, cmd/gbb-gateway	Executables
internal/	Backend packages and adjacent Go tests
internal/store/migrations/	Embedded PostgreSQL migrations
web/src/	Svelte routes, shared TypeScript, frontend tests
internal/httpapi/dist/	Generated frontend embed assets
build/docker/	Application/toolchain images and entrypoint
deploy/k8s/, deploy/local/	Kubernetes base and local overlay
scripts/	Build, development, test, release helpers
docs/, docs/wiki/	Detailed design references and this wiki

Build and checks

make build
make check
npm --prefix web run check
npm --prefix web test

make build builds frontend assets and all three executables. make cli, make server, and make gateway build individual executables. make web refreshes embedded frontend assets. make check runs formatting, vet, and Go tests; it can modify Go formatting. make test-cover reports aggregate Go coverage, and make help lists targets.

External-service tests are opt-in. A skipped integration test does not establish correctness against that service.

Gate	Coverage area
GBB_TEST_DSN	Real PostgreSQL persistence and transaction behavior
GBB_TEST_REDIS_URL	Real shared verification/enforcement state
GBB_TEST_DOCKER	Container lifecycle, execution, cancellation
GBB_TEST_S3_ENDPOINT	Object-store integration; use the package's companion credential settings
GBB_TEST_KUBECONFIG, GBB_TEST_KUBE_NAMESPACE	Kubernetes adapter server-side dry-run gate

GBB_TEST_DSN='postgres://gbb:gbb@localhost:5432/gbb?sslmode=disable' \
  go test ./internal/store/...
GBB_TEST_DOCKER=1 go test ./internal/runner/... ./internal/job/...
GBB_TEST_REDIS_URL=redis://127.0.0.1:6379/0 \
  go test -race ./internal/human ./internal/enforcement ./internal/httpapi
make test-s3

Use isolated test services. The Docker tests can build fixture images and need registry access on a cold run. See Contributing and the relevant package tests for setup.

Code conventions

Follow .editorconfig, format Go with gofmt, and retain pure-Go dependencies. Put validation in internal/spec; toolchain-specific arguments belong in image entrypoints. Use Svelte 5 runes.

When backend contracts change, update the frontend types and applicable validation. Add regression coverage for changed authorization, concurrency, and recovery behavior. Keep tests beside the implementation as *_test.go or *.test.ts.

Never commit generated binaries, node_modules, real configuration, credentials, Apple SDKs, or generated embed output beyond tracked placeholders.

Pull requests and releases

Use Conventional Commits such as fix(runner): ... or docs(wiki): .... Submit through a pull request to protected main; keep the branch current and require green Go and Frontend checks. Explain behavior, validation, and limitations. Include screenshots for UI changes.

Forgejo Actions runs CI and release workflows. See CI/CD for triggers, merge-ref checks, and release actions. Documentation changes should keep this wiki's links and implementation status consistent with the code.