{"id":43938175,"url":"https://github.com/versioner-io/versioner-github-action","last_synced_at":"2026-02-07T01:26:30.313Z","repository":{"id":322886583,"uuid":"1081619872","full_name":"versioner-io/versioner-github-action","owner":"versioner-io","description":"GitHub custom action for sending build and deploy events to Versioner","archived":false,"fork":false,"pushed_at":"2025-11-30T18:01:22.000Z","size":7735,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-02T22:00:11.300Z","etag":null,"topics":["ci-cd","cicd","deployment","deployment-tracking","devops","github-actions","observability"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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":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":"2025-10-23T03:32:50.000Z","updated_at":"2025-11-30T18:01:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/versioner-io/versioner-github-action","commit_stats":null,"previous_names":["versioner-io/versioner-github-action"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/versioner-io/versioner-github-action","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/versioner-io%2Fversioner-github-action","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/versioner-io%2Fversioner-github-action/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/versioner-io%2Fversioner-github-action/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/versioner-io%2Fversioner-github-action/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/versioner-io","download_url":"https://codeload.github.com/versioner-io/versioner-github-action/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/versioner-io%2Fversioner-github-action/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29183826,"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","deployment","deployment-tracking","devops","github-actions","observability"],"created_at":"2026-02-07T01:26:25.533Z","updated_at":"2026-02-07T01:26:30.306Z","avatar_url":"https://github.com/versioner-io.png","language":"TypeScript","readme":"# Versioner GitHub Action\n\nA GitHub Action for reporting deployment events to [Versioner](https://github.com/versioner-io/versioner), a deployment tracking and visibility system.\n\n## 📌 What is Versioner?\n\n**Versioner** is a deployment tracking and visibility system designed to help engineering teams:\n\n- **Detect drift** across environments - know exactly what's deployed where\n- **Reduce deployment confusion** - maintain a shared view of deployment state\n- **Improve auditability** - track who deployed what, when, and from where\n- **Streamline approvals** - integrate deployment tracking into your release pipeline\n\nVersioner captures deployment events from your CI/CD pipelines and provides:\n- REST API for querying deployment history\n- Slack app for chat-native deployment queries\n- Multi-environment tracking with automatic drift detection\n- Full audit trail with SCM integration\n\n## 🚀 Quick Start\n\nGet started in 5 minutes:\n\n### 1. Get API Credentials\n\n1. Sign up at [versioner.io](https://versioner.io)\n2. Create an API key in your account settings\n3. Note your API endpoint (e.g., `https://api.versioner.io`)\n\n### 2. Add GitHub Secret\n\nGo to your repository → **Settings** → **Secrets and variables** → **Actions**\n\nAdd secret:\n- `VERSIONER_API_KEY` - Your API key\n\n### 3. Add to Your Workflow\n\nCreate or update `.github/workflows/deploy.yml`:\n\n```yaml\nname: Deploy to Production\n\non:\n  push:\n    branches: [main]\n\njobs:\n  deploy:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n\n      - name: Deploy application\n        run: ./deploy.sh production\n\n      - name: Track deployment in Versioner\n        uses: versioner-io/versioner-github-action@v1\n        with:\n          api_key: ${{ secrets.VERSIONER_API_KEY }}\n          product_name: my-api-service\n          version: ${{ github.sha }}\n          environment: production\n```\n\n### 4. Push and Deploy\n\n```bash\ngit add .github/workflows/deploy.yml\ngit commit -m \"Add Versioner tracking\"\ngit push origin main\n```\n\nCheck the **Actions** tab to see your deployment tracked!\n\n## 📝 Inputs\n\n| Input | Required | Default | Description |\n|-------|----------|---------|-------------|\n| `api_url` | ❌ | `https://api.versioner.io` | Versioner API endpoint (can also use `VERSIONER_API_URL` env var) |\n| `api_key` | ✅* | - | Versioner API key (can also use `VERSIONER_API_KEY` env var, store in GitHub Secrets) |\n| `product_name` | ❌ | repo name | Name of the product/service (defaults to repository name) |\n| `version` | ✅ | - | Version identifier (e.g., git SHA, semantic version, build number) |\n| `environment` | ❌ | - | Target environment (required for deployment events, optional for build events) |\n| `event_type` | ❌ | `deployment` | Event type: `build` or `deployment` |\n| `status` | ❌ | `success` | Event status (`success`, `failure`, `in_progress`) |\n| `metadata` | ❌ | `{}` | Additional JSON metadata to attach to the event |\n| `fail_on_api_error` | ❌ | `true` | Fail the workflow if Versioner API has connectivity or authentication errors. Preflight check rejections (409, 423, 428) always fail regardless of this setting. |\n\n\\* Required unless provided via `VERSIONER_API_KEY` environment variable\n\n## 📤 Outputs\n\n| Output | Description |\n|--------|-------------|\n| `deployment_id` | UUID of the created deployment record (deployment events only) |\n| `event_id` | UUID of the deployment event (deployment events only) |\n| `build_id` | UUID of the created build record (build events only) |\n| `version_id` | UUID of the version record (all events) |\n| `product_id` | UUID of the product (all events) |\n\n## 🛡️ Preflight Checks\n\nWhen starting a deployment (`status: started`), Versioner automatically runs preflight checks to validate:\n- **No concurrent deployments** - Prevents multiple simultaneous deployments to the same environment\n- **No active no-deploy windows** - Respects scheduled freeze periods (e.g., Friday afternoons, holidays)\n- **Required approvals obtained** - Ensures proper authorization before deployment\n- **Flow/soak time requirements met** - Validates promotion path and minimum soak time in lower environments\n\nIf checks fail, the action will fail and the deployment will **NOT** be created.\n\n### Default Behavior\n\nPreflight checks run automatically by default:\n\n```yaml\n- name: Deploy to production\n  uses: versioner-io/versioner-github-action@v1\n  with:\n    api_key: ${{ secrets.VERSIONER_API_KEY }}\n    product_name: my-service\n    version: ${{ github.sha }}\n    environment: production\n    status: started  # Checks run automatically\n```\n\n### Skip Checks (Emergency Only)\n\nFor emergency hotfixes, admins can temporarily disable or set rules to \"Report Only\" mode in the Versioner UI. This provides centralized control without requiring code changes:\n\n1. Log 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 emergency, flip rules back to \"Enabled\"\n\n**Benefits of server-side control:**\n- No code changes required\n- Instant effect across all deployments\n- Granular control (disable specific rules, not all)\n- Auditable (status changes tracked)\n- Easy to reverse\n\n### Error Messages\n\nWhen preflight checks fail, you'll see detailed error messages:\n\n**Schedule Block (423):**\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```\n\n**Flow Violation (428):**\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 (428):**\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## 🔧 Usage Examples\n\n### Using Environment Variables (Recommended for Multiple Events)\n\nSet `VERSIONER_API_KEY` once at the job or workflow level to avoid repeating it:\n\n```yaml\nenv:\n  VERSIONER_API_KEY: ${{ secrets.VERSIONER_API_KEY }}\n\njobs:\n  deploy:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Build start\n        uses: versioner-io/versioner-github-action@v1\n        with:\n          version: ${{ github.sha }}\n          event_type: build\n          status: in_progress\n\n      - name: Build application\n        run: npm run build\n\n      - name: Build complete\n        uses: versioner-io/versioner-github-action@v1\n        with:\n          version: ${{ github.sha }}\n          event_type: build\n          status: success\n\n      - name: Deploy start\n        uses: versioner-io/versioner-github-action@v1\n        with:\n          version: ${{ github.sha }}\n          environment: production\n          status: in_progress\n\n      - name: Deploy application\n        run: ./deploy.sh production\n\n      - name: Deploy complete\n        uses: versioner-io/versioner-github-action@v1\n        with:\n          version: ${{ github.sha }}\n          environment: production\n          status: success\n```\n\n### Track a Build (No Deployment)\n\n```yaml\n- name: Track build\n  uses: versioner-io/versioner-github-action@v1\n  with:\n    api_key: ${{ secrets.VERSIONER_API_KEY }}\n    version: ${{ github.sha }}\n    event_type: build   # No environment needed - just tracking the build!\n```\n\n### Track a Deployment\n\n```yaml\n- name: Report deployment\n  uses: versioner-io/versioner-github-action@v1\n  with:\n    api_key: ${{ secrets.VERSIONER_API_KEY }}\n    product_name: my-service\n    version: ${{ github.sha }}\n    environment: production\n    event_type: deployment\n```\n\n### With Semantic Versioning\n\n```yaml\n- name: Extract version from tag\n  id: version\n  run: echo \"VERSION=${GITHUB_REF#refs/tags/v}\" \u003e\u003e $GITHUB_OUTPUT\n\n- name: Report deployment\n  uses: versioner-io/versioner-github-action@v1\n  with:\n    api_key: ${{ secrets.VERSIONER_API_KEY }}\n    product_name: my-service\n    version: ${{ steps.version.outputs.VERSION }}\n    environment: production\n```\n\n### With Custom Metadata\n\n```yaml\n- name: Report deployment with metadata\n  uses: versioner-io/versioner-github-action@v1\n  with:\n    api_key: ${{ secrets.VERSIONER_API_KEY }}\n    product_name: my-service\n    version: ${{ github.sha }}\n    environment: production\n    metadata: |\n      {\n        \"duration_seconds\": 120,\n        \"deployment_type\": \"blue-green\",\n        \"region\": \"us-east-1\"\n      }\n```\n\n### Report Deployment Failure\n\n```yaml\n- name: Deploy application\n  id: deploy\n  run: ./deploy.sh production\n  continue-on-error: true\n\n- name: Report deployment status\n  uses: versioner-io/versioner-github-action@v1\n  with:\n    api_key: ${{ secrets.VERSIONER_API_KEY }}\n    product_name: my-service\n    version: ${{ github.sha }}\n    environment: production\n    status: ${{ steps.deploy.outcome }}\n```\n\n### Best-Effort Observability\n\nAllow deployments to proceed even if Versioner API is unavailable:\n\n```yaml\n- name: Deploy to production\n  uses: versioner-io/versioner-github-action@v1\n  with:\n    api_key: ${{ secrets.VERSIONER_API_KEY }}\n    version: ${{ github.sha }}\n    environment: production\n    fail_on_api_error: false  # Don't block deployment if Versioner is down\n```\n\n**Note:** Preflight check rejections (409, 423, 428) always fail the workflow. Policy enforcement is controlled server-side via rule status (enabled, report_only, disabled) in the Versioner UI.\n\n### Multi-Environment Deployment\n\n```yaml\njobs:\n  deploy-staging:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - run: ./deploy.sh staging\n      - uses: versioner-io/versioner-github-action@v1\n        with:\n          api_key: ${{ secrets.VERSIONER_API_KEY }}\n          product_name: my-service\n          version: ${{ github.sha }}\n          environment: staging\n\n  deploy-production:\n    needs: deploy-staging\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - run: ./deploy.sh production\n      - uses: versioner-io/versioner-github-action@v1\n        with:\n          api_key: ${{ secrets.VERSIONER_API_KEY }}\n          product_name: my-service\n          version: ${{ github.sha }}\n          environment: production\n```\n\n## 🔐 Setting Up Secrets\n\n1. **Get your Versioner API key:**\n   - Sign up at [versioner.io](https://versioner.io)\n   - Create an API key in your account settings\n   - Note your API endpoint URL\n\n2. **Add secret to your GitHub repository:**\n   - Go to your repository → Settings → Secrets and variables → Actions\n   - Add `VERSIONER_API_KEY` with your API key\n   - (Optional) Add `VERSIONER_API_URL` to override the default `https://api.versioner.io`\n\n## 🤖 Auto-Populated Metadata\n\nThe action automatically includes the following metadata from the GitHub context:\n\n### Core Fields (Top-Level)\n- `scm_repository` - Repository name (e.g., `owner/repo`)\n- `scm_sha` - Git commit SHA\n- `scm_branch` - Branch name (e.g., `main`)\n- `source_system` - Always set to `\"github\"`\n- `build_number` - GitHub Actions run number\n- `invoke_id` - GitHub Actions run ID\n- `deploy_url` - Link to the GitHub Actions workflow run (for deployment events)\n- `build_url` - Link to the GitHub Actions workflow run (for build events)\n- `deployed_by` / `built_by` - GitHub username who triggered the workflow\n- `deployed_by_email` / `built_by_email` - Email from commit author (when available)\n- `deployed_by_name` / `built_by_name` - Full name from commit author (when available)\n- `started_at` / `completed_at` - Timestamp when the action runs\n\n**Note:** Email and name fields are extracted from commit metadata and are only available for `push` events. For `workflow_dispatch` (manual triggers) or other event types, these fields will be `null`.\n\n### Extra Metadata (Automatic)\n\nThe action automatically captures additional GitHub Actions context in the `extra_metadata` field with a `vi_gh_` prefix (Versioner Internal - GitHub). These fields are merged with any user-provided metadata, with **user values taking precedence**.\n\n**Auto-detected fields:**\n- `vi_gh_workflow` - Workflow name (e.g., `\"Deploy to Production\"`)\n- `vi_gh_job` - Job name (e.g., `\"deploy\"`)\n- `vi_gh_run_attempt` - Retry attempt number (e.g., `\"1\"`)\n- `vi_gh_event_name` - Trigger event (e.g., `\"push\"`, `\"pull_request\"`, `\"workflow_dispatch\"`)\n- `vi_gh_ref` - Git reference (e.g., `\"refs/heads/main\"`)\n- `vi_gh_head_ref` - PR head branch (only for pull requests)\n- `vi_gh_base_ref` - PR base branch (only for pull requests)\n\n**Example resulting metadata:**\n```json\n{\n  \"vi_gh_workflow\": \"Deploy to Production\",\n  \"vi_gh_job\": \"deploy\",\n  \"vi_gh_run_attempt\": \"1\",\n  \"vi_gh_event_name\": \"push\",\n  \"vi_gh_ref\": \"refs/heads/main\",\n  \"docker_image\": \"myapp:1.2.3\",\n  \"region\": \"us-east-1\"\n}\n```\n\n**Note:** Only fields that exist in the environment are included. The `vi_` prefix is reserved for Versioner-managed metadata.\n\n## 🏗️ How It Works\n\n1. **Validates inputs** - Ensures all required fields are provided\n2. **Enriches metadata** - Adds GitHub context automatically\n3. **Calls Versioner API** - POSTs to `/build-events/` or `/deployment-events/` endpoint\n4. **Handles errors** - Provides clear error messages and GitHub annotations\n5. **Outputs IDs** - Returns build/deployment and event IDs for downstream steps\n\nThe action uses Versioner's natural key-based API, which means:\n- Products, versions, and environments are **created automatically** if they don't exist\n- Environment types are **inferred** from names (e.g., `production` → `production`, `staging` → `staging`)\n- No pre-configuration required - just start sending events!\n\n## 📊 What Gets Tracked\n\nEach deployment event creates records in Versioner for:\n\n- **Product** - The service/application being deployed\n- **Version** - The specific version deployed (git SHA, tag, etc.)\n- **Environment** - Where it was deployed (production, staging, etc.)\n- **Deployment** - The deployment record linking version to environment\n- **Event** - The deployment event with full metadata and audit trail\n\n## 🔗 Integration with Versioner Ecosystem\n\nThis GitHub Action is part of the Versioner ecosystem:\n\n- **[Versioner API](https://github.com/versioner-io/versioner-api)** - Core REST API for deployment tracking\n- **[Versioner GitHub Action](https://github.com/versioner-io/versioner-github-action)** - This action (for GitHub workflows)\n- **Versioner Python SDK** - Coming soon (for non-GitHub CI/CD systems)\n- **Versioner Slack App** - Coming soon (chat-native deployment queries)\n\n## 🛠️ Development\n\nThis action is built with TypeScript and uses:\n- `@actions/core` - GitHub Actions toolkit\n- `@actions/github` - GitHub context and API\n- `axios` - HTTP client for API calls\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup and guidelines.\n\n## 📄 License\n\nMIT License - see [LICENSE](./LICENSE) for details.\n\n## 🔍 Troubleshooting\n\n### Email/Name Fields Are Null\n\n**Problem:** `deployed_by_email` and `deployed_by_name` are showing as `null` in the API.\n\n**Solution:** These fields are only populated for `push` events. If you're using `workflow_dispatch` (manual trigger) or other event types, commit metadata isn't available. To get email/name data:\n- Trigger the workflow via a push to a branch\n- Or use `pull_request` events which include commit data\n\n### Authentication Failed\n\n**Problem:** `Authentication failed: Invalid API key`\n\n**Solution:**\n1. Verify your API key is correct in Versioner account settings\n2. Ensure the secret is named exactly `VERSIONER_API_KEY` in GitHub\n3. Check that you're using `${{ secrets.VERSIONER_API_KEY }}` in the workflow\n\n### API Endpoint Not Found\n\n**Problem:** `API endpoint not found. Please check your api_url`\n\n**Solution:**\n1. If using default: No action needed, it should work automatically\n2. If using custom `api_url`: Verify the URL is correct (should be `https://api.versioner.io` or `https://api-development.versioner.io`)\n3. Ensure there's no trailing slash in the URL\n\n### Environment Required for Deployment Events\n\n**Problem:** Validation error about missing `environment_name`\n\n**Solution:** For `event_type: deployment`, you must provide the `environment` input:\n```yaml\nwith:\n  event_type: deployment\n  environment: production  # Required!\n```\n\nFor build events (`event_type: build`), environment is optional.\n\n## 🆘 Support\n\n- **Documentation:** [docs.versioner.io](https://docs.versioner.io)\n- **Issues:** [GitHub Issues](https://github.com/versioner-io/versioner-github-action/issues)\n- **Email:** support@versioner.io\n\n## 🙏 Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fversioner-io%2Fversioner-github-action","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fversioner-io%2Fversioner-github-action","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fversioner-io%2Fversioner-github-action/lists"}