GitLab CI

This guide walks you through setting up Spekra in your GitLab CI/CD pipeline.

Prerequisites

• A GitLab repository with Playwright or Jest tests
• A Spekra account and API key

Setup Steps

1. Add Your API Key as a Variable

1. Go to your project in GitLab
2. Navigate to Settings → CI/CD → Variables
3. Click Add variable
4. Key: SPEKRA_API_KEY
5. Value: Your Spekra API key
6. Check Mask variable (recommended)
7. Click Add variable

2. Update Your Pipeline

Add the Spekra environment variable to your test job:

stages:
  - test

test:
  stage: test
  image: mcr.microsoft.com/playwright:v1.40.0-jammy
  script:
    - npm ci
    - npx playwright test
  variables:
    SPEKRA_API_KEY: $SPEKRA_API_KEY

Full Example

Here's a complete pipeline configuration:

stages:
  - test

variables:
  npm_config_cache: "$CI_PROJECT_DIR/.npm"

cache:
  key: "${CI_COMMIT_REF_SLUG}"
  paths:
    - .npm/
    - node_modules/

test:
  stage: test
  image: mcr.microsoft.com/playwright:v1.40.0-jammy
  script:
    - npm ci --cache .npm --prefer-offline
    - npx playwright test
  variables:
    SPEKRA_API_KEY: $SPEKRA_API_KEY
  artifacts:
    when: always
    paths:
      - playwright-report/
    expire_in: 7 days
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Parallel Testing

For large test suites, use GitLab's parallel feature:

test:
  stage: test
  image: mcr.microsoft.com/playwright:v1.40.0-jammy
  parallel: 4
  script:
    - npm ci
    - npx playwright test --shard=$CI_NODE_INDEX/$CI_NODE_TOTAL
  variables:
    SPEKRA_API_KEY: $SPEKRA_API_KEY

Protected Variables

For additional security, mark your API key as protected:

1. Go to Settings → CI/CD → Variables
2. Edit the SPEKRA_API_KEY variable
3. Check Protect variable

Protected variables are only available to protected branches and tags.

Different Environments

Use GitLab environments for different API keys:

test:staging:
  stage: test
  environment: staging
  script:
    - npx playwright test
  variables:
    SPEKRA_API_KEY: $SPEKRA_STAGING_API_KEY

test:production:
  stage: test
  environment: production
  script:
    - npx playwright test
  variables:
    SPEKRA_API_KEY: $SPEKRA_PROD_API_KEY
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Captured Metadata

The reporter automatically captures from GitLab CI:

Merge Request Pipelines

For merge request pipelines, additional metadata is captured:

Troubleshooting

Variable Not Available

• Check the variable is not protected (or the branch is protected)
• Verify the variable name matches exactly
• For merge requests from forks, variables may not be available

Results Not Appearing

• Check pipeline logs for errors
• Enable debug: add SPEKRA_DEBUG: "true" to variables
• Verify network access to spekra.dev

Masked Variable Issues

If the masked variable isn't working:

• Ensure the value is at least 8 characters
• The value can only appear in logs as [MASKED]
• If you see the key in logs, it wasn't properly masked

Self-Hosted GitLab

If using self-hosted GitLab, ensure:

• Outbound network access to spekra.dev is allowed
• SSL certificates are properly configured
• The runner has network access

Next Steps

• GitHub Actions setup
• Troubleshooting
• API Reference