{"id":20172892,"url":"https://github.com/7irelo/helmforge","last_synced_at":"2026-04-10T11:01:54.679Z","repository":{"id":248413285,"uuid":"827279197","full_name":"7irelo/helmforge","owner":"7irelo","description":"Helmforge is a production-grade deployment orchestrator that applies Git-declared state to remote infrastructure with idempotent reconciliation, health-aware rollouts, and release history tracking.","archived":false,"fork":false,"pushed_at":"2026-03-18T10:23:43.000Z","size":45,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-19T01:37:18.668Z","etag":null,"topics":["cli","cobra-cli","devops","docker","gitops","ssh","yaml","zerolog"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/7irelo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-07-11T10:43:17.000Z","updated_at":"2026-03-18T10:23:49.000Z","dependencies_parsed_at":"2024-08-17T17:54:41.741Z","dependency_job_id":null,"html_url":"https://github.com/7irelo/helmforge","commit_stats":null,"previous_names":["7irelo/loretta-django-api","7irelo/helmforge"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/7irelo/helmforge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7irelo%2Fhelmforge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7irelo%2Fhelmforge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7irelo%2Fhelmforge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7irelo%2Fhelmforge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/7irelo","download_url":"https://codeload.github.com/7irelo/helmforge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7irelo%2Fhelmforge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31639524,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-10T07:40:12.752Z","status":"ssl_error","status_checked_at":"2026-04-10T07:40:11.664Z","response_time":98,"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":["cli","cobra-cli","devops","docker","gitops","ssh","yaml","zerolog"],"created_at":"2024-11-14T01:32:45.065Z","updated_at":"2026-04-10T11:01:54.673Z","avatar_url":"https://github.com/7irelo.png","language":"Go","readme":"# helmforge\n\nA GitOps-style deployment engine that deploys apps to remote Linux hosts via SSH using Docker Compose. Uses a Git repository as the source of truth.\n\n## Features\n\n- **plan** — Preview deployment actions without executing anything\n- **apply** — Deploy with rolling strategy, health checks, and automatic rollback on failure\n- **status** — View latest release and per-host deployment status\n- **drift** — Detect when remote state diverges from desired Git state\n- **rollback** — Re-deploy a previous release by ID\n\n## Install\n\n```bash\n# Build from source (requires Go 1.21+)\ngo build -o helmforge ./cmd/helmforge\n\n# Or install directly\ngo install github.com/7irelo/helmforge/cmd/helmforge@latest\n```\n\n**Prerequisites on your local machine:**\n- `git` CLI\n- `ssh` / `scp` CLI (with key-based auth configured)\n\n**Prerequisites on remote hosts:**\n- Docker + `docker compose` (v2 plugin)\n- SSH access for the deploy user\n\n## Repository Layout\n\nhelmforge reads config from a Git repository with this structure:\n\n```\nrepo/\n  environments/\n    staging/\n      apps/\n        reporting-service/\n          app.yaml              # App config (required)\n          docker-compose.yaml   # Compose file (required)\n          .env.example          # Optional reference\n    prod/\n      apps/\n        reporting-service/\n          app.yaml\n          docker-compose.yaml\n```\n\n## app.yaml Schema\n\n```yaml\napp: reporting-service          # Application name (required)\nenv: staging                    # Environment (required)\ntargets:                        # Deploy targets (at least one required)\n  - host: 10.0.1.10            # Hostname or IP (required)\n    user: deploy                # SSH user (required)\n    port: 22                    # SSH port (default: 22)\n    path: /opt/apps/reporting   # Remote path for compose files (required)\n  - host: 10.0.1.11\n    user: deploy\n    path: /opt/apps/reporting\nsource:\n  type: compose                 # Must be \"compose\" (required)\n  composeFile: docker-compose.yaml  # Compose file name (required)\ndeploy:\n  strategy: rolling             # Deploy strategy (default: rolling)\n  health:\n    type: http                  # Health check type: \"http\" or \"none\"\n    url: http://10.0.1.10:8080/health\n    timeoutSeconds: 30          # Default: 30\npolicy:\n  allowedBranches:              # Optional: restrict deployable branches\n    - main\n    - staging\n  requireCleanWorktree: true    # Optional (default: false)\n  requireSignedCommits: false   # Optional (default: false)\n```\n\n## Usage\n\n### Plan\n\nPreview what will happen during deployment:\n\n```bash\nhelmforge plan -e staging -a reporting-service --repo git@github.com:org/infra.git\n```\n\nSample output:\n```\nDeployment Plan\n===============\n  App:    reporting-service\n  Env:    staging\n  Repo:   git@github.com:org/infra.git\n  Ref:    main\n  Commit: a1b2c3d4e5f6\n\nHost: deploy@10.0.1.10:22\n  --------------------------------------------------\n  + [ensure_dir] Create remote directory /opt/apps/reporting\n      cmd: mkdir -p /opt/apps/reporting\n  ~ [copy_files] Copy docker-compose.yaml to 10.0.1.10:/opt/apps/reporting\n  \u003e [docker_pull] Pull latest images\n      cmd: cd /opt/apps/reporting \u0026\u0026 docker compose pull\n  \u003e [docker_up] Start/update services\n      cmd: cd /opt/apps/reporting \u0026\u0026 docker compose up -d --remove-orphans\n  ? [health_check] HTTP health check http://10.0.1.10:8080/health (timeout 30s)\n  * [write_marker] Write release marker file\n\nHost: deploy@10.0.1.11:22\n  --------------------------------------------------\n  ...\n```\n\nJSON output for CI:\n```bash\nhelmforge plan -e staging -a reporting-service --repo git@github.com:org/infra.git --json\n```\n\n```json\n{\n  \"env\": \"staging\",\n  \"app\": \"reporting-service\",\n  \"repo\": \"git@github.com:org/infra.git\",\n  \"ref\": \"main\",\n  \"commit_sha\": \"a1b2c3d4e5f6789...\",\n  \"actions\": [\n    {\n      \"host\": \"deploy@10.0.1.10:22\",\n      \"step\": \"ensure_dir\",\n      \"description\": \"Create remote directory /opt/apps/reporting\",\n      \"command\": \"mkdir -p /opt/apps/reporting\"\n    },\n    ...\n  ]\n}\n```\n\n### Apply\n\nExecute the deployment:\n\n```bash\n# Serial deployment (default)\nhelmforge apply -e staging -a reporting-service --repo git@github.com:org/infra.git\n\n# Deploy up to 3 hosts in parallel\nhelmforge apply -e staging -a reporting-service --repo git@github.com:org/infra.git --max-parallel 3\n\n# Deploy a specific branch/tag/commit\nhelmforge apply -e staging -a reporting-service --repo git@github.com:org/infra.git --ref v1.2.3\n```\n\nSample output:\n```\nDeployment Plan\n===============\n  App:    reporting-service\n  Env:    staging\n  ...\n\nExecuting deployment...\n\nRelease: rel-1708617234567890\n  Status:    success\n  App:       reporting-service\n  Env:       staging\n  Commit:    a1b2c3d4\n  Started:   2025-02-22 15:00:00 UTC\n  Finished:  2025-02-22 15:00:45 UTC\n  Duration:  45s\n\n  Host Results:\n    HOST        STATUS   ERROR\n    10.0.1.10   success\n    10.0.1.11   success\n```\n\n### Status\n\nCheck the current deployment status:\n\n```bash\nhelmforge status -e staging -a reporting-service\n\n# With drift detection (compares remote marker to current Git HEAD)\nhelmforge status -e staging -a reporting-service --repo git@github.com:org/infra.git\n```\n\n### Drift\n\nCheck for configuration drift across all apps in an environment:\n\n```bash\n# Check all apps\nhelmforge drift -e staging --repo git@github.com:org/infra.git --all\n\n# Check specific apps\nhelmforge drift -e staging --repo git@github.com:org/infra.git reporting-service\n```\n\nSample output:\n```\nDrift Report for staging (desired: a1b2c3d4)\n===========================================\n  reporting-service/10.0.1.10  InSync      a1b2c3d4 -\u003e a1b2c3d4\n  reporting-service/10.0.1.11  OutOfSync   a1b2c3d4 -\u003e 9f8e7d6c\n```\n\n### Rollback\n\nRoll back to a previous release:\n\n```bash\nhelmforge rollback -e staging -a reporting-service --to rel-1708617234567890\n```\n\n### Global Flags\n\n```\n-v, --verbose    Enable verbose/debug logging\n    --log-json   Use structured JSON logging (for CI/log aggregation)\n```\n\n## Architecture\n\n```\ncmd/helmforge/main.go           Entry point\ninternal/\n  core/\n    model/                      Domain types (AppConfig, Release, Plan, etc.)\n    validate/                   YAML config parsing + validation\n    plan/                       Plan generation (read-only)\n    reconcile/                  Apply engine (deploy, drift check)\n    release/                    Output formatting (text, JSON)\n  adapters/\n    git/                        Git operations (shells out to git CLI)\n    remote/                     SSH execution (shells out to ssh/scp)\n    health/                     HTTP health checking\n    store/                      SQLite release storage\n  cli/\n    commands/                   Cobra CLI commands\n  util/\n    log/                        Structured logging (zerolog)\n    lock/                       File-based deploy locking\n```\n\nAll adapters are behind interfaces for testability. Core logic depends only on interfaces, not concrete implementations.\n\n## Safety\n\n- **Ctrl+C handling**: Cancellation stops further host deploys and marks release as cancelled\n- **Deploy locking**: File-based lock prevents concurrent deploys for the same env/app\n- **Rolling strategy**: Deploy host-by-host, stop on first failure\n- **Release tracking**: Every deploy is recorded in local SQLite with per-host results\n- **Drift detection**: Remote marker file tracks deployed commit SHA\n\n## Secrets\n\nFor v1, helmforge does NOT manage secrets directly. Recommended approaches:\n- Pre-provision `.env` files or Docker secrets on the host\n- Use an external decrypt command hook\n- Use a secrets manager that injects env vars at runtime\n\n## Running Tests\n\n```bash\ngo test ./...\n```\n\n## License\n\nMIT\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F7irelo%2Fhelmforge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F7irelo%2Fhelmforge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F7irelo%2Fhelmforge/lists"}