FeaturesCI/CDJenkins

Jenkins Integration

Integrate BugBrain tests into your Jenkins pipelines to automatically run tests as part of your build process.

Quick Start

Step 1: Generate CI/CD Token

In BugBrain:

  1. Go to Settings → CI/CD Integration
  2. Click Generate Token and save:
    • Webhook URL
    • Webhook Secret
    • Test Plan ID

Step 2: Add Credentials to Jenkins

  1. Go to Jenkins → Manage Jenkins → Manage Credentials
  2. Click System (or appropriate domain)
  3. Click Add Credentials
  4. Select: Secret text credential type
  5. Paste webhook secret
  6. Set ID: bugbrain-webhook-secret
  7. Save

Step 3: Create Jenkins Job

Option A: Declarative Pipeline (Recommended)

Create file Jenkinsfile in your repo:

pipeline {
  agent any
 
  environment {
    BUGBRAIN_WEBHOOK_URL = 'https://api.bugbrain.tech/webhooks/ci/...'
    BUGBRAIN_SECRET = credentials('bugbrain-webhook-secret')
  }
 
  stages {
    stage('Build') {
      steps {
        // Your build steps...
        sh 'npm run build'
      }
    }
 
    stage('Test') {
      steps {
        // Your unit tests...
        sh 'npm test'
      }
    }
 
    stage('BugBrain Tests') {
      steps {
        script {
          sh '''
            curl -X POST "$BUGBRAIN_WEBHOOK_URL" \
              -H "Content-Type: application/json" \
              -H "X-Bugbrain-Secret: $BUGBRAIN_SECRET" \
              -d '{"branch": "'$GIT_BRANCH'", "commit": "'$GIT_COMMIT'"}'
          '''
        }
      }
    }
  }
}

Option B: Freestyle Job

  1. Create new Freestyle job
  2. Under Build section, click Add build step → Execute shell
  3. Add script:
curl -X POST "$BUGBRAIN_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -H "X-Bugbrain-Secret: $BUGBRAIN_SECRET" \
  -d '{
    "branch": "'$GIT_BRANCH'",
    "commit": "'$GIT_COMMIT'",
    "build_number": "'$BUILD_NUMBER'"
  }'

Step 4: Run Pipeline

Commit and push to trigger the build:

git add Jenkinsfile
git commit -m "Add BugBrain CI integration"
git push origin feature-branch

BugBrain tests will run automatically!

Jenkinsfile Examples

Declarative Pipeline (Full Example)

pipeline {
  agent any
 
  parameters {
    string(name: 'BUGBRAIN_TEST_PLAN', defaultValue: 'prod-tests', description: 'BugBrain test plan ID')
    booleanParam(name: 'FAIL_ON_BUGS', defaultValue: true, description: 'Fail job if bugs found')
  }
 
  environment {
    BUGBRAIN_API_URL = 'https://api.bugbrain.tech'
    BUGBRAIN_WEBHOOK_URL = 'https://api.bugbrain.tech/webhooks/ci/...'
    BUGBRAIN_SECRET = credentials('bugbrain-webhook-secret')
    BUGBRAIN_API_KEY = credentials('bugbrain-api-key')
  }
 
  stages {
    stage('Build') {
      steps {
        echo 'Building application...'
        sh 'npm run build'
      }
    }
 
    stage('Deploy to Staging') {
      steps {
        echo 'Deploying to staging...'
        sh 'npm run deploy:staging'
      }
    }
 
    stage('Run BugBrain Tests') {
      steps {
        script {
          echo 'Triggering BugBrain tests...'
 
          // Trigger tests
          def response = sh(
            script: '''
              curl -s -X POST "$BUGBRAIN_WEBHOOK_URL" \
                -H "Content-Type: application/json" \
                -H "X-Bugbrain-Secret: $BUGBRAIN_SECRET" \
                -d '{"branch": "'$GIT_BRANCH'", "commit": "'$GIT_COMMIT'"}'
            ''',
            returnStdout: true
          ).trim()
 
          def executionId = sh(
            script: "echo '$response' | jq -r '.execution_id'",
            returnStdout: true
          ).trim()
 
          echo "Test execution started: $executionId"
          env.BUGBRAIN_EXECUTION_ID = executionId
 
          // Poll for results (max 15 minutes)
          timeout(time: 15, unit: 'MINUTES') {
            waitUntil {
              def status = sh(
                script: '''
                  curl -s "${BUGBRAIN_API_URL}/api/executions/${BUGBRAIN_EXECUTION_ID}/status" \
                    -H "Authorization: Bearer $BUGBRAIN_API_KEY"
                ''',
                returnStdout: true
              ).trim()
 
              def state = sh(
                script: "echo '$status' | jq -r '.status'",
                returnStdout: true
              ).trim()
 
              echo "Test status: $state"
              return state == 'completed' || state == 'failed'
            }
          }
 
          // Get final results
          def results = sh(
            script: '''
              curl -s "${BUGBRAIN_API_URL}/api/executions/${BUGBRAIN_EXECUTION_ID}/status" \
                -H "Authorization: Bearer $BUGBRAIN_API_KEY" | jq '.'
            ''',
            returnStdout: true
          ).trim()
 
          echo "Results: $results"
 
          def failedTests = sh(
            script: "echo '$results' | jq -r '.failed_tests'",
            returnStdout: true
          ).trim().toInteger()
 
          env.BUGBRAIN_FAILED_TESTS = failedTests
 
          if (failedTests > 0 && params.FAIL_ON_BUGS) {
            error("BugBrain tests failed: $failedTests failures")
          }
        }
      }
    }
  }
 
  post {
    always {
      script {
        // Archive BugBrain report
        sh '''
          curl -s "${BUGBRAIN_API_URL}/api/executions/${BUGBRAIN_EXECUTION_ID}/report" \
            -H "Authorization: Bearer $BUGBRAIN_API_KEY" > bugbrain-report.json || true
        '''
 
        archiveArtifacts artifacts: 'bugbrain-report.json', allowEmptyArchive: true
      }
    }
 
    success {
      echo "✓ BugBrain tests passed!"
    }
 
    failure {
      echo "✗ BugBrain tests failed!"
      // Send Slack notification, etc.
    }
  }
}

