GitLab Platform Guide
Overview
Karandash provides full support for GitLab, including gitlab.com and self-hosted GitLab instances.
Support level: Full
Capabilities: - Merge request fetching (title, commits, changes/diffs) - Comment posting on MRs (notes) - Auto-fix mutations (add/remove labels, set draft status) - GitLab CI auto-detection - SARIF output for GitLab SAST integration - CI/CD job token support
API used: GitLab REST API v4
Authentication Setup
Option 1: Personal Access Token
Use a PAT for local development or external CI systems.
Create a token:
- Go to User Settings > Access Tokens (or Preferences > Access Tokens in newer GitLab versions)
- Click Add new token
- Set a name (e.g., "karandash-validation")
- Set an expiration date
- Select scopes:
read_api-- read-only access (sufficient for validation without comment posting)api-- full API access (required for comment posting and auto-fix)- Click Create personal access token
- Copy the token immediately
Project access tokens (recommended for CI/CD):
- Go to Project > Settings > Access Tokens
- Create a token with
apiscope andReporterrole (minimum) - Use this token in CI/CD variables
Option 2: GitLab CI Job Token (CI_JOB_TOKEN)
In GitLab CI, the built-in CI_JOB_TOKEN is automatically available.
It has limited permissions scoped to the current project. Karandash uses it only when neither token nor
GITLAB_TOKEN is set, and sends it in the JOB-TOKEN header (GitLab rejects a job token in PRIVATE-TOKEN).
CI_JOB_TOKEN permissions: - Read access to the project - Read access to merge request metadata - Cannot post comments (use a project access token for that)
Token Access for projects using Karandash:
When a project uses the Karandash Docker image or CI templates via CI_JOB_TOKEN, the Karandash repository must allow that project's job token to access its resources (container registry, CI includes, etc.). By default, GitLab restricts cross-project CI_JOB_TOKEN access.
To configure this in the Karandash repository:
- Go to Settings > CI/CD > Token Access
- Under "Allow CI job tokens from the following projects", add the project(s) that will use Karandash
- Those projects'
CI_JOB_TOKENcan now pull images and access CI resources from the Karandash repo
Alternatively, disable "Limit access to this project" in the Karandash repo to allow any project's job token to access it (less secure, not recommended for production).
Without this configuration, projects using Karandash will fail with 403 Forbidden when their CI_JOB_TOKEN tries to access Karandash resources.
For comment posting in CI, store a project access token as a CI/CD variable:
- Go to Project > Settings > CI/CD > Variables
- Add
GITLAB_TOKENwith a project access token value - Mark as Masked and optionally Protected
Environment Variable Setup
# Required
export GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx"
# Optional: Self-hosted GitLab
export CI_SERVER_URL="https://gitlab.example.com"
# Optional: User token for approve/unapprove (PAT with api scope)
# Required when GITLAB_TOKEN is a project access token or CI_JOB_TOKEN,
# because GitLab approve/unapprove API requires a user-scoped token.
export GITLAB_APPROVE_TOKEN="glpat-yyyyyyyyyyyyyyyyyyyy"
In GitLab CI, the following variables are automatically available:
- CI_JOB_TOKEN -- job-scoped token
- CI_SERVER_URL -- GitLab instance URL
- CI_PROJECT_PATH -- project path (e.g., group/project)
- CI_MERGE_REQUEST_IID -- merge request internal ID
- CI_API_V4_URL -- API v4 base URL
Testing Authentication
export GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx"
karandash validate --pr https://gitlab.com/mygroup/myproject/-/merge_requests/1
A successful run prints validation results. An authentication failure produces:
Authentication failed for gitlab provider (HTTP 401).
Your token is invalid, expired, or revoked.
Hint: configure token via GITLAB_TOKEN or CI_JOB_TOKEN.
Verify your token at: Settings > Access Tokens.
Configuration
Environment Variables (Zero-Config)
export GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx"
karandash validate --pr https://gitlab.com/mygroup/myproject/-/merge_requests/42
Karandash uses GITLAB_TOKEN first, then falls back to CI_JOB_TOKEN. The base URL defaults to https://gitlab.com unless CI_SERVER_URL is set.
Configuration File (.karandash/config.yaml)
platforms:
gitlab:
url: "https://gitlab.com"
token: "${GITLAB_TOKEN}"
# Optional: user PAT for approve/unapprove (falls back to the GITLAB_APPROVE_TOKEN env var)
approve-token: "${GITLAB_APPROVE_TOKEN}"
# Optional: how stale inline comments are deleted. `discussion` (default) deletes through the discussion API,
# `note` deletes the marked MR notes directly.
delete-inline-strategy: discussion
rules:
title-format:
pattern: "^(feat|fix|chore|docs|refactor): .+"
min-length: 10
max-length: 120
commit-messages:
format: "conventional"
draft:
block-draft: fail
size-limits:
max-lines: 500
max-files: 30
approval:
min-approvals: 2
reporters:
console: true
markdown: true # Post results as MR note
URL Formats
# gitlab.com
https://gitlab.com/{group}/{project}/-/merge_requests/{iid}
# Self-hosted
https://gitlab.example.com/{group}/{project}/-/merge_requests/{iid}
# Nested groups
https://gitlab.com/{group}/{subgroup}/{project}/-/merge_requests/{iid}
Project identification: Full project path (e.g., mygroup/myproject or mygroup/subgroup/myproject)
Self-Hosted GitLab
# .karandash/config.yaml
platforms:
gitlab:
url: "https://gitlab.example.com"
token: "${GITLAB_TOKEN}"
Or via environment variables:
export CI_SERVER_URL="https://gitlab.example.com"
export GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx"
Features and Limitations
What Works
| Feature | Status | Notes |
|---|---|---|
| MR fetching | Yes | Title, description, source/target branches |
| Commit validation | Yes | All commits in the MR |
| Change detection | Yes | Full diffs via changes API |
| Approval checking | Yes | Approval count from MR metadata |
| Comment posting | Yes | Posts MR notes via Notes API |
| Comment updating | Yes | Finds and updates existing Karandash notes |
| Inline comments | Yes | Posts diff discussions via GitLab discussions API |
| Resolve inline comments | Yes | Resolves marked diff discussions |
| Label management (--fix) | Yes | Reads current labels, merges, and updates |
| Draft status (--fix) | Yes | Toggles "Draft: " title prefix |
| Title update (--fix) | Yes | Updates MR title |
| Description update (--fix) | Yes | Updates MR description |
| Approve / unapprove | Yes | Requires a user-scoped token (GITLAB_APPROVE_TOKEN) |
| CI auto-detection | Yes | Detects GITLAB_CI, CI_PROJECT_PATH, CI_MERGE_REQUEST_IID |
| SARIF output | Yes | Compatible with GitLab SAST artifacts |
What Does Not Work
| Feature | Reason |
|---|---|
| Pipeline triggering | Karandash reports results, does not trigger pipelines |
Platform-Specific Considerations
- CI_JOB_TOKEN limitations: Cannot post comments or modify MRs. Use a project access token stored as a CI/CD variable for full functionality.
- Rate limiting: GitLab.com allows 300 requests/minute for authenticated users. Karandash makes 3 API calls per MR validation (MR, commits, changes).
- Draft MRs: GitLab uses the "Draft: " title prefix convention. Karandash adds/removes this prefix when toggling draft status via
--fix. - Nested groups: Fully supported. The project path can include multiple group levels.
- API version: Karandash uses GitLab API v4. Minimum GitLab version: 12.0+.
Common Use Cases
GitLab CI Integration
Minimal setup (zero-config with CI_JOB_TOKEN):
# .gitlab-ci.yml
karandash:
stage: test
image: rinekri/karandash:latest
rules:
- if: $CI_MERGE_REQUEST_IID
script:
- karandash validate
variables:
GITLAB_TOKEN: $CI_JOB_TOKEN
With comment posting (requires project access token):
# .gitlab-ci.yml
karandash:
stage: test
image: rinekri/karandash:latest
rules:
- if: $CI_MERGE_REQUEST_IID
script:
- karandash validate
variables:
GITLAB_TOKEN: $KARANDASH_TOKEN # Project access token stored in CI/CD variables
With SARIF output for GitLab SAST:
# .gitlab-ci.yml
karandash:
stage: test
image: rinekri/karandash:latest
rules:
- if: $CI_MERGE_REQUEST_IID
script:
- karandash validate --format sarif --output gl-sast-report.json
artifacts:
reports:
sast: gl-sast-report.json
expire_in: 1 week
variables:
GITLAB_TOKEN: $CI_JOB_TOKEN
Results appear in the MR's Security widget.
Local MR Testing
export GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx"
# Validate a specific MR
karandash validate --pr https://gitlab.com/mygroup/myproject/-/merge_requests/42
# Self-hosted GitLab
karandash validate --pr https://gitlab.example.com/team/app/-/merge_requests/10
# With JSON output
karandash validate --pr https://gitlab.com/mygroup/myproject/-/merge_requests/42 \
--format json
# With auto-fix
karandash validate --pr https://gitlab.com/mygroup/myproject/-/merge_requests/42 \
--fix
Config Inheritance Across Repos
Host a shared base config and extend it per-repository:
# https://gitlab.com/mygroup/configs/-/raw/main/karandash-base.yaml
rules:
title-format:
pattern: "^(feat|fix|chore|docs): .+"
commit-messages:
format: "conventional"
security:
scan-for-secrets: true
# .karandash/config.yaml in each repository
extends: "https://gitlab.com/mygroup/configs/-/raw/main/karandash-base.yaml"
platforms:
gitlab:
url: "https://gitlab.com"
token: "${GITLAB_TOKEN}"
rules:
approval:
min-approvals: 2
Auto-Fix Support
GitLab supports auto-fix via --fix for safe, mechanical fixes:
# Apply fixes
karandash validate --pr https://gitlab.com/org/repo/-/merge_requests/5 --fix
# Supported fixes:
# - Add required labels (reads current labels, merges, updates)
# - Remove forbidden labels
# - Toggle draft status (adds/removes "Draft: " title prefix)
Auto-fix requires a token with api scope.
Troubleshooting
"401 Unauthorized"
Error: 401 Unauthorized
Causes: - Token is expired or revoked - Token does not have required scopes - CI_JOB_TOKEN used outside its project scope
Fix:
1. Verify the token: curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" "https://gitlab.com/api/v4/user"
2. Check token scopes (needs read_api minimum, api for comment posting)
3. If using CI_JOB_TOKEN, confirm the MR belongs to the same project
"404 Not Found" on MR Fetch
Error: 404 Not Found
Causes: - Wrong project path (check for typos, correct group nesting) - Token does not have access to the project - MR IID does not exist
Fix:
1. Verify the project path matches the URL: group/subgroup/project
2. Check that the token has access: curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" "https://gitlab.com/api/v4/projects/group%2Fproject"
3. URL-encode the project path when testing directly: group%2Fsubgroup%2Fproject
CI_JOB_TOKEN Cannot Access Karandash Resources (403)
Cause: The project's CI_JOB_TOKEN is blocked from accessing the Karandash repository (container registry, CI templates). GitLab restricts cross-project job token access by default.
Fix: 1. In the Karandash repository, go to Settings > CI/CD > Token Access 2. Under "Allow CI job tokens from the following projects", add the project that needs access 3. Alternatively, disable "Limit access to this project" in the Karandash repo (less secure)
CI_JOB_TOKEN Cannot Post Comments
Cause: CI_JOB_TOKEN has limited permissions and cannot create MR notes.
Fix:
1. Create a project access token with api scope
2. Store it as a CI/CD variable named KARANDASH_TOKEN
3. Use it in your pipeline:
variables:
GITLAB_TOKEN: $KARANDASH_TOKEN
"404 Not Found" on Approve/Unapprove
Error: GitLab API error: HTTP 404 Not Found (POST /projects/.../merge_requests/.../approve)
Cause: GitLab's approve/unapprove API requires a user-scoped token (Personal Access Token or OAuth token with api scope). Project access tokens and CI_JOB_TOKEN cannot approve MRs - GitLab returns 404 (not 403) as a security measure.
Fix:
1. Create a Personal Access Token with api scope (User Settings > Access Tokens)
2. Set it as GITLAB_APPROVE_TOKEN:
export GITLAB_APPROVE_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx"
Or in config:
platforms:
gitlab:
approve-token: "${GITLAB_APPROVE_TOKEN}"
The main GITLAB_TOKEN (project token) continues to be used for all other operations. The approve token is only used for approve/unapprove calls.
Self-Hosted GitLab -- SSL Certificate Errors
Fix for Docker:
docker run \
-v /path/to/ca-cert.pem:/usr/local/share/ca-certificates/ca.crt \
-e GITLAB_TOKEN=$GITLAB_TOKEN \
-e CI_SERVER_URL=https://gitlab.example.com \
rinekri/karandash:latest karandash validate
Fix for JAR:
java -Djavax.net.ssl.trustStore=/path/to/truststore.jks \
-jar karandash.jar validate
Rate Limiting (429)
Error: 429 Too Many Requests
Fix:
- GitLab.com: 300 requests/minute. Karandash uses ~3 calls per MR.
- Self-hosted: Check your instance rate limits in Admin > Settings > Network > User and IP rate limits
- Avoid running Karandash on every push; trigger only on merge_request_event
Edge Cases and Limitations
CI_JOB_TOKEN Expiration
Issue: CI_JOB_TOKEN works in the pipeline job but fails when used outside the pipeline context.
Root cause: CI_JOB_TOKEN is only valid during the job execution. It expires after the job completes, typically within seconds.
Workaround: - Only use CI_JOB_TOKEN during the pipeline job itself - For comment posting and auto-fix, store a project access token in CI/CD variables instead
Nested Group Path Resolution
Issue: Projects in deeply nested groups fail with "404 Not Found" when accessed via URL encoding.
Root cause: GitLab API requires URL encoding of forward slashes in project paths (e.g., group%2Fsubgroup%2Fproject), but Karandash auto-detects and handles this internally.
Expected behavior: Karandash correctly parses URLs like:
https://gitlab.com/team/backend/services/auth/-/merge_requests/42
If issues persist: Verify the project path exactly:
curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
"https://gitlab.com/api/v4/projects/team%2Fbackend%2Fservices%2Fauth"
Draft MR Prefix Edge Case
Issue: Using --fix to un-draft a MR with custom "Draft" text (not the default "Draft: ") does not remove the prefix.
Root cause: Karandash only recognizes the standard GitLab "Draft: " prefix. Custom draft indicators (e.g., "[DRAFT]", "WIP:") are not toggled.
Workaround: - Use the standard GitLab draft feature instead of custom prefixes, or - Manually set draft status in the MR UI before calling Karandash
Approval State Cache
Issue: MR shows as approved in the UI but validation fails with "insufficient approvals."
Root cause: Karandash queries the MR API at validation time. If an approval was just added, there may be a brief replication delay in GitLab's cache.
Expected behavior: Wait a few seconds after approving and retry validation.
Personal Access Token Scopes on Self-Hosted
Issue: A token with api scope still cannot post comments on self-hosted GitLab.
Root cause: Some self-hosted GitLab instances have additional permission restrictions or use custom authentication plugins.
Fix:
1. Verify the token user has at least Developer role on the project
2. Check Project Settings > Members for the token owner's permissions
3. Test the token directly: curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" "https://gitlab.example.com/api/v4/projects/{id}/merge_requests/{iid}/notes"
Project Access Token Expiration
Issue: Project access tokens expire silently, causing validation to fail with "401 Unauthorized" without warning.
Root cause: Project access tokens have configurable expiration dates. No notification is sent when they expire.
Fix: - Check token expiration in Project Settings > Access Tokens - Set long expiration dates (1 year or more) or regenerate regularly - Monitor CI/CD job logs for authentication failures
Rate Limiting with Multiple Projects
Issue: Validating MRs from multiple projects hits rate limits faster.
Root cause: GitLab applies rate limits per IP, not per token. If you validate 300+ MRs across different projects within 1 minute from the same IP, the limit is hit.
Mitigation: - Stagger MR validation across time, or - Use multiple tokens from different IP addresses (if possible), or - Request higher rate limits from GitLab.com support
API Version Mismatch
Issue: Self-hosted GitLab instance predates API v4 (very old instances).
Root cause: Karandash uses GitLab API v4. Instances older than GitLab 12.0 (released 2019) use API v3 or earlier.
Fix: Upgrade your GitLab instance, or use Karandash with a supported GitLab version (12.0+).
Large MR with Many Commits
Issue: Validation is slow or times out on MRs with >100 commits.
Root cause: Karandash fetches the full commit list for each MR. Very large commit histories require multiple API calls with pagination.
Expected behavior: Validation may take 10-30 seconds for very large MRs. This is normal.
Optimization: GitLab's API returns commits paginated (20 per page by default). Karandash handles pagination transparently.
MR with Force-Pushed Updates
Issue: Validation shows outdated commit information after a force-push.
Root cause: After a force-push, the MR's commit list changes. Karandash queries the current state, so it will reflect the new commits.
Expected behavior: Run validation again after force-pushing to see updated results.
Examples
Minimal GitLab CI Pipeline
karandash:
stage: test
image: rinekri/karandash:latest
rules:
- if: $CI_MERGE_REQUEST_IID
script:
- karandash validate
Full GitLab CI Pipeline with Comments and SARIF
stages:
- validate
karandash:
stage: validate
image: rinekri/karandash:latest
rules:
- if: $CI_MERGE_REQUEST_IID
script:
- karandash validate --format sarif --output gl-sast-report.json
artifacts:
reports:
sast: gl-sast-report.json
expire_in: 1 week
variables:
GITLAB_TOKEN: $KARANDASH_TOKEN
allow_failure: false
GitLab-Optimized Configuration
# .karandash/config.yaml
platforms:
gitlab:
url: "${CI_SERVER_URL:-https://gitlab.com}"
token: "${GITLAB_TOKEN}"
rules:
title-format:
pattern: "^(feat|fix|chore|docs|refactor|test|ci): .+"
min-length: 10
max-length: 120
commit-messages:
format: "conventional"
max-length: 100
branch-naming:
pattern: "^(feature|bugfix|hotfix|release)/[a-z0-9-]+$"
draft:
block-draft: fail
wip-patterns:
- "WIP"
- "\\[WIP\\]"
- "DRAFT"
size-limits:
max-files: 30
max-lines: 500
max-commits: 20
approval:
min-approvals: 2
labels:
required-labels:
- "workflow::review"
forbidden-labels:
- "workflow::wip"
- "do-not-merge"
security:
scan-for-secrets: true
sensitive-files:
- "**/.env"
- "**/*.pem"
- "**/*.key"
reporters:
console: true
markdown: true
Self-Hosted GitLab Enterprise Configuration
# .karandash/config.yaml
extends: "https://gitlab.corp.example.com/devops/configs/-/raw/main/base.yaml"
platforms:
gitlab:
url: "https://gitlab.corp.example.com"
token: "${GITLAB_TOKEN}"
rules:
title-format:
pattern: "^\\[JIRA-\\d+\\] (feat|fix|chore): .+"
require-ticket: true
jira-ticket:
project-keys:
- "PROJ"
- "INFRA"
approval:
min-approvals: 3
required-approvers:
- "tech-lead"
- "security-team"
reporters:
console: true
markdown: true