Git Workflow And CI/CD Pipeline#

Lead Section#

The CipherSwarmAgent project implements a modern, automated development workflow designed for distributed hash-cracking operations in air-gapped laboratory environments. The workflow combines Git best practices with continuous integration and delivery (CI/CD) automation through GitHub Actions, supporting cross-platform builds across Ubuntu, macOS, and Windows.

The CI/CD infrastructure uses mise for development tool version management, pre-commit hooks for code quality enforcement, and a comprehensive task automation framework through Just. The system provides automated testing, linting, security scanning, and changelog generation while maintaining consistent development environments across local machines and CI runners.

The workflow emphasizes hermetic, reproducible builds suitable for secure deployment in non-Internet-connected environments, with Docker multi-stage builds that integrate hashcat capabilities for distributed password recovery operations.

Git Branching Model#

Branch Strategy#

CipherSwarmAgent uses a simplified trunk-based development model centered on the main branch:

main branch: The primary development branch. All features, fixes, and releases target main. All changes must go through pull requests—direct commits to main are not permitted.
Feature branches: Named feature/<short-description>, branched from main and merged back after review.
Hotfix branches: Named hotfix/<short-description>, used for urgent production fixes.

Pull Request Workflow#

Contributors fork the repository, create a feature or hotfix branch from main, and submit a pull request against main. Feature branches should be rebased onto main before merging to maintain a clean, linear commit history.

Example workflow:

git checkout -b feature/add-benchmark-caching
# ... development work ...
git rebase main
git push origin feature/add-benchmark-caching
# Submit pull request via GitHub

Commit Message Conventions#

All commit messages follow the Conventional Commits specification, enabling automated changelog generation and semantic versioning.

Commit Message Format#

Format: <type>(<scope>): <description>

Commit Types:

feat: New features
fix: Bug fixes
docs: Documentation changes
style: Code style changes (formatting, whitespace)
refactor: Code refactoring
perf: Performance improvements
test: Test additions or modifications
build: Build system changes
ci: CI/CD configuration changes
chore: Maintenance tasks

Examples:

feat(hashcat): add benchmark caching mechanism
fix(api): correct authentication token refresh logic
docs(readme): update installation instructions for air-gapped environments
ci(workflow): add cross-platform test matrix

Enforcement Mechanism#

Commit message format is enforced through pre-commit hooks and validated in CI pipelines. The project does not include a .gitlint file; instead, commit validation is handled by the pre-commit framework.

CI/CD Pipeline Architecture#

GitHub Actions Workflows#

The CipherSwarmAgent CI/CD system uses two primary GitHub Actions workflows:

1. Main CI Workflow (`go.yml`)#

The go.yml workflow implements the core CI pipeline with three parallel jobs:

Triggers:

Pushes to main branch
All pull requests

Jobs:

build - Cross-platform build and test
golangci - Code linting
- Ubuntu-only execution
- Uses golangci-lint-action (latest version)
coverage - Test coverage reporting

CI Pipeline Diagram:

All three jobs run in parallel with no dependencies, maximizing CI throughput.

2. Changelog Generation Workflow (`git-chglog.yml`)#

The git-chglog.yml workflow automates changelog generation from conventional commit messages:

Triggers:

Pushes to main branch
Pull requests targeting main

Configuration:

Development Tool Management#

mise Configuration#

The project uses mise (formerly rtx) for unified development tool version management, ensuring consistent environments across local development and CI.

Tool Categories:

Language Runtimes (idiomatic version files):
Pinned Development Tools:
- cosign: 3.0.5 (binary signing)
- git-cliff: 2.12.0 (changelog generation)
- golangci-lint: 2.10.1 (Go linting)
- just: 1.46.0 (task runner)
- markdownlint-cli2: 0.21.0 (Markdown linting)
- pre-commit: 4.5.1 (Git hooks)
Latest Development Tools:
- act (GitHub Actions local runner)
- goreleaser (release automation)
- oapi-codegen (API client generation)
- gosec (security scanner)

Version Management Strategy:

The project uses idiomatic version files (.go-version, .bun-version, .python-version) as the single source of truth for core language versions. Critical tools are pinned to specific versions for stability, while development tools use latest versions for flexibility. This hybrid approach balances reproducibility with access to the newest features.

CI Integration#