Scripted Pipeline Example

node {
  try {
    stage('Build') {
      sh 'npm run build'
    }
 
    stage('BugBrain Tests') {
      withCredentials([string(credentialsId: 'bugbrain-webhook-secret', variable: 'SECRET')]) {
        def response = sh(
          script: '''
            curl -s -X POST "$BUGBRAIN_WEBHOOK_URL" \
              -H "X-Bugbrain-Secret: $SECRET" \
              -d '{}'
          ''',
          returnStdout: true
        ).trim()
 
        def executionId = readJSON(text: response).execution_id
        echo "Started execution: $executionId"
      }
    }
 
  } catch (Exception e) {
    currentBuild.result = 'FAILURE'
    throw e
  }
}

Conditional Execution

Only Run on Main Branch

stage('BugBrain Tests') {
  when {
    branch 'main'
  }
  steps {
    sh 'curl -X POST "$BUGBRAIN_WEBHOOK_URL" ...'
  }
}

Only Run on Pull Requests

stage('BugBrain Tests') {
  when {
    changeRequest()
  }
  steps {
    sh 'curl -X POST "$BUGBRAIN_WEBHOOK_URL" ...'
  }
}

Only Run if Tests Changed

stage('BugBrain Tests') {
  when {
    changeset "test/**"
  }
  steps {
    sh 'curl -X POST "$BUGBRAIN_WEBHOOK_URL" ...'
  }
}

Advanced Features

Multiple Test Plans

Run different test plans based on branch:

stage('BugBrain Tests') {
  steps {
    script {
      def testPlanId = 'smoke-tests'
      if (env.GIT_BRANCH == 'origin/main') {
        testPlanId = 'full-tests'
      }
 
      sh '''
        curl -X POST "${BUGBRAIN_API_URL}/webhooks/ci/proj_id/${testPlanId}" \
          -H "X-Bugbrain-Secret: $BUGBRAIN_SECRET" \
          -d '{}'
      '''
    }
  }
}

Parallel Test Execution

stage('Parallel Tests') {
  parallel {
    stage('BugBrain Smoke') {
      steps {
        sh 'curl -X POST "$WEBHOOK_URL/smoke-tests" ...'
      }
    }
    stage('BugBrain Full') {
      steps {
        sh 'curl -X POST "$WEBHOOK_URL/full-tests" ...'
      }
    }
  }
}

Send Results to Slack

post {
  always {
    script {
      def status = currentBuild.result
      def color = status == 'SUCCESS' ? 'good' : 'danger'
 
      slackSend(
        color: color,
        message: "BugBrain Tests: ${status}\n" +
                 "Execution: ${env.BUGBRAIN_EXECUTION_ID}\n" +
                 "Failed Tests: ${env.BUGBRAIN_FAILED_TESTS}"
      )
    }
  }
}

Jenkins Plugins

Recommended Plugins

  • Pipeline Plugin — For declarative/scripted pipelines
  • Git Plugin — For git integration
  • Slack Notification Plugin — For Slack notifications
  • Email Extension Plugin — For email alerts

Install from: Manage Jenkins → Manage Plugins → Available

Environment Variables

Built-in Jenkins Variables

VariableDescription
$GIT_BRANCHBranch being built
$GIT_COMMITCommit hash
$BUILD_NUMBERJenkins build number
$WORKSPACEJob workspace directory
$BUILD_URLURL to build page
$BRANCH_NAMECurrent branch (Pipeline only)

Access Credentials Securely

Use withCredentials block:

withCredentials([
  string(credentialsId: 'bugbrain-webhook-secret', variable: 'SECRET'),
  string(credentialsId: 'bugbrain-api-key', variable: 'API_KEY')
]) {
  sh 'curl -X POST "$BUGBRAIN_WEBHOOK_URL" -H "X-Bugbrain-Secret: $SECRET" ...'
}

Troubleshooting

Tests Don’t Start

  1. Check webhook URL is correct:

    echo "Webhook URL: $BUGBRAIN_WEBHOOK_URL"

  2. Test webhook manually:

    curl -v -X POST "https://api.bugbrain.tech/webhooks/ci/..." \
  -H "X-Bugbrain-Secret: your-secret" \
  -d '{}'

  3. Check Jenkins logs:

    /var/log/jenkins/jenkins.log

Authentication Fails

  • Verify credentials are set in Jenkins
  • Check credential ID matches Jenkinsfile: credentials('bugbrain-webhook-secret')
  • Try creating new credential with simple ID like bugbrain-secret

Timeout During Polling

  • Increase timeout: timeout(time: 30, unit: 'MINUTES')
  • Check BugBrain status at status.bugbrain.tech
  • Verify API key is valid

Can’t Write BugBrain Report

Make sure job has write permissions:

post {
  always {
    sh 'mkdir -p reports && cd reports'
    // ... fetch and save report
  }
}

Example Jenkinsfile: See full working example at github.com/bugbrain/examples/jenkinsfile

GitLab CIOverview