Configuration Reference

Complete reference for all configuration options available in the GitLab CI/CD integration.

CI/CD Variables

Configure these variables in Settings → CI/CD → Variables in your GitLab project.

Required Variables

Security: Always mark SCAN_PROFILE_TOKEN as Masked to prevent exposure in logs. Find this token in the Detectify platform under your scan profile settings.

Optional Variables

These can be set in CI/CD Variables or overridden in .gitlab-ci.yml:

Pipeline Configuration

Job Timeout

The GitLab job timeout should be set higher than POLL_TIMEOUT to allow the scan to complete:

security-scan:
  timeout: 5h  # Must be > POLL_TIMEOUT

When to Run

By default, the scan runs on merge requests and pushes to the default branch. Customize with GitLab rules:

rules:
  # Run on merge requests
  - if: $CI_PIPELINE_SOURCE == "merge_request_event"
 
  # Run on pushes to main/master
  - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
 
  # Allow manual trigger
  - if: $CI_PIPELINE_SOURCE == "web"
    when: manual

Common Configurations

Run Only on Merge Requests

rules:
  - if: $CI_PIPELINE_SOURCE == "merge_request_event"

Manual Trigger Only

rules:
  - when: manual

Scheduled Scans

First, create a schedule in CI/CD → Schedules, then:

rules:
  - if: $CI_PIPELINE_SOURCE == "schedule"

Non-Blocking Scans

Allow the pipeline to continue even if guardrails fail:

security-scan:
  allow_failure: true

Environment-Specific Configuration

Using GitLab Environments

Run different scans for different environments:

security-scan-staging:
  extends: .security-scan-base
  environment: staging
  variables:
    SCANNER_API_URL: $STAGING_SCANNER_URL
    SCAN_PROFILE_TOKEN: $STAGING_SCAN_TOKEN
  rules:
    - if: $CI_COMMIT_BRANCH == "staging"
 
security-scan-production:
  extends: .security-scan-base
  environment: production
  variables:
    SCANNER_API_URL: $PRODUCTION_SCANNER_URL
    SCAN_PROFILE_TOKEN: $PRODUCTION_SCAN_TOKEN
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Group-Level Variables

For organizations with multiple projects, set variables at the group level:

1. Go to your GitLab group
2. Navigate to Settings → CI/CD → Variables
3. Add SCANNER_API_URL (can be shared across projects)
4. Add project-specific SCAN_PROFILE_TOKEN in each project

Artifacts Configuration

Default Artifacts

artifacts:
  when: always           # Save even on failure
  paths:
    - scan-results.json  # Full results
    - scan-id.txt        # Scan reference ID
    - scan-status.json   # Status on failure
  expire_in: 30 days     # Retention period

Extended Retention for Compliance

artifacts:
  expire_in: 1 year

Disable Artifacts

artifacts: {}

Integrating with Existing Pipelines

Adding to Multi-Stage Pipelines

stages:
  - build
  - test
  - security-scan    # Add security stage
  - deploy
 
# Your existing jobs...
 
security-scan:
  stage: security-scan
  # ... security scan configuration
  needs: ["build"]   # Run after build completes

Using Include

Store the security scan configuration in a shared repository:

# In your project's .gitlab-ci.yml
include:
  - project: 'security/gitlab-templates'
    ref: main
    file: '/templates/detectify-scan.yml'
 
# Override variables as needed
variables:
  SCAN_PROFILE_TOKEN: $MY_PROJECT_TOKEN

Troubleshooting

Scanner Not Reachable

If you see Scanner API is not reachable:

1. Verify SCANNER_API_URL is correct
2. Check network connectivity from GitLab runners to your scanner
3. Ensure the scanner service is running

Scan Timeout

If scans consistently timeout:

1. Increase POLL_TIMEOUT value
2. Increase job timeout accordingly
3. Check if the target application is responding

Variable Not Set Errors

Ensure variables are:

• Spelled correctly (case-sensitive)
• Not marked as “Protected” if running on unprotected branches
• Available to the correct environment