{"id":37200949,"url":"https://github.com/sxwebdev/gcx","last_synced_at":"2026-01-14T23:10:20.779Z","repository":{"id":280203866,"uuid":"941255469","full_name":"sxwebdev/gcx","owner":"sxwebdev","description":"gcx is a lightweight CLI tool for cross-compiling Go binaries, publishing them, and deploying with custom commands. It uses a YAML config and Git tags for versioning, integrates with CI/CD pipelines, and sends notifications via popular messaging platforms.","archived":false,"fork":false,"pushed_at":"2025-08-22T08:20:24.000Z","size":57,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-08-22T10:28:43.731Z","etag":null,"topics":["deployment","devops","golang","self-hosted"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sxwebdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-01T21:15:24.000Z","updated_at":"2025-08-22T08:16:20.000Z","dependencies_parsed_at":"2025-03-28T08:23:45.279Z","dependency_job_id":"6709a363-8e95-4774-be64-d74e8b3c2067","html_url":"https://github.com/sxwebdev/gcx","commit_stats":null,"previous_names":["sxwebdev/gcx"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/sxwebdev/gcx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sxwebdev%2Fgcx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sxwebdev%2Fgcx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sxwebdev%2Fgcx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sxwebdev%2Fgcx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sxwebdev","download_url":"https://codeload.github.com/sxwebdev/gcx/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sxwebdev%2Fgcx/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28437933,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T22:37:52.437Z","status":"ssl_error","status_checked_at":"2026-01-14T22:37:31.496Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deployment","devops","golang","self-hosted"],"created_at":"2026-01-14T23:10:20.017Z","updated_at":"2026-01-14T23:10:20.726Z","avatar_url":"https://github.com/sxwebdev.png","language":"Go","readme":"# gcx\n\n**gcx** is a lightweight CLI tool for cross-compiling Go binaries and publishing them to cloud storage (e.g., S3). It reads build and release settings from a YAML configuration file (similar to GoReleaser), manages secrets via environment variables or a `.env` file, and automatically uses the current Git tag as the version.\n\n## Features\n\n- 🔨 **Cross-compilation:** Build Go binaries for multiple OS/architecture combinations.\n- 🚀 **Automated publishing:** Upload build artifacts to S3 (including self-hosted endpoints) or SSH.\n- ⚙️ **Configuration driven:** Use a YAML config file (`gcx.yaml`) to define build, archive, and publish settings.\n- 🏷️ **Versioning:** Automatically determine the version using the current Git tag.\n- 🔄 **CI/CD friendly:** Easily integrate with CI pipelines (e.g., GitLab CI).\n- 🎣 **Hooks system:** Execute commands before and after build process.\n- 📦 **Archiving:** Create archives (tar.gz) of your binaries with customizable naming.\n- 🚢 **Deployment:** Deploy your artifacts to servers via SSH with custom commands.\n- 🔔 **Notifications:** Send deployment status alerts to multiple channels (Telegram, Slack, Discord, Teams) using Shoutrrr.\n\n## Installation\n\nYou can download the pre-built binary from the [releases](https://github.com/sxwebdev/gcx/releases) page or build it from source:\n\n### Install from source\n\n```bash\ngo install github.com/sxwebdev/gcx/cmd/gcx@latest\n```\n\n### Install via script\n\n```bash\n/bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/sxwebdev/gcx/refs/heads/master/scripts/install.sh)\"\n```\n\n### Build from source\n\n```bash\ngit clone https://github.com/sxwebdev/gcx.git\ncd gcx\nmake build\n```\n\n### Use Docker Hub\n\n```bash\ndocker pull sxwebdev/gcx:latest\n```\n\n## How to use\n\n```text\n# gcx help\n\nNAME:\n   gcx - A tool for cross-compiling and publishing Go binaries\n\nUSAGE:\n   gcx [global options] [command [command options]]\n\nCOMMANDS:\n   build    Compiles binaries\n   publish  Publishes artifacts based on the configuration\n   deploy   Deploys artifacts based on the configuration\n   release  Release related commands\n   git      Git related commands\n   version  Displays the current version\n   config   Configuration related commands\n   help, h  Shows a list of commands or help for one command\n\nGLOBAL OPTIONS:\n   --help, -h  show help\n```\n\n### Git related commands\n\n```text\nNAME:\n   gcx git - Git related commands\n\nUSAGE:\n   gcx git [command [command options]]\n\nCOMMANDS:\n   version  Displays the current git tag version\n\nOPTIONS:\n   --help, -h  show help\n```\n\n## Configuration\n\nCreate a YAML configuration file named `gcx.yaml` in your project root. An example configuration:\n\n```yaml\nversion: 1\nout_dir: dist\n\n# Pre-build hooks\nbefore:\n  hooks:\n    - go mod tidy\n\n# Post-build hooks\nafter:\n  hooks:\n    - echo \"Build completed!\"\n    - ./scripts/notify-telegram.sh \"New build ready!\"\n\n# Build configuration\nbuilds:\n  - main: ./cmd/myapp\n    output_name: myapp\n    disable_platform_suffix: false\n    env:\n      - CGO_ENABLED=0\n    goos:\n      - linux\n      - darwin\n    goarch:\n      - amd64\n      - arm64\n    flags:\n      - -trimpath\n    ldflags:\n      - -s -w\n      - -X main.version={{.Version}}\n      - -X main.commit={{.Commit}}\n      - -X main.buildDate={{.Date}}\n\n# Archive configuration\narchives:\n  - formats: [\"tar.gz\"]\n    name_template: \"{{ .Binary }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}\"\n\n# Artifact publishing configuration\nblobs:\n  - provider: s3\n    name: s3-storage\n    bucket: your-bucket-name\n    directory: \"releases/{{.Version}}\"\n    region: us-west-1\n    endpoint: https://s3.example.com\n\n  - provider: ssh\n    name: stage-server\n    server: \"stage.example.com\"\n    user: \"deployer\"\n    key_path: \"~/.ssh/deploy_key\"\n    insecure_ignore_host_key: false\n    directory: \"/var/www/releases/{{.Version}}\"\n\n# Deployment configuration\ndeploys:\n  - name: \"production\"\n    provider: \"ssh\"\n    server: \"prod.example.com\"\n    user: \"deployer\"\n    key_path: \"~/.ssh/deploy_key\"\n    insecure_ignore_host_key: false\n    commands:\n      - systemctl stop myapp\n      - cp /var/www/releases/myapp/latest/myapp /usr/local/bin/\n      - chmod +x /usr/local/bin/myapp\n      - systemctl start myapp\n    alerts:\n      urls:\n        - \"telegram://token@telegram?channels=channel-1\"\n        - \"slack://token-a/token-b/token-c\"\n        - \"discord://token@channel\"\n        - \"teams://token-a/token-b/token-c\"\n\n  - name: \"staging\"\n    provider: \"ssh\"\n    server: \"staging.example.com\"\n    user: \"deployer\"\n    key_path: \"~/.ssh/deploy_key\"\n    insecure_ignore_host_key: true\n    commands:\n      - docker-compose -f /opt/myapp/docker-compose.yml down\n      - cp /var/www/releases/myapp/latest/myapp /opt/myapp/\n      - docker-compose -f /opt/myapp/docker-compose.yml up -d\n    alerts:\n      urls:\n        - \"telegram://token@telegram?channels=staging-alerts\"\n        - \"slack://token-a/token-b/token-c\"\n```\n\n### Template Variables\n\nThe following variables are available in templates:\n\n- `{{.Version}}` - Current version (from git tag)\n- `{{.Commit}}` - Current git commit hash\n- `{{.Date}}` - Build date\n- `{{.Binary}}` - Binary name\n- `{{.Os}}` - Operating system\n- `{{.Arch}}` - Architecture\n- `{{.Env.VARIABLE_NAME}}` - Environment variable value (from .env file or system environment)\n\n### Environment Variables\n\nYou can use environment variables in your ldflags and other templates. Variables can be set in:\n\n1. `.env` file in your project root\n2. System environment variables\n3. CI/CD environment variables\n\nFor security reasons, only environment variables that are explicitly referenced in your configuration (using `{{.Env.VARIABLE_NAME}}`) will be available during the build process. This prevents accidentally exposing sensitive system environment variables.\n\nExample usage in ldflags:\n\n```yaml\nldflags:\n  - \"-X main.apiKey={{.Env.API_KEY}}\"\n  - \"-X main.environment={{.Env.ENVIRONMENT}}\"\n  - \"-X main.debug={{.Env.DEBUG}}\"\n```\n\nAnd in your `.env` file:\n\n```env\nAPI_KEY=your-secret-key\nENVIRONMENT=production\nDEBUG=false\n```\n\nYou can also set build-specific environment variables in the configuration:\n\n```yaml\nbuilds:\n  - main: \"./cmd/app\"\n    env:\n      - \"CGO_ENABLED=0\"\n      - \"GO111MODULE=on\"\n```\n\n## Alerts Configuration\n\nThe tool supports sending deployment status notifications using [shoutrrr](https://containrrr.dev/shoutrrr/). You can configure alerts for each deployment to notify different channels about success or failure of the deployment.\n\n### Supported Services\n\n- Telegram\n- Slack\n- Discord\n- Microsoft Teams\n- And many more (see [shoutrrr services](https://containrrr.dev/shoutrrr/services/overview/))\n\n### URL Formats\n\nHere are examples of URL formats for different services:\n\n```yaml\nalerts:\n  urls:\n    # Telegram\n    - \"telegram://token@telegram?channels=channel-1,channel-2\"\n\n    # Slack\n    - \"slack://token-a/token-b/token-c\"\n\n    # Discord\n    - \"discord://token@channel\"\n\n    # Microsoft Teams\n    - \"teams://token-a/token-b/token-c\"\n\n    # Generic Webhook\n    - \"generic://example.com/webhook?token=token\"\n```\n\n### Alert Message Format\n\nThe alert message includes:\n\n- Application name (from deploy configuration)\n- Version (current Git tag)\n- Deployment status (Success/Failed)\n- Error details (in case of failure)\n\nExample success message:\n\n```text\nDeployment Status Update\nApplication: myapp-production\nVersion: v1.2.3\nStatus: Success\n```\n\nExample failure message:\n\n```text\nDeployment Status Update\nApplication: myapp-production\nVersion: v1.2.3\nStatus: Failed\nError: command 'systemctl start myapp' failed: exit status 1\n```\n\n## CLI Usage\n\nOnce installed, you can run the following commands:\n\n```bash\n# Initialize a new gcx.yaml configuration file\ngcx config init\ngcx config init --os linux --arch amd64  # Create config for specific platform\ngcx config init --main ./cmd/myapp       # Create config with custom main file\ngcx config init --config custom.yaml     # Create config with custom name\ngcx config init --force                  # Overwrite existing config\n\n# Build binaries according to configuration\ngcx build\n\n# Publish artifacts to configured destinations\ngcx publish\n\n# Deploy artifacts using configured deployment settings\ngcx deploy\ngcx deploy --name production  # Deploy specific configuration\n\n# Show current git tag version\ngcx git version\n\n# Generate a changelog between current and previous git tags\ngcx release changelog\ngcx release changelog --stable  # Compare with previous stable version\n\n# Show gcx version information\ngcx version\n```\n\nThe changelog command generates a markdown-formatted list of changes between the current and previous git tags, including:\n\n- List of changes with commit messages\n- Author of each change\n- Short commit hash\n- Full changelog comparison URL\n\nExample changelog output:\n\n```markdown\n## What's Changed\n\n- Add new feature by @author in abc1234\n- Fix documentation by @another-author in def5678\n\n**Full Changelog**: https://github.com/user/repo/compare/v0.0.1...v0.0.2\n```\n\n### Configuration Initialization\n\nThe `config init` command creates a new `gcx.yaml` file with default settings. Available flags:\n\n- `--os, -o`: Target operating system (default: current OS)\n- `--arch, -a`: Target architecture (default: current arch)\n- `--main, -m`: Path to the main Go file (default: ./cmd/app)\n- `--config, -c`: Path to the configuration file (default: gcx.yaml)\n- `--force, -f`: Force overwrite existing config file\n\nExample of generated configuration:\n\n```yaml\nversion: 1\nout_dir: dist\nbuilds:\n  - main: ./cmd/app\n    output_name: myapp\n    disable_platform_suffix: false\n    goos:\n      - linux\n    goarch:\n      - amd64\n    flags:\n      - -trimpath\n    ldflags:\n      - -s -w\n      - -X main.version={{.Version}}\n      - -X main.commit={{.Commit}}\n      - -X main.buildDate={{.Date}}\n```\n\n## GitLab CI/CD Integration Example\n\n```yaml\nimage: sxwebdev/gcx:latest\n\nstages:\n  - build\n  - publish\n  - deploy\n\nvariables:\n  GCX_CONFIG: gcx.yaml\n\nbuild:\n  stage: build\n  script:\n    - gcx build --config $GCX_CONFIG\n  artifacts:\n    paths:\n      - dist/\n\npublish:\n  stage: publish\n  script:\n    - gcx publish --config $GCX_CONFIG\n  only:\n    - tags\n\ndeploy:\n  stage: deploy\n  script:\n    - gcx deploy --config $GCX_CONFIG --name production\n  only:\n    - tags\n  when: manual\n```\n\nIn this pipeline:\n\n- The `build` stage compiles binaries, creates archives, and stores them in `dist/`\n- The `publish` stage uploads artifacts to configured destinations\n- The `deploy` stage (manual trigger) deploys the application to production\n- Ensure all necessary environment variables are set in your GitLab CI/CD settings\n\n## License\n\nDistributed under the MIT License. See `LICENSE` for more information.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsxwebdev%2Fgcx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsxwebdev%2Fgcx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsxwebdev%2Fgcx/lists"}