Development Workflow

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• CLAUDE.md
• pyproject.toml
• specs/003-collect-tool/tasks.md
• specs/004-backup-retention-policy/tasks.md
• specs/001-k8s-helm-backup/plan.md
• specs/005-restore-latest-backup/opsmill-implement-report.md

The development workflow for the Infrahub toolset provides a structured environment for building, testing, and maintaining three specialized Go binaries: infrahub-backup, infrahub-taskmanager, and infrahub-collect. Developers use a combination of make commands for local builds, uv for Python-based tooling, and structured change management via towncrier news fragments.

Sources: AGENTS.md:6-14, CLAUDE.md:6-12

Local Development Lifecycle

Developers manage the codebase using a Makefile that handles building, testing, and formatting. The project requires Go 1.25.0 and utilizes golangci-lint for code quality checks.

Build and Install Commands

The project uses make to manage the compilation of its three specialized binaries.

Command	Action
make build	Builds all three binaries to the bin/ directory
make build-all	Cross-compiles for Linux, Darwin, and Windows (amd64/arm64)
make install	Installs all binaries to $GOPATH/bin
make dev-setup	Installs development dependencies like golangci-lint
make clean	Removes build artifacts

Sources: AGENTS.md:17-25, CLAUDE.md:16-20, specs/archive/003-collect-tool/tasks.md:27-31

Quality Control and Testing

Continuous validation occurs through table-driven unit tests in Go and end-to-end (E2E) tests using pytest.

This diagram shows the sequence of quality checks a developer performs before submitting a pull request.
Sources: AGENTS.md:27-35, CLAUDE.md:22-26, specs/004-backup-retention-policy/tasks.md:12-16

• make test: Runs all Go unit tests.
• make test-coverage: Generates a coverage.html report.
• make lint: Runs golangci-lint (with errcheck disabled).
• make fmt: Standardizes code formatting.

Sources: AGENTS.md:27-35, CLAUDE.md:22-26

Change Management and Versioning

The project uses towncrier to manage the CHANGELOG.md file through individual news fragments. This prevents merge conflicts on the main changelog file during high-velocity development.

News Fragment Types

News fragments must be added to the changelog/ directory and named <issue>.<type>.md.

• added: For new features.
• changed: For changes in existing functionality.
• fixed: For bug fixes.
• deprecated / removed: For lifecycle changes.
• security: For security-related updates.
• housekeeping: For internal or tooling work.

Sources: AGENTS.md:41-48, pyproject.toml:73-108

Releasing

The project follows a specific release flow:

1. Create fragments using uv run towncrier create.
2. Preview changes with uv run towncrier build --draft --version X.Y.Z.
3. Assemble the final CHANGELOG.md at release time using the --version flag.
4. Binary versions are determined by git tags, not pyproject.toml.

Sources: AGENTS.md:46-52, pyproject.toml:68-72

Environment and Dependencies

Nix Integration

The project uses Nix flakes for environment reproducibility. Whenever Go modules change (modifying go.mod or go.sum), developers MUST run scripts/update-vendor-hash.sh to update the vendorHash in flake.nix.

Sources: AGENTS.md:54-57, specs/archive/003-collect-tool/tasks.md:30-32

Python E2E Test Suite

Python is used for end-to-end testing, managed via uv. The suite relies on several key libraries:

• pytest: Core testing framework.
• infrahub-testcontainers: Manages Infrahub instances in Docker during tests.
• kubernetes-asyncio / kr8s: Interfaces with Kubernetes clusters.

Sources: pyproject.toml:7-18

Binary Architecture and Command Pattern

The project follows a command-pattern architecture using Cobra. Logic is centralized in src/internal/app and shared across the binaries.

This diagram illustrates how multiple specialized binaries share a common internal application core.
Sources: AGENTS.md:59-99, specs/archive/003-collect-tool/plan.md:49-53

Containerization and CI/CD

Docker Multi-Arch Workflow

The project builds multi-arch Docker images (amd64 and arm64) to support both standard servers and ARM-based infrastructure.

1. Build Stage: Uses golang:1.25-alpine as a base.
2. Watchdog Integration: Includes a neo4j_watchdog tool for Neo4j Community Edition backups.
3. Runtime Stage: Uses alpine:3.19 with kubectl installed.

Sources: specs/001-k8s-helm-backup/plan.md:53-73

GitHub Actions Pipeline

The CI/CD pipeline triggers on releases and pull requests:

• Linting/Testing: Validates code quality on every PR.
• Docker Release: Builds and pushes images to Docker Hub using docker/build-push-action@v6 with support for linux/amd64 and linux/arm64.

Sources: specs/001-k8s-helm-backup/plan.md:90-112, specs/005-restore-latest-backup/opsmill-implement-report.md:5-10

The development workflow ensures that changes are validated through a multi-tier testing strategy and released consistently across multiple binary entry points and container architectures.

Summary: The workflow prioritizes binary consistency, automated change tracking, and robust cross-platform support. Developers rely on make for local cycles and structured news fragments for changelog integrity.