{"id":43936577,"url":"https://github.com/versioner-io/versioner-cli","last_synced_at":"2026-02-07T01:10:54.077Z","repository":{"id":322882878,"uuid":"1084467588","full_name":"versioner-io/versioner-cli","owner":"versioner-io","description":"Command-line tool for tracking build and deployment events in Versioner","archived":false,"fork":false,"pushed_at":"2025-12-20T21:31:59.000Z","size":145,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-22T20:44:50.205Z","etag":null,"topics":["ci-cd","cicd","cli","deployment","deployment-tracking","devops","golang","observability"],"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/versioner-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","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":"2025-10-27T18:07:32.000Z","updated_at":"2025-12-20T21:31:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/versioner-io/versioner-cli","commit_stats":null,"previous_names":["versioner-io/versioner-cli"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/versioner-io/versioner-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/versioner-io%2Fversioner-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/versioner-io%2Fversioner-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/versioner-io%2Fversioner-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/versioner-io%2Fversioner-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/versioner-io","download_url":"https://codeload.github.com/versioner-io/versioner-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/versioner-io%2Fversioner-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29183368,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-07T00:44:15.062Z","status":"ssl_error","status_checked_at":"2026-02-07T00:35:01.758Z","response_time":59,"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":["ci-cd","cicd","cli","deployment","deployment-tracking","devops","golang","observability"],"created_at":"2026-02-07T01:10:53.420Z","updated_at":"2026-02-07T01:10:54.048Z","avatar_url":"https://github.com/versioner-io.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Versioner CLI\n\n\u003e **Beta Release** - This CLI is currently in beta. We're actively seeking feedback from early users!\n\n## 📌 What is Versioner?\n\n**Versioner** is a deployment tracking and visibility system designed to help engineering teams:\n\n- Detect drift, skipped steps, or misconfigurations across environments\n- Maintain a shared view of what’s deployed where\n- Reduce wasted time from unclear or missing deployment context\n- Improve auditability, ownership, and approval processes in release pipelines\n\nVersioner takes events such as \"build completed\" or \"deployment started\" in via the Events API and stores them in a database. It then provides a query endpoint to retrieve deployment history and a Slack app to query the database for deployment history in a chat-native interface.\n\n### Full ecosystem architecture:\n\n- **API**: Python-based REST API, accessed by the UI, Slack app and external events senders\n- **Database**: Neon-hosted Postgres, with a **database-per-customer** design\n- **Frontend**: React UI served via CloudFront\n- **CLI (this project)**: Command-line interface for submitting events\n- **GitHub Action**: GitHub Action for submitting events\n- **Slack App**: Chat-native interface for querying deployment state and approvals\n- **Events API**: External events (e.g. CI/CD notifications) flow through API Gateway → SQS → Lambda → DB\n\n## This project\n\nThis project is the CLI for Versioner. It provides a simple way to submit build and deployment events to the Versioner API from any CI/CD system or deployment tool.\n\n**Current Status**: Phase 1 (MVP) complete! The CLI is functional with core features including:\n- ✅ Track build and deployment events\n- ✅ Auto-detection for 8 CI/CD systems (GitHub Actions, GitLab CI, Jenkins, CircleCI, Bitbucket, Azure DevOps, Travis CI, Rundeck)\n- ✅ Retry logic with exponential backoff\n- ✅ Status value normalization\n- ✅ Environment variable configuration\n\n## Installation\n\n### Beta Release - Direct Download\n\nDownload pre-built binaries from [GitHub Releases](https://github.com/versioner-io/versioner-cli/releases):\n\n```bash\n# Linux (amd64)\ncurl -L https://github.com/versioner-io/versioner-cli/releases/latest/download/versioner-linux-amd64 -o versioner\nchmod +x versioner\nsudo mv versioner /usr/local/bin/\n\n# Linux (arm64)\ncurl -L https://github.com/versioner-io/versioner-cli/releases/latest/download/versioner-linux-arm64 -o versioner\nchmod +x versioner\nsudo mv versioner /usr/local/bin/\n\n# macOS (Apple Silicon)\ncurl -L https://github.com/versioner-io/versioner-cli/releases/latest/download/versioner-darwin-arm64 -o versioner\nchmod +x versioner\nsudo mv versioner /usr/local/bin/\n\n# macOS (Intel)\ncurl -L https://github.com/versioner-io/versioner-cli/releases/latest/download/versioner-darwin-amd64 -o versioner\nchmod +x versioner\nsudo mv versioner /usr/local/bin/\n\n# Windows (amd64)\n# Download versioner-windows-amd64.exe from releases and add to PATH\n```\n\n**Coming Soon:**\n- Homebrew tap for easier installation on macOS/Linux\n- Automated install script\n\n## Quick Start\n\n### Get Your API Key\n\n1. Sign up at [app.versioner.io](https://app.versioner.io)\n2. Navigate to Settings → API Keys\n3. Create a new API key and save it securely\n\n### Track a Build Event\n\n```bash\nversioner track build \\\n  --product api-service \\\n  --version 1.2.3 \\\n  --status completed\n```\n\n### Track a Deployment Event\n\n```bash\nversioner track deployment \\\n  --product api-service \\\n  --environment production \\\n  --version 1.2.3 \\\n  --status success\n```\n\n### Configuration\n\nSet your API key via environment variable:\n\n```bash\nexport VERSIONER_API_KEY=your-api-key-here\nexport VERSIONER_API_URL=https://api.versioner.io  # Optional, defaults to production\n```\n\nOr use a config file at `~/.versioner/config.yaml`:\n\n```yaml\napi_key: your-api-key-here\napi_url: https://api.versioner.io\n```\n\n## Usage Examples\n\n### GitHub Actions\n\n```yaml\n- name: Track build\n  run: |\n    versioner track build \\\n      --product api-service \\\n      --version ${{ github.sha }} \\\n      --status completed\n  env:\n    VERSIONER_API_KEY: ${{ secrets.VERSIONER_API_KEY }}\n\n- name: Track deployment\n  run: |\n    versioner track deployment \\\n      --product api-service \\\n      --environment production \\\n      --version ${{ github.sha }} \\\n      --status success\n  env:\n    VERSIONER_API_KEY: ${{ secrets.VERSIONER_API_KEY }}\n```\n\n### GitLab CI\n\n```yaml\nbuild:\n  script:\n    - make build\n  after_script:\n    - versioner track build --product api --version $CI_COMMIT_SHA --status completed\n\ndeploy:\n  script:\n    - make deploy\n  after_script:\n    - versioner track deployment --product api --environment $CI_ENVIRONMENT_NAME --version $CI_COMMIT_SHA --status success\n```\n\n### Jenkins\n\n```groovy\nstage('Build') {\n  steps {\n    sh 'make build'\n    sh 'versioner track build --product api --version ${BUILD_NUMBER} --status completed'\n  }\n}\n\nstage('Deploy') {\n  steps {\n    sh 'make deploy'\n    sh 'versioner track deployment --product api --environment prod --version ${BUILD_NUMBER} --status success'\n  }\n}\n```\n\n## Status Values\n\nBoth build and deployment events support these statuses:\n\n- `pending` - Queued/scheduled\n- `started` - Currently executing\n- `completed` - Successfully finished\n- `failed` - Failed with errors\n- `aborted` - Cancelled or skipped\n\nAliases like `success`, `in_progress`, `cancelled`, etc. are automatically normalized.\n\n## API Error Handling\n\nThe CLI provides control over how API connectivity and authentication errors are handled:\n\n### `--fail-on-api-error` Flag\n\n**Default:** `true` (API errors fail the command)\n\n**Purpose:** Controls whether API connectivity/authentication errors should block deployments\n\n**Behavior:**\n- `--fail-on-api-error=true` (default): API errors fail the command (exit code 4)\n- `--fail-on-api-error=false`: API errors log warnings but allow command to continue (exit code 0)\n\n**Environment Variable:** `VERSIONER_FAIL_ON_API_ERROR=true|false`\n\n**Use Cases:**\n\n**Mission-Critical Audit Trail (Default):**\n```bash\n# Every deployment MUST be recorded\nversioner track deployment \\\n  --product api-service \\\n  --environment production \\\n  --version 1.2.3 \\\n  --status started \\\n  --fail-on-api-error true  # Default behavior\n```\n\n**Best-Effort Observability:**\n```bash\n# Recording is nice-to-have, don't block production deployments\nversioner track deployment \\\n  --product api-service \\\n  --environment production \\\n  --version 1.2.3 \\\n  --status started \\\n  --fail-on-api-error false\n```\n\n**API Errors Affected:**\n- 401 (Authentication failed)\n- 403 (Authorization failed)\n- 404 (Endpoint not found)\n- 422 (Validation error)\n- Connection refused\n- Request timeout\n- Other HTTP errors\n\n**Note:** Preflight check rejections (409, 423, 428) always fail regardless of this flag. Policy enforcement is controlled server-side via rule status settings.\n\n## Preflight Checks\n\nWhen tracking a deployment with `--status=started`, the API automatically runs **preflight checks** to validate the deployment before it proceeds. These checks help enforce deployment policies and prevent common issues.\n\n### What Gets Checked\n\nPreflight checks validate:\n\n1. **Concurrent Deployments** - Prevents multiple simultaneous deployments to the same environment\n2. **No-Deploy Windows** - Blocks deployments during scheduled blackout periods (e.g., Friday afternoons)\n3. **Flow Requirements** - Ensures versions are deployed to prerequisite environments first (e.g., staging before production)\n4. **Soak Time** - Requires versions to run in an environment for a minimum duration before promoting\n5. **Quality Approvals** - Requires QA/security sign-off from prerequisite environments\n6. **Release Approvals** - Requires manager/lead approval before deploying to sensitive environments\n\n### Exit Codes\n\nThe CLI uses specific exit codes to indicate different failure types:\n\n- **0** - Success (deployment allowed)\n- **1** - General error (network issues, invalid arguments)\n- **4** - API error (authentication, validation)\n- **5** - Preflight check failure (deployment blocked)\n\n### Error Types and Responses\n\n#### 409 - Deployment Conflict\n\nAnother deployment is already in progress:\n\n```\n⚠️  Deployment Conflict\n\nAnother deployment to production is already in progress\nAnother deployment is in progress. Please wait and retry.\n```\n\n**Action:** Wait for the current deployment to complete, then retry.\n\n#### 423 - Schedule Block\n\nDeployment blocked by a no-deploy window:\n\n```\n🔒 Deployment Blocked by Schedule\n\nRule: Production Freeze - Friday Afternoons\nDeployment blocked by no-deploy window\n\nRetry after: 2025-11-21T18:00:00-08:00\n\nTo skip checks (emergency only), add:\n  --skip-preflight-checks\n```\n\n**Action:** Wait until the blackout window ends, or use `--skip-preflight-checks` for emergencies.\n\n#### 428 - Precondition Failed\n\nMissing required prerequisites:\n\n**Flow Violation:**\n```\n❌ Deployment Precondition Failed\n\nError: FLOW_VIOLATION\nRule: Staging Required Before Production\nVersion must be deployed to staging first\n\nDeploy to required environments first, then retry.\n```\n\n**Insufficient Soak Time:**\n```\n❌ Deployment Precondition Failed\n\nError: INSUFFICIENT_SOAK_TIME\nRule: 24hr Staging Soak\nVersion must soak in staging for at least 24 hours\n\nRetry after: 2025-11-22T10:00:00Z\n\nWait for soak time to complete, then retry.\n```\n\n**Approval Required:**\n```\n❌ Deployment Precondition Failed\n\nError: APPROVAL_REQUIRED\nRule: Prod Needs 2 Approvals\nproduction deployment requires 2 release approval(s)\n\nApproval required before deployment can proceed.\nObtain approval via Versioner UI, then retry.\n```\n\n### Policy Control\n\n**Preferred Approach: Server-Side Rule Status**\n\nPolicy enforcement should be controlled server-side via the Versioner UI:\n\n**Rule Status Options:**\n- `enabled` - Rule is evaluated and blocks on failure (returns 409/423/428)\n- `report_only` - Rule is evaluated but doesn't block (returns 200 with warnings)\n- `disabled` - Rule is not evaluated at all\n\n**Emergency Deployments:**\n1. Admin logs into Versioner UI\n2. Navigate to Deployment Rules\n3. Change rule status from \"Enabled\" to \"Report Only\" or \"Disabled\"\n4. Deploy normally - rules won't block\n5. After incident, flip back to \"Enabled\"\n\n**Benefits:**\n- ✅ Centralized control (no code changes)\n- ✅ Granular (per-rule control)\n- ✅ Auditable (status changes tracked)\n- ✅ Reversible (instant flip back)\n- ✅ Consistent across all clients\n\n**Emergency Override (Deprecated):**\n\nFor immediate bypass when you can't access the UI:\n\n```bash\nversioner track deployment \\\n  --product api-service \\\n  --environment production \\\n  --version 1.2.3-hotfix \\\n  --status started \\\n  --skip-preflight-checks\n```\n\n**⚠️ Deprecation Notice:** `--skip-preflight-checks` is deprecated. Use server-side rule status control instead. This flag will be removed in a future version.\n\n**⚠️ Warning:** Only use `--skip-preflight-checks` for:\n- Production incidents requiring immediate fixes when UI is unavailable\n- Approved emergency changes\n- When deployment rules are temporarily misconfigured\n\nAlways document why checks were skipped in your deployment logs.\n\n### Full Deployment Workflow\n\n```bash\n# 1. Start deployment (triggers preflight checks)\nversioner track deployment \\\n  --product api-service \\\n  --environment production \\\n  --version 1.2.3 \\\n  --status started\n\n# 2. If checks pass (exit code 0), proceed with actual deployment\nif [ $? -eq 0 ]; then\n  # Your deployment commands here\n  kubectl apply -f deployment.yaml\n\n  # 3. Report completion\n  versioner track deployment \\\n    --product api-service \\\n    --environment production \\\n    --version 1.2.3 \\\n    --status completed\nfi\n```\n\n### CI/CD Integration\n\n**GitHub Actions:**\n```yaml\n- name: Start Deployment\n  id: preflight\n  run: |\n    versioner track deployment \\\n      --product api-service \\\n      --environment production \\\n      --version ${{ github.sha }} \\\n      --status started\n  env:\n    VERSIONER_API_KEY: ${{ secrets.VERSIONER_API_KEY }}\n  continue-on-error: true\n\n- name: Deploy Application\n  if: steps.preflight.outcome == 'success'\n  run: |\n    # Your deployment commands\n    kubectl apply -f k8s/\n\n- name: Report Completion\n  if: steps.preflight.outcome == 'success'\n  run: |\n    versioner track deployment \\\n      --product api-service \\\n      --environment production \\\n      --version ${{ github.sha }} \\\n      --status completed\n  env:\n    VERSIONER_API_KEY: ${{ secrets.VERSIONER_API_KEY }}\n```\n\n**GitLab CI:**\n```yaml\ndeploy:production:\n  script:\n    # Preflight check\n    - |\n      versioner track deployment \\\n        --product api \\\n        --environment production \\\n        --version $CI_COMMIT_SHA \\\n        --status started\n    # Deploy if checks pass\n    - kubectl apply -f k8s/\n    # Report completion\n    - |\n      versioner track deployment \\\n        --product api \\\n        --environment production \\\n        --version $CI_COMMIT_SHA \\\n        --status completed\n```\n\n## CI/CD Auto-Detection\n\nThe CLI automatically detects your CI/CD environment and extracts relevant metadata. Supported systems:\n\n- **GitHub Actions** - Repository, commit SHA, run ID, actor\n- **GitLab CI** - Project path, commit SHA, pipeline ID, user\n- **Jenkins** - Repository, commit SHA, build number, user (with plugin)\n- **CircleCI** - Repository, commit SHA, build number, workflow ID\n- **Bitbucket Pipelines** - Repository, commit SHA, build number\n- **Azure DevOps** - Repository, commit SHA, build number, user\n- **Travis CI** - Repository, commit SHA, build number\n- **Rundeck** - Job name, execution ID, user, project\n\nWhen running in a supported CI/CD system, you can omit many flags:\n\n```bash\n# In GitHub Actions - auto-detects repository, SHA, build number, etc.\nversioner track build --product api-service --status completed\n\n# In GitLab CI - auto-detects project, SHA, pipeline info\nversioner track deployment --environment production --status success\n```\n\nUse `--verbose` to see which values were auto-detected:\n\n```bash\nversioner track build --product=api --status=completed --verbose\n```\n\n### Auto-Detected Extra Metadata\n\nThe CLI automatically captures system-specific metadata and includes it in the `extra_metadata` field with a `vi_` prefix (Versioner Internal). This metadata is merged with any user-provided `--extra-metadata` values, with user values taking precedence.\n\n**GitHub Actions:**\n- `vi_gh_workflow` - Workflow name\n- `vi_gh_job` - Job name\n- `vi_gh_run_attempt` - Retry attempt number\n- `vi_gh_event_name` - Triggering event (push, pull_request, etc.)\n- `vi_gh_ref` - Git reference\n- `vi_gh_head_ref` - PR head branch (if applicable)\n- `vi_gh_base_ref` - PR base branch (if applicable)\n\n**GitLab CI:**\n- `vi_gl_pipeline_id` - Pipeline ID\n- `vi_gl_pipeline_url` - Direct link to pipeline\n- `vi_gl_job_id` - Job ID\n- `vi_gl_job_name` - Job name\n- `vi_gl_job_url` - Direct link to job\n- `vi_gl_pipeline_source` - Pipeline trigger source\n\n**Jenkins:**\n- `vi_jenkins_job_name` - Job name\n- `vi_jenkins_build_url` - Build URL\n- `vi_jenkins_node_name` - Build agent name\n- `vi_jenkins_executor_number` - Executor number\n\n**CircleCI:**\n- `vi_circle_workflow_id` - Workflow ID\n- `vi_circle_workflow_job_id` - Workflow job ID\n- `vi_circle_job_name` - Job name\n- `vi_circle_node_index` - Parallel node index\n\n**Bitbucket Pipelines:**\n- `vi_bb_pipeline_uuid` - Pipeline UUID\n- `vi_bb_step_uuid` - Step UUID\n- `vi_bb_workspace` - Workspace name\n- `vi_bb_repo_slug` - Repository slug\n\n**Azure DevOps:**\n- `vi_azure_build_id` - Build ID\n- `vi_azure_definition_name` - Pipeline definition name\n- `vi_azure_agent_name` - Agent name\n- `vi_azure_team_project` - Team project name\n\n**Travis CI:**\n- `vi_travis_build_id` - Build ID\n- `vi_travis_job_id` - Job ID\n- `vi_travis_job_number` - Job number\n- `vi_travis_event_type` - Event type\n\n**Rundeck:**\n- `vi_rd_job_id` - Job UUID\n- `vi_rd_job_execid` - Execution ID\n- `vi_rd_job_serverurl` - Rundeck server URL\n- `vi_rd_job_project` - Project name\n- `vi_rd_job_name` - Job name\n- `vi_rd_job_group` - Job group\n- `vi_rd_job_url` - Direct link to execution\n\n**Example with merged metadata:**\n```bash\n# Auto-detected metadata is automatically included\nversioner track build \\\n  --product=api-service \\\n  --status=completed \\\n  --extra-metadata='{\"docker_image\": \"myorg/api:1.2.3\", \"artifacts\": [\"binary\"]}'\n\n# Result includes both auto-detected (vi_*) and user-provided fields\n```\n\n**Note:** Only fields that are actually present in the environment are included. Missing values are gracefully omitted.\n\n## Feedback \u0026 Support\n\nThis is a beta release and we'd love your feedback!\n\n- **Issues \u0026 Bug Reports:** [GitHub Issues](https://github.com/versioner-io/versioner-cli/issues)\n- **Feature Requests:** [GitHub Discussions](https://github.com/versioner-io/versioner-cli/discussions)\n- **Security Issues:** See [SECURITY.md](SECURITY.md)\n\n## Documentation\n\nFor comprehensive documentation:\n\n- See [Versioner docs](https://docs.versioner.io)\n\n### Repository-Specific Docs\n\n- [CONTRIBUTING.md](CONTRIBUTING.md) - Development workflow, setup, testing\n- [SECURITY.md](SECURITY.md) - Security policy and vulnerability reporting\n- [LICENSE](LICENSE) - MIT License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fversioner-io%2Fversioner-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fversioner-io%2Fversioner-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fversioner-io%2Fversioner-cli/lists"}