GitLab CI Integration

Integrate BugBrain tests into your GitLab CI/CD pipelines to automatically run tests on every commit and merge request.

Quick Start

Step 1: Generate CI/CD Token

In BugBrain, go to Settings → CI/CD Integration
Click Generate Token and copy:
- Webhook URL
- Webhook Secret
- Test Plan ID

Step 2: Add GitLab Variables

In your GitLab project:

Go to Settings → CI/CD → Variables
Add three variables:

Variable Name	Value	Protected
`BUGBRAIN_WEBHOOK_URL`	Paste webhook URL	Yes
`BUGBRAIN_WEBHOOK_SECRET`	Paste webhook secret	Yes
`BUGBRAIN_TEST_PLAN_ID`	Paste test plan ID	Yes

Mark all as “Protected” so they only appear in protected branches.

Step 3: Add Pipeline Stage

Create or update .gitlab-ci.yml:

# .gitlab-ci.yml
 
stages:
  - build
  - test
  - bugbrain
  - deploy
 
# Your existing stages...
 
# BugBrain integration
run_bugbrain_tests:
  stage: bugbrain
  script:
    - |
      curl -X POST "$BUGBRAIN_WEBHOOK_URL" \
        -H "Content-Type: application/json" \
        -H "X-Bugbrain-Secret: $BUGBRAIN_WEBHOOK_SECRET" \
        -d '{
          "test_plan_id": "'$BUGBRAIN_TEST_PLAN_ID'",
          "branch": "'$CI_COMMIT_BRANCH'",
          "commit_sha": "'$CI_COMMIT_SHA'",
          "merge_request_iid": "'$CI_MERGE_REQUEST_IID'"
        }'
  only:
    - merge_requests
    - main
    - develop

Step 4: Commit and Push

git add .gitlab-ci.yml
git commit -m "Add BugBrain CI/CD integration"
git push origin feature-branch

Tests will run automatically on the next push or merge request!

Pipeline Configuration

Trigger on Merge Requests Only

run_bugbrain_tests:
  stage: bugbrain
  script:
    - curl -X POST "$BUGBRAIN_WEBHOOK_URL" ...
  only:
    - merge_requests

Trigger on Specific Branches

run_bugbrain_tests:
  stage: bugbrain
  script:
    - curl -X POST "$BUGBRAIN_WEBHOOK_URL" ...
  only:
    - main
    - develop
    - /^release\/.*$/  # Release branches

Trigger on Tags

run_bugbrain_tests:
  stage: bugbrain
  script:
    - curl -X POST "$BUGBRAIN_WEBHOOK_URL" ...
  only:
    - tags

Advanced Configuration

Polling for Results

For synchronous execution (wait for results in pipeline):

run_bugbrain_tests:
  stage: bugbrain
  script:
    # Trigger test execution
    - |
      RESPONSE=$(curl -s -X POST "$BUGBRAIN_WEBHOOK_URL" \
        -H "Content-Type: application/json" \
        -H "X-Bugbrain-Secret: $BUGBRAIN_WEBHOOK_SECRET" \
        -d '{}')
 
    - EXECUTION_ID=$(echo $RESPONSE | jq -r '.execution_id')
    - echo "Test execution started: $EXECUTION_ID"
 
    # Poll for results (max 10 minutes)
    - |
      for i in {1..120}; do
        STATUS=$(curl -s "https://api.bugbrain.tech/api/executions/$EXECUTION_ID/status" \
          -H "Authorization: Bearer $BUGBRAIN_TOKEN")
 
        STATE=$(echo $STATUS | jq -r '.status')
        if [ "$STATE" = "completed" ] || [ "$STATE" = "failed" ]; then
          break
        fi
        sleep 5
      done
 
    # Check results
    - |
      FAILED=$(echo $STATUS | jq -r '.failed_tests')
      if [ "$FAILED" -gt 0 ]; then
        echo "Tests failed: $FAILED failures"
        exit 1
      fi
  allow_failure: false

Conditional Execution

Only run tests on feature branches:

run_bugbrain_tests:
  stage: bugbrain
  script:
    - curl -X POST "$BUGBRAIN_WEBHOOK_URL" ...
  only:
    - branches
  except:
    - main

Only run on main/develop:

run_bugbrain_tests:
  stage: bugbrain
  script:
    - curl -X POST "$BUGBRAIN_WEBHOOK_URL" ...
  only:
    variables:
      - $CI_COMMIT_BRANCH == "main" || $CI_COMMIT_BRANCH == "develop"

Parallel Jobs

Run different test plans in parallel:

