Skip to content

EXAMPLES.md

Latest commit

 

History

History
694 lines (569 loc) · 16.4 KB

EXAMPLES.md

File metadata and controls

694 lines (569 loc) · 16.4 KB
Raw

Usage Examples

This document provides comprehensive examples of using the Versioner GitHub Action in various scenarios.

Table of Contents

Build Events

Track a Build (No Deployment)

Perfect for CI pipelines that build artifacts but don't deploy them immediately.

name: Build and Test

on:
  push:
    branches: [main, develop]
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build application
        run: |
          npm install
          npm run build
          npm test

      - name: Track build in Versioner
        uses: versioner-io/versioner-github-action@v1
        with:
          api_key: ${{ secrets.VERSIONER_API_KEY }}
          version: ${{ github.sha }}
          event_type: build
          # No environment needed!
          # product_name defaults to repository name

Track Build with Custom Product Name

- name: Track build
  uses: versioner-io/versioner-github-action@v1
  with:
    api_key: ${{ secrets.VERSIONER_API_KEY }}
    product_name: my-custom-service-name
    version: ${{ github.sha }}
    event_type: build
    metadata: |
      {
        "build_type": "production-ready",
        "tests_passed": true
      }

Deployment Events

Simple Deployment Tracking

name: Deploy to Production

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Deploy application
        run: ./deploy.sh production

      - name: Track deployment
        uses: versioner-io/versioner-github-action@v1
        with:
          api_key: ${{ secrets.VERSIONER_API_KEY }}
          product_name: my-api-service
          version: ${{ github.sha }}
          environment: production

Build + Deploy Workflow

Separate Build and Deployment Steps

Track builds separately from deployments - useful when builds happen in CI but deployments are triggered separately (e.g., via Rundeck, ArgoCD, or manual approval).

name: Build and Deploy

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      version: ${{ steps.version.outputs.sha }}
    steps:
      - uses: actions/checkout@v4

      - name: Set version
        id: version
        run: echo "sha=${{ github.sha }}" >> $GITHUB_OUTPUT

      - name: Build and test
        run: |
          npm install
          npm run build
          npm test

      - name: Push artifacts
        run: |
          docker build -t myapp:${{ github.sha }} .
          docker push myapp:${{ github.sha }}

      - name: Track build in Versioner
        uses: versioner-io/versioner-github-action@v1
        with:
          api_key: ${{ secrets.VERSIONER_API_KEY }}
          version: ${{ github.sha }}
          event_type: build
          status: success

  deploy-staging:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Deploy to staging
        run: ./deploy.sh staging ${{ needs.build.outputs.version }}

      - name: Track deployment in Versioner
        uses: versioner-io/versioner-github-action@v1
        with:
          api_key: ${{ secrets.VERSIONER_API_KEY }}
          version: ${{ needs.build.outputs.version }}
          environment: staging
          event_type: deployment

  deploy-production:
    needs: [build, deploy-staging]
    runs-on: ubuntu-latest
    environment: production  # Requires manual approval
    steps:
      - uses: actions/checkout@v4

      - name: Deploy to production
        run: ./deploy.sh production ${{ needs.build.outputs.version }}

      - name: Track deployment in Versioner
        uses: versioner-io/versioner-github-action@v1
        with:
          api_key: ${{ secrets.VERSIONER_API_KEY }}
          version: ${{ needs.build.outputs.version }}
          environment: production
          event_type: deployment

Multi-Environment Deployments

Sequential Environments

name: Deploy Pipeline

on:
  push:
    branches: [main]

jobs:
  deploy-dev:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: ./deploy.sh dev
      - uses: versioner-io/versioner-github-action@v1
        with:
          api_key: ${{ secrets.VERSIONER_API_KEY }}
          product_name: my-service
          version: ${{ github.sha }}
          environment: dev

  deploy-staging:
    needs: deploy-dev
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: ./deploy.sh staging
      - uses: versioner-io/versioner-github-action@v1
        with:
          api_key: ${{ secrets.VERSIONER_API_KEY }}
          product_name: my-service
          version: ${{ github.sha }}
          environment: staging

  deploy-production:
    needs: deploy-staging
    runs-on: ubuntu-latest
    environment: production  # Requires manual approval
    steps:
      - uses: actions/checkout@v4
      - run: ./deploy.sh production
      - uses: versioner-io/versioner-github-action@v1
        with:
          api_key: ${{ secrets.VERSIONER_API_KEY }}
          product_name: my-service
          version: ${{ github.sha }}
          environment: production

Semantic Versioning

