Skip to main content
This page describes the developer workflow for working in the Arcentra repository. All commands assume you are at the root of the arcentra checkout.

​
Toolchain

  • Go 1.25 or later (matches go.mod).
  • Buf — Protobuf and gRPC code generation. make buf-install installs it on demand.
  • Wire — compile-time dependency injection. make wire-install installs it on demand.
  • golangci-lint v2 — installed automatically into bin/ by make lint.
  • staticcheck (optional) — make staticcheck installs and runs it.
  • addlicense (optional) — make addlicense adds Apache 2.0 headers to Go files.
  • Docker (optional) — required for make docker-build and make docker-buildx.

​
Make targets

make help prints the full target list. The targets you reach for most often are:
TargetWhat it does
make depsgo mod tidy and go mod verify
make codegenRun all code generators (Buf + Wire for both binaries)
make bufGenerate gRPC/protobuf code
make wire TARGET=arcentraGenerate Wire bindings for the control plane
make wire TARGET=arcentra-agentGenerate Wire bindings for the agent
make build TARGET=<name>Build a binary; <name> matches a cmd/ subdirectory
make build-target TARGET=<name>Release build with -trimpath -s -w (CI/Docker)
make runRun the control plane locally
make lintInstall golangci-lint v2 and run linters
make fmt-checkVerify formatting (excludes generated files)
make testgo test -race -count=1 ./...
make staticcheckRun staticcheck across the module
make docker-buildBuild a Docker image with docker buildkit
make docker-buildxMulti-arch (linux/arm64,linux/amd64) build and push
make addlicenseAdd license headers to Go files
make versionPrint version, branch, commit, and build time
make version-tagCreate and annotate vX.Y.Z.W git tag
The repository carries two binaries by default: arcentra (control plane) and arcentra-agent. Any directory inside cmd/ can be built with make build TARGET=<dirname>.

​
Code generation

Two generators are wired into the build:
  • Buf generates Go message and gRPC service code under api/<service>/v1.
  • Wire generates dependency-injection wiring (wire_gen.go) under cmd/arcentra/ and cmd/arcentra-agent/.
Run make codegen after editing any .proto file or any wire.go file.

​
Testing

make test
This runs the full Go test suite with the race detector enabled. For a single package, run go test -race ./internal/path/... directly.

​
Configuration during development

The default configuration files under conf.d/ are tailored for local development:
  • conf.d/config.toml — control plane.
  • conf.d/agent.toml — agent.
  • conf.d/plugins.toml — plugins and builtins.
make run starts the control plane against these defaults; you can also run go run ./cmd/arcentra -conf <path> and go run ./cmd/arcentra-agent -conf <path> directly. See Configuration for a reference of every section.

​
Versioning and releases

Arcentra uses a four-part YY.Major.Minor.Patch version scheme:
  • YY — last two digits of the year (25 for 2025, 26 for 2026).
  • Major — incremented for architecture changes or breaking APIs.
  • Minor — incremented for new, backward-compatible features.
  • Patch — incremented for bug fixes and small adjustments.
Examples: 
25.0.0.0  -> initial release in 2025
25.0.0.1  -> bug fix
25.0.1.0  -> new feature (backward compatible)
25.1.0.0  -> major change
26.0.0.0  -> first release of 2026

​
Choosing the version at build time

The Makefile resolves the version in this order:
  1. The VERSION environment variable.
  2. A VERSION file at the repository root.
  3. An exact-match git tag (with the leading v stripped).
  4. Fallback to <current-2-digit-year>.0.0.0.
# explicit
VERSION=25.1.2.3 make build TARGET=arcentra

# via VERSION file
echo -n "25.1.2.3" > VERSION
make build TARGET=arcentra

​
Tagging a release

export VERSION=25.1.2.3
make version-tag
git push origin v$VERSION
Tags follow the vYY.Major.Minor.Patch convention.

​
Reading the version from Go

import "github.com/arcentrix/arcentra/pkg/version"

v := version.GetVersion()
fmt.Println(v.Version)

parsed, err := version.GetParsedVersion()
if err != nil {
    log.Fatal(err)
}
fmt.Printf("year=20%02d major=%d minor=%d patch=%d\n",
    parsed.Year, parsed.Major, parsed.Minor, parsed.Patch)

​
Contributing

Read CONTRIBUTING.md for the full process. In short:
  1. Fork and branch from main.
  2. Run make codegen, make lint, and make test locally before opening a PR.
  3. Add or update documentation in this site for any user-visible change.
  4. Reference the related issue and follow the project’s commit and PR conventions.
Security issues should be reported privately as described in SECURITY.md.
Last modified on April 26, 2026