Skip to main content
Integrate Stably tests into your GitLab CI/CD pipeline using our API. Configure your .gitlab-ci.yml to trigger tests and poll for completion automatically.

​
Setup Instructions

1

Get API Key

Go to the settings page on the Web UI to get your API key.
2

Set Environment Variables

In your GitLab project, go to “Settings” > “CI/CD” > “Variables” and add:
  • TEST_SUITE_ID: Your Stably test suite ID
  • STABLY_API_KEY: Your Stably API key (mark as protected and masked)
3

Configure Pipeline

Add the Stably test job to your .gitlab-ci.yml file.

​
Basic Configuration

Add this to your .gitlab-ci.yml: 
stages:
  - test

stably_tests:
  stage: test
  image: alpine:latest
  before_script:
    - apk add --no-cache curl jq
  script:
    - |
      # Trigger test run
      RESPONSE=$(curl -s -X POST \
        "https://api.stably.ai/v1/testSuite/$TEST_SUITE_ID/run" \
        -H "Authorization: Bearer $STABLY_API_KEY" \
        -H "accept: application/json")
      
      TEST_SUITE_RUN_ID=$(echo $RESPONSE | jq -r '.testSuiteRunId')
      
      # Poll for completion
      while true; do
        STATUS=$(curl -s -X GET \
          "https://api.stably.ai/v1/testSuiteRun/$TEST_SUITE_RUN_ID/status" \
          -H "Authorization: Bearer $STABLY_API_KEY" | jq -r '.status')
        
        if [ "$STATUS" = "FINISHED" ]; then
          echo "Test run completed"
          
          # Fetch test results to check if tests passed
          RESULTS=$(curl -s -X GET \
            "https://api.stably.ai/v1/testSuiteRun/$TEST_SUITE_RUN_ID/result" \
            -H "Authorization: Bearer $STABLY_API_KEY")
          
          # Check if all tests passed or are flaky
          ALL_PASSED=$(echo $RESULTS | jq '.results | all(.status == "PASSED" or .status == "FLAKY")')
          
          if [ "$ALL_PASSED" = "true" ]; then
            echo "✅ All tests passed successfully"
            exit 0
          else
            echo "❌ Some tests failed"
            echo $RESULTS | jq '.results[] | select(.status != "PASSED" and .status != "FLAKY") | {testName, status}'
            exit 1
          fi
        fi
        
        sleep 30
      done
  variables:
    TEST_SUITE_ID: "your-suite-id"
  secrets:
    STABLY_API_KEY:
      vault: stably-api-key

​
Environment Variables

Set these variables in your GitLab project (Settings > CI/CD > Variables):
  • TEST_SUITE_ID: Your Stably test suite ID
  • STABLY_API_KEY: Your Stably API key (store as CI/CD variable, mark as protected and masked)
For multiple test suites, you can create additional variables:
  • SMOKE_TEST_SUITE_ID: ID for smoke tests
  • REGRESSION_TEST_SUITE_ID: ID for regression tests

​
API Documentation

For complete API reference, including all available endpoints, request/response schemas, and examples, visit our API Documentation.

​
Best Practices

  • Use secrets: Store your API key as a GitLab CI/CD variable marked as “protected” and “masked”
  • Set timeouts: Add appropriate timeouts to prevent jobs from running indefinitely
  • Handle errors: Include proper error handling in your scripts
  • Parallel execution: Run multiple test suites in parallel for faster feedback
  • Conditional execution: Use GitLab’s rules to run tests only when needed