The GitHub Actions workflow integrates mise using jdx/mise-action@v4 with caching enabled, ensuring all development tools are available at the correct versions in CI runners without manual installation steps.

Pre-Commit Hooks#

The .pre-commit-config.yaml configuration enforces code quality through automated checks before commits:

Hook Categories:

File Validation (pre-commit-hooks v6.0.0):
- Large file detection (>1024KB)
- Case conflict detection
- Merge conflict markers
- JSON, TOML, YAML, XML syntax validation
- Line ending normalization
GitHub Actions Linting (actionlint v1.7.11):
- Validates workflow file syntax and semantics
Shell Script Linting (shellcheck v0.11.0):
- Static analysis of shell scripts
Markdown Formatting (mdformat 1.0.0):
- Formats Markdown with 9 plugins:
  - GitHub Flavored Markdown (GFM)
  - Admonitions
  - Footnotes
  - Table of Contents
  - Front matter
  - GFM alerts
  - And more

Installation:

# Install pre-commit hooks
mise exec -- pre-commit install
# Or via just
just install

Task Automation with Just#

The 432-line Justfile provides 40+ development commands organized into logical groups. All commands use mise exec to ensure consistent tool versions.

Key Recipe Groups:

Setup#

just install - Install dependencies, setup pre-commit hooks, run go mod tidy

Development#

just dev - Run application
just generate - Regenerate API client from OpenAPI spec

Code Quality#

just format - Format code
just lint - Run linters
just check - Run pre-commit checks

Testing#

just test - Run test suite
just test-coverage - Generate coverage report
just bench - Run benchmarks
just bench-compare - Compare benchmark results

Build & Release#

just build - Build agent binary
just build-release - Optimized build with stripped symbols
just release-check - Validate release readiness
just release-snapshot - Create snapshot release (no publishing)
just release - Full release with GoReleaser

Security#

just sbom - Generate Software Bill of Materials (SBOM) using CycloneDX

CI Validation#

just ci-check - Fast CI checks subset
just ci-smoke - Smoke tests
just ci-full - Comprehensive validation (pre-commit, lint, test, SBOM, release, docs)

Local GitHub Actions Testing#

just act-* - Test workflows locally using nektos/act

Documentation#

just docs - Serve MkDocs documentation locally

Testing Patterns and Infrastructure#

Test Helper Architecture#

The lib/testhelpers/ directory provides 7 specialized test utility modules (900+ lines total):

1. State Management (state_helper.go):

SetupTestState() - Full state setup with temp directories, API client
ResetTestState() - Reset state without cleanup (for subtests)
SetupMinimalTestState() - Minimal setup (AgentID + basic paths)
WithTestState() - Convenience wrapper with automatic cleanup

2. Test Fixtures (fixtures.go):

NewTestTask() - Minimal valid Task with defaults
NewTestAttack() - Attack with mock resource files
NewTestHashcatStatus() - Sample hashcat status with devices
NewTestDeviceStatus(), NewTestAgentConfiguration(), NewTestAgent()
MockDevicesList() - Mock device discovery

3. HTTP Mocking (http_mock.go):

Mock responders for authentication, configuration, heartbeat, status submission, crack submission, error reporting
Uses httpmock library for HTTP interception

4. Error Factories (error_helpers.go):

NewAPIError() - Generic API error
NewValidationAPIError() - 422 errors
NewSetTaskAbandonedError() - Task abandonment errors

5. Custom Assertions (assertions.go):

Field-by-field comparison for complex data structures
AssertDeviceStatus(), AssertTaskStatus(), AssertHashcatStatus(), AssertAgentConfiguration(), AssertErrorType()

6. File System Utilities (file_mock.go):

CreateTempTestDir() - Temporary directory with cleanup
MockDownloadServer() - HTTP server for download testing
CalculateTestChecksum() - MD5 checksum calculation
CreateHashListFile() - Hash list files for hashcat

7. Mock Sessions (mock_session.go):

NewMockSession() - Mock hashcat sessions
CreateTestHashcatParams() - Valid hashcat parameters

Testing Best Practices#

Table-Driven Tests:
Use Go's table-driven test pattern for comprehensive scenario coverage:

func TestValidation(t *testing.T) {
    tests := []struct {
        name string
        input Input
        wantErr bool
    }{
        {"valid input", validInput, false},
        {"invalid input", invalidInput, true},
    }
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            err := Validate(tt.input)
            if (err != nil) != tt.wantErr {
                t.Errorf("got error %v, wantErr %v", err, tt.wantErr)
            }
        })
    }
}

