> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stably.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# GitLab CI

> Integrate Stably tests into your GitLab CI/CD pipeline using our API with automatic polling for test completion.

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

<Steps>
  <Step title="Get API Key">
    Go to the [settings page](https://app.stably.ai/settings?tab=api-key) on the Web UI to get your API key.
  </Step>

  <Step title="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)
  </Step>

  <Step title="Configure Pipeline">
    Add the Stably test job to your `.gitlab-ci.yml` file.
  </Step>
</Steps>

## Basic Configuration

Add this to your `.gitlab-ci.yml`:

```yaml theme={null}
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](/api-reference/introduction).

## 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