Integrate with GitLab

Integrate with GitLab

GitLab Setup

Complete guide for configuring Fluid Attacks' MR/PR scanner with GitLab CI/CD pipelines.

Overview

This guide covers the setup process for integrating Smells security analysis into GitLab CI/CD pipelines, including token creation, variable configuration, and pipeline examples.

Prerequisites

  • GitLab project with appropriate permissions
  • Repository with merge request workflow
  • Access to create Personal Access Tokens or Project Access Tokens

Access Token Creation

Project Access Token

  1. Navigate to Project Settings → Access Token
  2. Click Add new token
  3. Configure the token
    1. Token name: Fluid Attacks Security Analysis 
    2. Expiration date: Set appropriate expiration
    3. Select scopes:

Required Scopes

ScopePurpose
apiComplete access to GitLab API
read_repositoryRead repository content

Step 2: Copy Token

  1. Click Create project access token
  2. Immediately copy the generated token
  3. Store securely - it won't be shown again
  4. Token format: glpat-xxxxxxxxxxxxxxxxxxxx

Variable Configuration

Required Variables

Configure these variables in your GitLab project:

Manual Variables (Protected)

Variable NameDescriptionType
FLUIDATTACKS_JWTJWT token for Fluid Attacks APIMasked
GITLAB_TOKENPersonal/Project Access TokenMasked

Automatic Variables (System)

These are automatically provided by GitLab CI:

Variable NameDescriptionAuto-Populated
CI_MERGE_REQUEST_PROJECT_IDProject ID✅ (MR pipelines only)
CI_MERGE_REQUEST_IIDMerge request IID✅ (MR pipelines only)

Variable Setup Methods

Option 1: Project Variables (Recommended)

  1. Navigate to Settings → CI/CD → Variables
  2. Click Add variable for each required variable:
Key: FLUIDATTACKS_JWT
Value: [your-jwt-token]
Flags: ✅ Expand variable reference, ✅ Mask variable

Key: GITLAB_TOKEN
Value: [your-gitlab-token]
Flags: ✅ Expand variable reference, ✅ Mask variable

Option 2: Group Variables

For multiple projects:

  1. Navigate to Group → Settings → CI/CD → Variables
  2. Add the same variables as above
  3. All projects in the group will inherit these variables

Pipeline Configuration

Basic Pipeline

# .gitlab-ci.yml
stages:
  - security

variables:
  DOCKER_IMAGE: "fluidattacks/smells:latest"

smells-analysis:
  stage: security
  image: $DOCKER_IMAGE
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  script:
    - smells-pipeline
  variables:
    FLUIDATTACKS_JWT: $FLUIDATTACKS_JWT
    GITLAB_TOKEN: $GITLAB_TOKEN

Permissions and Security

Required Permissions

Your GitLab user/token needs:

  • Developer role minimum on the project
  • Access to merge requests
  • API access permissions

Token Security Best Practices

  • Use Project Access Tokens when possible
  • Set short expiration periods (30-90 days)
  • Regularly rotate tokens
  • Monitor token usage in audit logs
  • Use service accounts for production
  • Always mark tokens as Masked and Protected

Troubleshooting

Common Issues

1. Token Permission Errors

Error: Invalid GitLab token or insufficient permissions

Solutions:

  • Verify token has api scope
  • Check token hasn't expired
  • Ensure user has Developer+ role on project
  • Verify token is for the correct GitLab instance

2. Missing Merge Request Context

Error: Neither GitLab nor Azure DevOps environment variables found

Solutions:

  • Ensure pipeline runs on merge request events only
  • Check rules configuration includes merge_request_event
  • Verify merge request is properly created

3. Variable Masking Issues

Error: Variable is masked but value is visible

Solutions:

  • Ensure variable value meets masking requirements (8+ chars)
  • Use Base64 encoding for complex values
  • Check variable is marked as both Protected and Masked
Idea
There is also a guide to integrate with Azure DevOps.