Test Isolation:
Use helper functions that return fresh data copies rather than shared fixtures to prevent test pollution.

Resource Cleanup:
Use t.Cleanup() for automatic resource cleanup instead of defer to ensure cleanup runs even if tests panic.

Race Detection:
Run tests with race detection: go test -race ./...

Docker Containerization#

Multi-Stage Build Architecture#

The Dockerfile uses a three-stage build process optimized for air-gapped deployments:

Stage 1: Build (lines 4-16)

Base: golang:latest
Downloads dependencies
Builds static binary with CGO disabled
Produces minimal, portable executable

Stage 2: Test (lines 19-20)

Runs test suite within container
Validates build before release stage

Stage 3: Release (lines 22-34)

Base: dizcza/docker-hashcat (parameterized branch)
Includes hashcat and agent binary
Default environment variables:
- API_URL: Server endpoint
- API_TOKEN: Authentication token
- ALWAYS_USE_NATIVE_HASHCAT: Force native hashcat
- HASHCAT_PATH: Path to hashcat binary

Release Container#

The Dockerfile.releaser provides a simplified container for pre-built binaries:

Base: dizcza/docker-hashcat
Copies pre-built cipherswarm-agent binary
Used by GoReleaser for release builds

Hashcat Integration#

The Docker images integrate with the dizcza/docker-hashcat base image, which provides:

GPU support (CUDA/OpenCL)
CPU-only variant (pocl branch)
Pre-configured hashcat installation
Required system libraries

This integration enables distributed hash cracking without requiring manual hashcat installation in air-gapped environments.

Air-Gapped Deployment Considerations#

The CI/CD pipeline and tooling are designed to support deployment in non-Internet-connected environments:

1. Hermetic Builds:

Docker multi-stage builds minimize external dependencies
Static binary compilation (CGO disabled) for portability
All dependencies vendored or included in container images

2. Offline Tool Management:

mise configuration can be pre-installed with all tools
Idiomatic version files enable version pinning without network access
SBOM generation provides complete dependency inventory

3. Security and Verification:

cosign integration for binary signing (version 3.0.5)
quill tool for macOS binary notarization
CycloneDX SBOM for supply chain verification

4. Deployment Workflow:

# 1. Build on Internet-connected system
just build-release

# 2. Generate SBOM for verification
just sbom

# 3. Transfer artifacts to air-gapped environment
# - Binary: dist/cipherswarm-agent
# - SBOM: sbom.json
# - Docker image: export via docker save

# 4. Deploy in air-gapped lab
docker load -i cipherswarm-agent.tar
docker run -e API_URL=... -e API_TOKEN=... cipherswarm-agent

Development Workflow Summary#

Typical Development Cycle:

Local Validation Before Push:

# Install development environment
just install

# Run full local validation
just ci-full

# Or incremental validation
just check # Pre-commit hooks
just lint # Linters only
just test # Tests only
just build # Build verification

Relevant Code Files#

File Path	Purpose	Description
`.github/workflows/go.yml`	Main CI Pipeline	Cross-platform build, test, lint, and coverage jobs
`.github/workflows/git-chglog.yml`	Changelog Automation	Auto-generate CHANGELOG from conventional commits
`justfile`	Task Automation	40+ development commands for build, test, release
`mise.toml`	Tool Version Management	Unified development tool version configuration
`.pre-commit-config.yaml`	Code Quality Hooks	Pre-commit validation and formatting hooks
`Dockerfile`	Production Container	Multi-stage build with hashcat integration
`Dockerfile.releaser`	Release Container	Simplified container for pre-built binaries
`.go-version`	Go Version	Go 1.26.0 (idiomatic version file)
`.bun-version`	Bun Version	Bun 1.3.9 (JavaScript runtime)
`.python-version`	Python Version	Python 3.14.3
`lib/testhelpers/`	Test Infrastructure	7 modules with 900+ lines of test utilities

CipherSwarm Architecture: Overall system design for distributed hash cracking
Agent API Specification: REST API contract for agent-server communication
Hashcat Integration: Integration with hashcat for password recovery operations
Security and Authentication: API token management and secure communication
Deployment Patterns: Deployment strategies for air-gapped and Internet-connected environments