Skip to main content

Quick Start

Get Debugg AI running on your GitHub repository in under 5 minutes.

Prerequisites​

Add GitHub Action Workflow​

Create .github/workflows/debugg-ai.yml in your repository:

name: Debugg AI Workflow

on:
  pull_request:
    types: [opened, synchronize, reopened]
  workflow_dispatch:
    inputs:
      test_url:
        description: 'Override test URL (optional)'
        required: false
        type: string
      timeout:
        description: 'Test timeout in seconds'
        required: false
        default: '1800'
        type: string

jobs:
  debugg-ai-test-runner:
    runs-on: ubuntu-latest
    
    env:
      DEBUGGAI_API_KEY: ${{ secrets.DEBUGGAI_API_KEY }}
      NODE_ENV: test
    
    steps:
    - name: Checkout code
      uses: actions/checkout@v4
      with:
        fetch-depth: 0
    
    - name: Setup pnpm
      uses: pnpm/action-setup@v2
      with:
        version: 9
    
    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '18'
        cache: 'pnpm'
    
    - name: Install dependencies
      run: |
        echo "Installing project dependencies..."
        pnpm install --frozen-lockfile
        
    - name: Install Debugg AI CLI
      run: |
        echo "Installing Debugg AI CLI..."
        pnpm add -g @debugg-ai/cli@latest
        debugg-ai --version
    
    - name: Build application
      run: |
        echo "Building Next.js application..."
        pnpm run build
      env:
        NEXT_PUBLIC_API_URL: ${{ github.event.inputs.test_url || 'http://localhost:3000' }}
    
    - name: Set test URL
      run: |
        if [ ! -z "${{ github.event.inputs.test_url }}" ]; then
          echo "TEST_URL=${{ github.event.inputs.test_url }}" >> $GITHUB_ENV
        elif [ -z "${{ env.TEST_URL }}" ]; then
          echo "TEST_URL=http://localhost:3000" >> $GITHUB_ENV
        fi
    
    - name: Start application server
      run: |
        echo "Starting Next.js server in background..."
        pnpm run start &
        SERVER_PID=$!
        echo "SERVER_PID=$SERVER_PID" >> $GITHUB_ENV
    
    - name: Wait for server readiness
      run: |
        echo "Waiting for server to be ready..."
        for i in {1..60}; do
          if curl -f ${{ env.TEST_URL }} > /dev/null 2>&1; then
            echo "Server is ready!"
            break
          fi
          echo "Waiting for server... (attempt $i/60)"
          sleep 2
        done
        
        if ! curl -f ${{ env.TEST_URL }} > /dev/null 2>&1; then
          echo "Server failed to start!"
          exit 1
        fi
    
    - name: Run tests with Debugg AI CLI
      id: debugg_ai_test
      run: |
        echo "Starting Debugg AI test run..."
        echo "Test URL: ${{ env.TEST_URL }}"
        
        CMD="debugg-ai test"
        CMD="$CMD --api-key $DEBUGGAI_API_KEY"
        
        CMD="$CMD --repo-path ."
        CMD="$CMD --max-test-time $(($(echo '${{ github.event.inputs.timeout }}') * 1000))"
        CMD="$CMD --server-timeout 120000"
        CMD="$CMD --last 10"
        
        echo "Executing: $CMD"
        
        if $CMD; then
          echo "TEST_STATUS=passed" >> $GITHUB_ENV
          echo "Tests completed successfully!"
        else
          echo "TEST_STATUS=failed" >> $GITHUB_ENV
          echo "Tests failed!"
          exit 1
        fi
      env:
        DEBUGGAI_API_KEY: ${{ secrets.DEBUGGAI_API_KEY }}
    
    - name: Create job summary
      if: always()
      run: |
        if [ -f test-report.md ]; then
          cat test-report.md >> $GITHUB_STEP_SUMMARY
        else
          echo "# Test Report Not Available" >> $GITHUB_STEP_SUMMARY
        fi
        
        echo "" >> $GITHUB_STEP_SUMMARY
        echo "## Quick Status" >> $GITHUB_STEP_SUMMARY
        
        if [ "${{ env.TEST_STATUS }}" == "passed" ]; then
          echo "✅ **Tests PASSED**" >> $GITHUB_STEP_SUMMARY
        elif [ "${{ env.TEST_STATUS }}" == "failed" ]; then
          echo "❌ **Tests FAILED**" >> $GITHUB_STEP_SUMMARY
        else
          echo "⚠️ **Test status unknown**" >> $GITHUB_STEP_SUMMARY
        fi
    
    - name: Cleanup
      if: always()
      run: |
        echo "Cleaning up processes..."
        
        if [ ! -z "${{ env.SERVER_PID }}" ]; then
          echo "Stopping server (PID: ${{ env.SERVER_PID }})..."
          kill ${{ env.SERVER_PID }} || true
          sleep 3
        fi
        
        pkill -f "npm run start" || true
        pkill -f "next start" || true
        pkill -f "ngrok" || true
    
    - name: Set workflow status
      if: always()
      run: |
        if [ "${{ env.TEST_STATUS }}" == "failed" ]; then
          echo "❌ Tests failed! Check the artifacts and job summary for detailed results."
          exit 1
        elif [ "${{ env.TEST_STATUS }}" == "passed" ]; then
          echo "✅ All tests passed successfully!"
          exit 0
        else
          echo "⚠️ Test status unknown or error occurred"
          exit 1
        fi

Configure GitHub Secrets​

Add these secrets to your repository:

  1. Go to Settings → Secrets and variables → Actions
  2. Add required secrets:
    • DEBUGGAI_API_KEY - Your Debugg AI API key

Customize for Your Stack​

Node.js/npm​

Replace pnpm commands:

- name: Setup Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '18'
    cache: 'npm'

- name: Install dependencies
  run: npm ci

- name: Build application
  run: npm run build

- name: Start application server
  run: npm start &

Python/Django​

- name: Setup Python
  uses: actions/setup-python@v4
  with:
    python-version: '3.11'

- name: Install dependencies
  run: |
    pip install -r requirements.txt
    pip install debugg-ai-cli

- name: Run migrations
  run: python manage.py migrate

- name: Start Django server
  run: |
    python manage.py runserver &
    echo "TEST_URL=http://localhost:8000" >> $GITHUB_ENV

Docker​

- name: Build Docker image
  run: docker build -t myapp:latest .

- name: Start container
  run: |
    docker run -d -p 3000:3000 --name myapp myapp:latest
    echo "TEST_URL=http://localhost:3000" >> $GITHUB_ENV

Trigger Tests​

Tests run automatically on:

  • Pull request creation
  • Pull request updates
  • Manual workflow dispatch

To manually trigger:

  1. Go to Actions tab
  2. Select Debugg AI Workflow
  3. Click Run workflow
  4. Optionally specify custom test URL or timeout

View Results​

After tests complete:

  • Check workflow summary for pass/fail status
  • Download test artifacts for detailed results
  • Review generated test report in job summary

Next Steps​