Vetrix Docs

Contributing to Vetrix

Development setup

Prerequisites

  • Go 1.22+
  • PostgreSQL 15+
  • Node.js 20+ (for the UI)
  • Docker (optional, for integration tests)

Clone and build

git clone git@github.com:your-org/vetrix.git
cd vetrix
go build ./...

Database setup

createdb vetrix_dev
export DATABASE_URL="postgres://postgres@localhost/vetrix_dev?sslmode=disable"
export JWT_SECRET="$(openssl rand -base64 48)"
go run ./cmd/server

Running the server

go run ./cmd/server

The API is available at http://localhost:3000.

Running the UI (development)

cd web
npm install
npm run dev

The UI dev server runs on port 3001 and proxies API requests to localhost:3000.

Code conventions

Go

  • Run gofmt and golangci-lint before committing.
  • Error messages are lowercase and do not end with punctuation.
  • Use context.Context as the first argument for all functions that make I/O calls.
  • Avoid global state. Wire dependencies through struct fields.
  • Keep packages cohesive. internal/api handles HTTP concerns only; business logic lives in internal/<feature>/.

Package structure

cmd/
  server/           — main HTTP + SSH server entry point
  worker/           — standalone CI/CD runner entry point
internal/
  admin/            — admin settings, user management, health
  api/              — HTTP handlers and router
  auth/             — JWT issuance and middleware
  acl/              — permissions, PATs, SSH keys
  cicd/             — pipeline execution, runner protocol
  git/              — git repository operations
  mirror/           — pull/push mirror scheduler
  registry/         — container, npm, PyPI, Go, generic registries
  search/           — indexing and query engine
  scanning/         — SAST, secret scanning

Database

  • Migrations live in db/migrations/. Use sequential integer prefixes: 0001_init.up.sql, 0001_init.down.sql.
  • Never modify an existing migration. Add a new one.
  • Use pgx/v5 for all database access. No ORM.
  • Prefer RETURNING clauses over separate SELECT after INSERT/UPDATE.

Tests

  • Unit tests live alongside the code they test: foo.go → foo_test.go.
  • Integration tests that need a real database are in internal/<pkg>/integration_test.go and use the //go:build integration tag.
  • Run unit tests: go test ./...
  • Run integration tests: go test -tags integration ./... (requires TEST_DATABASE_URL)
  • See backend-pipeline.md for the backend CI testing runbook (the go-test / go-integration-test jobs, local TEST_DSN against mydev_postgres, and cookbooks for adding TEST_DSN-gated tests + structural projection guards).

Merge request guidelines

  1. One concern per MR. Separate refactoring from feature work.
  2. Reference the issue. Include Closes #123 in the MR description.
  3. Write tests. New behaviour must have unit tests. Bug fixes must have a regression test.
  4. Update docs. If you change API behaviour, update the relevant file in docs/.
  5. Keep commits clean. Squash or rebase if your branch has fixup commits before requesting review.
  6. CI must pass. PRs with failing CI are not reviewed.

Naming and terminology

A few project-wide naming rules. Apply them in any new copy you write and check existing copy when you touch it.

  • Vetrix's own merge / pull surface is "merge request" / "MR". The DB table is merge_requests, the type is MergeRequest, the API client is pullsApi (kept for back-compat with the /pulls/ route — see internal/api/pulls.go). User-facing copy uses "merge request"; wire-level identifiers like the pull_request webhook event are deliberately kept.
  • Vetrix's own CI / workflow surface is "Vetrix Workflows" (proper noun) when referring to the feature concept, or "pipeline" / "workflow" (lowercase) when referring to a single configured run. Do not call it "Actions" or "GitHub Actions" in product copy. "Actions" as a UI table-column header for row affordances (Cancel / Retry / Delete / etc.) is a different word with the same spelling — keep it.

Commit message format

<type>(<scope>): <short summary>

<optional body>

<optional footer: Closes #123>

Types: feat, fix, docs, refactor, test, chore.

Examples:

feat(cicd): add job timeout enforcement
fix(auth): reject expired JWTs with a 401 instead of 500
docs(registry): add PyPI install examples

Reporting issues

File bugs at /issues with:

  • Vetrix version (vetrix --version)
  • Steps to reproduce
  • Expected behaviour
  • Actual behaviour
  • Logs if applicable

Security vulnerabilities

Do not open a public issue for security vulnerabilities. Email the maintainers directly. See SECURITY.md for the disclosure policy.