Using Git Tags

name: Release

on:
  push:
    tags:
      - 'v*.*.*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Extract version from tag
        id: version
        run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT

      - name: Build and deploy
        run: |
          ./build.sh
          ./deploy.sh production

      - name: Track deployment
        uses: versioner-io/versioner-github-action@v1
        with:
          api_key: ${{ secrets.VERSIONER_API_KEY }}
          product_name: my-service
          version: ${{ steps.version.outputs.VERSION }}
          environment: production
          metadata: |
            {
              "release_type": "production",
              "git_tag": "${{ github.ref_name }}"
            }

Using Package Version

name: Deploy NPM Package

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Get package version
        id: package
        run: echo "VERSION=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT

      - name: Publish to NPM
        run: npm publish

      - name: Track deployment
        uses: versioner-io/versioner-github-action@v1
        with:
          api_key: ${{ secrets.VERSIONER_API_KEY }}
          product_name: my-npm-package
          version: ${{ steps.package.outputs.VERSION }}
          environment: npm-registry

Custom Metadata

Deployment Duration and Details

name: Deploy with Metrics

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Record start time
        id: start
        run: echo "TIME=$(date +%s)" >> $GITHUB_OUTPUT

      - name: Deploy application
        id: deploy
        run: |
          ./deploy.sh production
          echo "REGION=us-east-1" >> $GITHUB_OUTPUT
          echo "STRATEGY=blue-green" >> $GITHUB_OUTPUT

      - name: Calculate duration
        id: duration
        run: |
          END_TIME=$(date +%s)
          DURATION=$((END_TIME - ${{ steps.start.outputs.TIME }}))
          echo "SECONDS=$DURATION" >> $GITHUB_OUTPUT

      - name: Track deployment
        uses: versioner-io/versioner-github-action@v1
        with:
          api_key: ${{ secrets.VERSIONER_API_KEY }}
          product_name: my-service
          version: ${{ github.sha }}
          environment: production
          metadata: |
            {
              "duration_seconds": ${{ steps.duration.outputs.SECONDS }},
              "deployment_strategy": "${{ steps.deploy.outputs.STRATEGY }}",
              "region": "${{ steps.deploy.outputs.REGION }}",
              "runner_os": "${{ runner.os }}",
              "triggered_by_event": "${{ github.event_name }}"
            }

Infrastructure Details

- name: Track deployment with infrastructure metadata
  uses: versioner-io/versioner-github-action@v1
  with:
    api_key: ${{ secrets.VERSIONER_API_KEY }}
    product_name: my-service
    version: ${{ github.sha }}
    environment: production
    metadata: |
      {
        "kubernetes_cluster": "prod-us-east-1",
        "namespace": "production",
        "replicas": 3,
        "image_tag": "${{ github.sha }}",
        "helm_chart_version": "2.1.0",
        "rollout_strategy": "rolling-update"
      }

Error Handling

Report Deployment Failures

name: Deploy with Error Handling

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Deploy application
        id: deploy
        run: ./deploy.sh production
        continue-on-error: true

      - name: Track deployment status
        uses: versioner-io/versioner-github-action@v1
        with:
          api_key: ${{ secrets.VERSIONER_API_KEY }}
          product_name: my-service
          version: ${{ github.sha }}
          environment: production
          status: ${{ steps.deploy.outcome }}
          metadata: |
            {
              "exit_code": "${{ steps.deploy.outputs.exit_code }}",
              "deployment_attempted": true
            }

      - name: Fail workflow if deployment failed
        if: steps.deploy.outcome == 'failure'
        run: exit 1

Track In-Progress Deployments

name: Long-Running Deployment

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Start deployment tracking
        uses: versioner-io/versioner-github-action@v1
        with:
          api_key: ${{ secrets.VERSIONER_API_KEY }}
          product_name: my-service
          version: ${{ github.sha }}
          environment: production
          status: in_progress

      - name: Run deployment
        run: ./long-deploy.sh production

      - name: Update deployment status
        if: always()
        uses: versioner-io/versioner-github-action@v1
        with:
          api_key: ${{ secrets.VERSIONER_API_KEY }}
          product_name: my-service
          version: ${{ github.sha }}
          environment: production
          status: ${{ job.status }}

Conditional Deployment

Deploy Only on Main Branch

name: Conditional Deploy

