---

name: gcx description: > Go cross-compilation, build, publish, and deploy CLI tool (github.com/sxwebdev/gcx). Use this skill whenever working in the gcx codebase — editing build/publish/deploy logic, CLI commands, config structs, archive creation, SSH/S3 publishing, deployment alerts, or tests. Also triggers when code imports "sxwebdev/gcx", references gcx.yaml configuration, or when the user mentions: gcx CLI, Go cross-compilation tool, gcx build, gcx publish, gcx deploy, gcx release changelog, gcx config init, BlobConfig, BuildConfig, DeployConfig, ArchiveConfig, HooksConfig, Publisher, Deployer, Archiver, AlertData, shoutrrr alerts, or GoReleaser alternative. user-invocable: false

gcx — Go Cross-Compilation & Deploy Tool

Overview

gcx is a lightweight CLI tool for cross-compiling Go binaries and publishing them to S3 or SSH servers. It reads YAML configuration (gcx.yaml), manages secrets via .env files, uses git tags for versioning, and supports deployment with notifications.

The codebase follows a clean package architecture with each concern separated into its own package under internal/.

Architecture

See references/architecture.md for the full codebase map including file layout, key packages, and data flow.

Key packages:

• cmd/gcx/main.go — thin CLI layer (~200 lines): command definitions, flag wiring, package orchestration
• internal/config/ — all config structs, YAML loading, comprehensive validation
• internal/build/ — build orchestration, BuildArtifact struct, archive creation
• internal/archive/ — Archiver interface with tar.gz and zip implementations
• internal/publish/ — Publisher interface with S3 and SSH implementations
• internal/deploy/ — Deployer interface with SSH implementation
• internal/notify/ — notification sending via shoutrrr
• internal/git/ — git operations (tag, changelog, commit hash)
• internal/sshutil/ — shared SSH client factory, known hosts management
• internal/tmpl/ — shared template processing utility
• internal/hook/ — hook execution via sh -c
• internal/shellutil/ — shell escaping utilities
• internal/helpers/ — path expansion utility

Configuration Schema

See references/config-schema.md for the complete config schema with all fields, types, defaults, and template variables.

Instructions

Adding a new CLI command

1. Define the command in cmd/gcx/main.go inside the cli.Command tree
2. Use urfave/cli/v3 patterns — cli.Command with Name, Usage, Flags, and Action
3. The action handler receives context.Context — pass it to all package functions
4. Access config via config.Load(cmd.String("config")) when the command needs configuration

Modifying config structs

1. Add the new field to the appropriate struct in internal/config/config.go
2. Include the yaml:"field_name,omitempty" tag
3. Add validation in the struct's Validate() method
4. Update examples/gcx.yaml to document the new field

Adding a new publish provider

1. Create a new file internal/publish/{provider}.go
2. Implement the Publisher interface: Name() string and Publish(ctx, artifactsDir, version) error
3. Add provider-specific fields to config.BlobConfig with yaml:"...,omitempty" tags
4. Add validation in BlobConfig.Validate() for the new provider
5. Register the provider in publish.NewPublisher() factory
6. Use tmpl.Process() for directory template processing
7. Use sshutil.NewClient() if the provider needs SSH (eliminates code duplication)

Adding a new deploy provider

1. Create a new file internal/deploy/{provider}.go
2. Implement the Deployer interface: Name() string and Deploy(ctx) error
3. Add provider-specific fields to config.DeployConfig
4. Add validation in DeployConfig.Validate()
5. Register in deploy.NewDeployer() factory

Working with templates

gcx uses internal/tmpl.Process() — a wrapper around Go's text/template:

result, err := tmpl.Process("name", templateStr, data)

Template data for builds:

• {{.Version}} — git tag
• {{.Commit}} — short commit hash
• {{.Date}} — RFC3339 build timestamp
• {{.Env.VAR_NAME}} — environment variable (security-filtered)

For archive naming (ArchiveTemplateData): {{.Binary}}, {{.Version}}, {{.Os}}, {{.Arch}}

Adding deployment alerts

Alerts use the shoutrrr library via internal/notify/.

notify.Send(urls, notify.AlertData{
    AppName: "myapp",
    Version: "v1.0.0",
    Status:  "Success",
})

Error handling patterns

• Wrap errors with context: fmt.Errorf("doing X: %w", err)
• All config structs have Validate() methods
• Alert failures are logged but don't block deployment
• Hook failures stop execution immediately
• Git command failures return sensible defaults ("0.0.0" for tag, "none" for commit)

Building and testing

make build          # builds to ./bin/gcx
go test ./...       # run all tests
make docker-build   # build Docker image
make install        # go install

Key principles

• Clean package architecture: Each concern is in its own package. cmd/gcx/main.go is a thin CLI layer that wires packages together.

• Interfaces for providers: Publisher, Deployer, and Archiver interfaces enable testability and easy extension via factory functions.

• Shared SSH client factory: sshutil.NewClient() eliminates SSH client code duplication between publish and deploy.

• Shell safety: Hooks run via sh -c (not naive strings.Fields parsing). SSH remote commands use shellutil.Quote() for shell escaping.

• Context propagation: All operations accept context.Context for cancellation support.

• Template safety: Environment variables are selectively exposed — only vars explicitly referenced in {{.Env.X}} patterns are loaded.

• Structured artifact metadata: build.Artifact carries binary name, version, OS, arch as structured data — no fragile filename parsing.

• Parallel builds: errgroup with configurable concurrency limit handles concurrent compilation and archiving.