IDE & Tooling Setup¶

As a library and framework, GTB requires specific tooling to ensure that generated code and mocks remain consistent.

Recommended IDE: VS Code or Cursor¶

We highly recommend using Cursor or VS Code with the following extensions:

Go: Rich language support (Google).
YAML: Support for manifest and config editing (Red Hat).
Markdown Lint: Ensures documentation consistency.

Internal AI Tools¶

For developers using AI-powered editors like Cursor or Claude Code, we maintain a central marketplace for specialized plugins and MCP servers.

APX SRE Marketplace: The official source for internal generative AI plugins and SRE-focused assistant tools.

Editor Settings¶

Add these to your settings.json to enable auto-formatting and linting on save. This is especially important for the generator templates.

{
  "go.formatTool": "goimports",
  "go.lintTool": "golangci-lint",
  "go.lintOnSave": "package",
  "editor.formatOnSave": true,
  "[go]": {
    "editor.codeActionsOnSave": {
      "source.organizeImports": "always"
    }
  }
}

Environment Variables & .env¶

For detailed information on configuring symbols, API keys, and local development overrides using .env files, see the Environment Variables & .env guide.

Local Build & Generation Tools¶

Task (Taskfile.dev)¶

We use task for build automation.

Recommended Installation (Binary):

# Install to ./bin
curl -sSfL https://taskfile.dev/install.sh | sh -s -- -d

Alternative (Homebrew):

brew install go-task/tap/go-task

Just (alternative)¶

For those who prefer just, we provide a justfile with functional parity for all core development tasks.

Installation:

# Recommended via curl (see https://just.systems/man/en/chapter_4.html)
curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to ~/bin

# Alternative via cargo
cargo install just

mockery¶

Since GTB is highly interface-driven, mockery is essential for regenerating test mocks.

Recommended Installation (go install):

go install github.com/vektra/mockery/[email protected]

Alternative (Binary): Download the pre-built binary for your platform from the GitHub Releases page.

Secondary (Homebrew):

brew install mockery

golangci-lint¶

Run the linter before every commit. The project enforces strict linting rules.

Recommended Installation (Binary):

# binary will be $(go env GOPATH)/bin/golangci-lint
curl -sSfL https://golangci-lint.run/install.sh | sh -s -- -b $(go env GOPATH)/bin v1.64.6

Secondary (Homebrew):

brew install golangci-lint

Documentation Tooling¶

MkDocs¶

We use MkDocs with the Material theme to generate our documentation.

Note

While mkdocs-material is our current default, it is now in maintenance mode. We recommend using Zensical, a more modern and fully compatible alternative from the same development team.

Recommended Installation (pipx):

# Modern alternative (recommended)
pipx install zensical

# Legacy Material theme
pipx install mkdocs-material

Previewing Locally:

# Using Zensical
zensical serve

# Or using MkDocs directly
mkdocs serve