bugbrain_smoke_tests:
  stage: bugbrain
  script:
    - |
      curl -X POST "https://api.bugbrain.tech/webhooks/ci/$PROJECT_ID/$SMOKE_TEST_PLAN" \
        -H "X-Bugbrain-Secret: $BUGBRAIN_WEBHOOK_SECRET" -d '{}'
 
bugbrain_full_tests:
  stage: bugbrain
  script:
    - |
      curl -X POST "https://api.bugbrain.tech/webhooks/ci/$PROJECT_ID/$FULL_TEST_PLAN" \
        -H "X-Bugbrain-Secret: $BUGBRAIN_WEBHOOK_SECRET" -d '{}'

Pass Build Variables

Send git/MR information to BugBrain:

run_bugbrain_tests:
  stage: bugbrain
  script:
    - |
      curl -X POST "$BUGBRAIN_WEBHOOK_URL" \
        -H "Content-Type: application/json" \
        -H "X-Bugbrain-Secret: $BUGBRAIN_WEBHOOK_SECRET" \
        -d '{
          "branch": "'$CI_COMMIT_BRANCH'",
          "commit_sha": "'$CI_COMMIT_SHA'",
          "commit_message": "'$CI_COMMIT_MESSAGE'",
          "merge_request_iid": "'$CI_MERGE_REQUEST_IID'",
          "pipeline_id": "'$CI_PIPELINE_ID'",
          "user": "'$GITLAB_USER_LOGIN'"
        }'

Using GitLab Variables

Available CI/CD Variables

These are automatically available in GitLab pipelines:

Variable	Description
`$CI_COMMIT_BRANCH`	Branch being built
`$CI_COMMIT_SHA`	Commit hash
`$CI_COMMIT_MESSAGE`	Commit message
`$CI_PIPELINE_ID`	Pipeline ID
`$CI_MERGE_REQUEST_IID`	Merge request ID
`$GITLAB_USER_LOGIN`	User who triggered pipeline

Custom Variables

Define custom variables in .gitlab-ci.yml:

variables:
  ENVIRONMENT: staging
  TEST_TIMEOUT: "600"
 
run_bugbrain_tests:
  script:
    - echo "Environment: $ENVIRONMENT"
    - curl -X POST "$BUGBRAIN_WEBHOOK_URL" ...

Merge Request Integration

Show Test Results in MR

Add a comment script to post results on merge request:

run_bugbrain_tests:
  stage: bugbrain
  script:
    # Run tests...
    - |
      curl -X POST "$BUGBRAIN_WEBHOOK_URL" \
        -H "X-Bugbrain-Secret: $BUGBRAIN_WEBHOOK_SECRET" \
        -d '{}' > response.json
 
    - EXECUTION_ID=$(jq -r '.execution_id' response.json)
 
    # Post result comment (optional)
    - |
      curl -X POST \
        "https://gitlab.com/api/v4/projects/$CI_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID/notes" \
        -H "PRIVATE-TOKEN: $CI_JOB_TOKEN" \
        -d '{"body":"🤖 BugBrain tests running: https://app.bugbrain.tech/executions/'$EXECUTION_ID'"}'

Status Badge

Add a badge showing test status to your README:

[![BugBrain Tests](https://api.bugbrain.tech/badge/project/YOUR_PROJECT_ID/YOUR_TEST_PLAN_ID)](https://app.bugbrain.tech/projects/YOUR_PROJECT_ID)

Troubleshooting

Tests Not Running

Check variables are set correctly:

echo $BUGBRAIN_WEBHOOK_URL
echo $BUGBRAIN_WEBHOOK_SECRET

Verify .gitlab-ci.yml syntax:

# In GitLab UI: CI/CD → Pipelines → Lint

Check pipeline is running:
- Go to CI/CD → Pipelines
- Look for your branch
- Check “bugbrain” stage status

Webhook Fails with 401

Token expired: Generate new token
Secret doesn’t match: Re-copy from BugBrain Settings
Check webhook logs in BugBrain: Settings → Webhooks → Recent Requests

Tests Timeout

Increase polling timeout: Change sleep 5 to sleep 10 in polling script
Check BugBrain is responding: Visit status.bugbrain.tech
Upgrade plan for higher quota

Can’t Access Project Variables

Ensure you have “Maintainer” or “Owner” role
Variables only accessible in protected pipelines
Check “Protected” checkbox when creating variables

Example Repository

See a complete .gitlab-ci.yml example at github.com/bugbrain/examples/gitlab-ci-integration

GitHub Actions Jenkins