on:
  push:
    branches: [main, develop]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Deploy to appropriate environment
        id: deploy
        run: |
          if [ "${{ github.ref }}" == "refs/heads/main" ]; then
            ./deploy.sh production
            echo "ENV=production" >> $GITHUB_OUTPUT
          else
            ./deploy.sh staging
            echo "ENV=staging" >> $GITHUB_OUTPUT
          fi

      - name: Track deployment
        uses: versioner-io/versioner-github-action@v1
        with:
          api_key: ${{ secrets.VERSIONER_API_KEY }}
          product_name: my-service
          version: ${{ github.sha }}
          environment: ${{ steps.deploy.outputs.ENV }}

Deploy Only on Tag

name: Deploy on Tag

on:
  push:
    tags:
      - 'v*'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: ./deploy.sh production

      - name: Track deployment
        uses: versioner-io/versioner-github-action@v1
        with:
          api_key: ${{ secrets.VERSIONER_API_KEY }}
          product_name: my-service
          version: ${{ github.ref_name }}
          environment: production

Matrix Deployments

Deploy to Multiple Regions

name: Multi-Region Deployment

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        region: [us-east-1, us-west-2, eu-west-1]
    steps:
      - uses: actions/checkout@v4

      - name: Deploy to ${{ matrix.region }}
        run: ./deploy.sh production ${{ matrix.region }}

      - name: Track deployment
        uses: versioner-io/versioner-github-action@v1
        with:
          api_key: ${{ secrets.VERSIONER_API_KEY }}
          product_name: my-service
          version: ${{ github.sha }}
          environment: production-${{ matrix.region }}
          metadata: |
            {
              "region": "${{ matrix.region }}",
              "multi_region": true
            }

Deploy Multiple Services

name: Microservices Deployment

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        service: [api, worker, scheduler]
    steps:
      - uses: actions/checkout@v4

      - name: Deploy ${{ matrix.service }}
        run: ./deploy-${{ matrix.service }}.sh production

      - name: Track deployment
        uses: versioner-io/versioner-github-action@v1
        with:
          api_key: ${{ secrets.VERSIONER_API_KEY }}
          product_name: ${{ matrix.service }}
          version: ${{ github.sha }}
          environment: production

Using Outputs

Use Deployment ID in Downstream Steps

name: Deploy with Notifications

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: ./deploy.sh production

      - name: Track deployment
        id: versioner
        uses: versioner-io/versioner-github-action@v1
        with:
          api_key: ${{ secrets.VERSIONER_API_KEY }}
          product_name: my-service
          version: ${{ github.sha }}
          environment: production

      - name: Send Slack notification
        run: |
          curl -X POST ${{ secrets.SLACK_WEBHOOK }} \
            -H 'Content-Type: application/json' \
            -d '{
              "text": "Deployment tracked!",
              "blocks": [{
                "type": "section",
                "text": {
                  "type": "mrkdwn",
                  "text": "Deployment ID: `${{ steps.versioner.outputs.deployment_id }}`\nEvent ID: `${{ steps.versioner.outputs.event_id }}`"
                }
              }]
            }'

Advanced Examples

Monorepo with Multiple Products

name: Monorepo Deploy

on:
  push:
    branches: [main]

jobs:
  detect-changes:
    runs-on: ubuntu-latest
    outputs:
      api: ${{ steps.changes.outputs.api }}
      web: ${{ steps.changes.outputs.web }}
    steps:
      - uses: actions/checkout@v4
      - uses: dorny/paths-filter@v2
        id: changes
        with:
          filters: |
            api:
              - 'packages/api/**'
            web:
              - 'packages/web/**'

  deploy-api:
    needs: detect-changes
    if: needs.detect-changes.outputs.api == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: ./deploy-api.sh production
      - uses: versioner-io/versioner-github-action@v1
        with:
          api_key: ${{ secrets.VERSIONER_API_KEY }}
          product_name: my-api
          version: ${{ github.sha }}
          environment: production

  deploy-web:
    needs: detect-changes
    if: needs.detect-changes.outputs.web == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: ./deploy-web.sh production
      - uses: versioner-io/versioner-github-action@v1
        with:
          api_key: ${{ secrets.VERSIONER_API_KEY }}
          product_name: my-web-app
          version: ${{ github.sha }}
          environment: production

Best Practices

  1. Always use GitHub Secrets for api_key - never hardcode credentials
  2. api_url is optional - defaults to https://api.versioner.io (use variables for testing/self-hosted)
  3. Use descriptive product names that match your service naming conventions
  4. Include relevant metadata to make deployments searchable and auditable
  5. Track both successes and failures for complete visibility
  6. Use consistent environment names across your organization
  7. Leverage outputs for integration with other tools (Slack, PagerDuty, etc.)