Gerrit Platform Guide
Overview
Karandash provides standard support for Gerrit Code Review instances.
Support level: Standard
Capabilities: - Change fetching (subject, current revision, commits) - Zero-config mode via environment variables - URL-based change validation - Support for modern Gerrit URL format
Not available: - CI auto-detection (no standard Gerrit CI environment variables) - SARIF upload
API used: Gerrit REST API
Authentication Setup
Option 1: HTTP Password
Gerrit authenticates REST calls with HTTP Basic username:http-password. When both username (or GERRIT_USERNAME) and token (or GERRIT_TOKEN, the HTTP password) are set, Karandash sends every call to the authenticated /a/ path with a Basic Authorization header. A token without a username logs a warning and falls back to anonymous access.
Generate an HTTP password:
- Log in to your Gerrit instance
- Go to Settings > HTTP Credentials (or Settings > HTTP Password)
- Click Generate Password (or Generate New Password)
- Copy the generated password
The HTTP password is different from your SSH key or login password.
Option 2: Token-Based Authentication
Some Gerrit instances support token-based authentication (e.g., via plugins).
Note: Gerrit's authentication model varies by instance. Check your instance's documentation for the exact authentication method supported.
Option 3: Anonymous Access
For public Gerrit instances (e.g., Gerrit Code Review for open-source projects), token-based auth may not be required. Karandash supports connecting without a token:
export GERRIT_URL="https://gerrit-review.googlesource.com"
# No GERRIT_TOKEN needed for public instances
karandash validate --pr https://gerrit-review.googlesource.com/c/project/+/12345
Environment Variable Setup
# Required
export GERRIT_URL="https://gerrit.example.com"
# Optional (not needed for public instances)
export GERRIT_USERNAME="your-gerrit-username"
export GERRIT_TOKEN="your-http-password"
Testing Authentication
export GERRIT_URL="https://gerrit.example.com"
export GERRIT_USERNAME="your-gerrit-username"
export GERRIT_TOKEN="your-http-password"
karandash validate --pr https://gerrit.example.com/c/myproject/+/12345
A successful run prints validation results. An authentication failure produces:
Authentication failed for gerrit provider (HTTP 401).
Your token is invalid, expired, or revoked.
Hint: configure token via GERRIT_TOKEN.
Configuration
Environment Variables (Zero-Config)
export GERRIT_URL="https://gerrit.example.com"
export GERRIT_USERNAME="your-gerrit-username"
export GERRIT_TOKEN="your-http-password"
karandash validate --pr https://gerrit.example.com/c/myproject/+/12345
Configuration File (.karandash/config.yaml)
platforms:
gerrit:
url: "https://gerrit.example.com"
username: "${GERRIT_USERNAME}"
token: "${GERRIT_TOKEN}"
notify: OWNER # who Gerrit emails about the review: NONE, OWNER (default), OWNER_REVIEWERS, ALL
rules:
title-format:
pattern: "^[A-Z].+"
min-length: 10
max-length: 72
commit-messages:
format: "conventional"
size-limits:
max-lines: 500
max-files: 30
security:
scan-for-secrets: true
reporters:
console: true
URL Formats
# Modern Gerrit URL format (supported)
https://gerrit.example.com/c/{project}/+/{change-id}
https://gerrit.example.com/c/{project}/+/{change-id}/{patchset}
# Legacy format (NOT supported -- requires project name)
https://gerrit.example.com/#{change-number}
Project identification: Project path (e.g., myproject or team/myproject)
Important: The legacy hash-based URL format (/#/change-number) is not supported. Use the modern /c/{project}/+/{change-id} format.
Gerrit-Specific Terminology
| Gerrit Term | Karandash Equivalent |
|---|---|
| Change | Merge Request / Pull Request |
| Patchset | Revision / Update |
| Subject | Title |
| Change-Id | MR ID |
Features and Limitations
What Works
| Feature | Status | Notes |
|---|---|---|
| Change fetching | Yes | Subject, status, current revision |
| Commit validation | Yes | Commits from current revision |
| Comment posting | Yes | Posts review messages via Gerrit review API |
| Comment updating | Yes | Posts a new review message (Gerrit has no edit) |
| Inline comments | Yes | Inline comments and the summary go in one review (tag: autogenerated:karandash, duplicates omitted), so Gerrit sends one email |
| Label management (--fix) | Yes | Implemented via Gerrit hashtags |
| Draft status (--fix) | Yes | Sets or clears Work-In-Progress flag; already in that state (409) is a no-op |
| Title update (--fix) | Yes | Updates change subject |
| Description update (--fix) | Yes | Rewrites the commit message body; subject and Change-Id footer are kept |
| Approve / unapprove | Yes | Sets or clears Code-Review +2 vote |
| Zero-config mode | Yes | Via GERRIT_URL + optional GERRIT_TOKEN |
| URL parsing | Yes | Modern /c/{project}/+/{id} format |
| Public instances | Yes | Token is optional for public Gerrit |
What Does Not Work
| Feature | Reason |
|---|---|
| CI auto-detection | No standard Gerrit CI environment variables |
| Review scores | Karandash does not set Code-Review or Verified labels |
| Legacy URLs | /#/change-number format not supported |
| File change detection | Limited; depends on Gerrit API revision details |
| File blame | Gerrit REST has blame only per change revision (/changes/{id}/revisions/{rev}/files/{file}/blame), not for a file at a branch or commit; fetchFileBlame returns the SDK's empty result |
Platform-Specific Considerations
- Gerrit is always self-hosted. There is no hosted Gerrit service. You must always provide
GERRIT_URL. - Single-commit model: Gerrit traditionally follows one commit per change. Karandash validates commits from the current revision.
- Authentication varies: HTTP passwords, OAuth, LDAP, or custom plugins. Check your instance's authentication setup.
- XSRF protection: Gerrit REST API prefixes responses with
)]}'\nto prevent XSRF. Karandash handles this automatically. - Rate limiting: Gerrit instances typically do not impose API rate limits, but large installations may have custom throttling. Gerrit's REST API does not expose quota state, so
karandash doctorreports no remaining rate limit.
Common Use Cases
Local Change Testing
export GERRIT_URL="https://gerrit.example.com"
export GERRIT_USERNAME="your-gerrit-username"
export GERRIT_TOKEN="your-http-password"
# Validate a specific change
karandash validate --pr https://gerrit.example.com/c/myproject/+/12345
# JSON output
karandash validate --pr https://gerrit.example.com/c/myproject/+/12345 \
--format json
Jenkins Integration (Common Gerrit CI)
Jenkins with the Gerrit Trigger plugin is the most common CI setup for Gerrit.
// Jenkinsfile
pipeline {
agent any
environment {
GERRIT_URL = 'https://gerrit.example.com'
GERRIT_TOKEN = credentials('gerrit-http-password')
}
stages {
stage('Validate Change') {
steps {
sh '''
karandash validate \
--platform gerrit \
--project "${GERRIT_PROJECT}" \
--mr-id "${GERRIT_CHANGE_NUMBER}"
'''
}
}
}
}
Common Gerrit Trigger environment variables:
| Variable | Description |
|---|---|
GERRIT_CHANGE_NUMBER |
Change number |
GERRIT_PROJECT |
Project name |
GERRIT_PATCHSET_NUMBER |
Patchset number |
GERRIT_CHANGE_URL |
Full change URL |
Zuul CI Integration
Zuul is another common CI system for Gerrit:
# .zuul.yaml
- job:
name: karandash-validate
run: playbooks/karandash.yaml
- project:
check:
jobs:
- karandash-validate
# playbooks/karandash.yaml
- hosts: all
tasks:
- name: Run Karandash validation
shell: |
export GERRIT_URL="{{ zuul.executor.src_root }}"
karandash validate \
--platform gerrit \
--project "{{ zuul.project.name }}" \
--mr-id "{{ zuul.change }}"
Google-Hosted Gerrit (googlesource.com)
For open-source projects hosted on googlesource.com:
# No token needed for public repos
export GERRIT_URL="https://gerrit-review.googlesource.com"
karandash validate --pr https://gerrit-review.googlesource.com/c/gerrit/+/12345
Troubleshooting
"401 Unauthorized"
Error: 401 Unauthorized
Causes: - HTTP password is expired or incorrect - Token format is wrong (not the HTTP password) - Instance requires a different authentication method
Fix:
1. Regenerate the HTTP password in Gerrit Settings
2. Verify the password works: curl -u "username:$GERRIT_TOKEN" "https://gerrit.example.com/a/changes/?q=status:open&n=1"
3. Check if your instance uses a different auth mechanism
"404 Not Found"
Causes: - Wrong project name or change ID - Change is in a different Gerrit instance - Project path is incorrect
Fix: 1. Verify the change exists in the Gerrit UI 2. Check the project path matches exactly (case-sensitive) 3. Confirm the GERRIT_URL points to the correct instance
Legacy URL Format Not Supported
Error: Legacy Gerrit URL format requires project name.
Use format: /c/{project}/+/{change-id}
Cause: Using the old /#/change-number URL format.
Fix: Use the modern URL format:
# Instead of:
https://gerrit.example.com/#/c/12345
# Use:
https://gerrit.example.com/c/project-name/+/12345
Find the modern URL by opening the change in Gerrit's web UI.
SSL Certificate Errors
Cause: Self-signed certificates on internal Gerrit instances.
Fix:
# For JAR
java -Djavax.net.ssl.trustStore=/path/to/truststore.jks \
-jar karandash.jar validate
# For Docker
docker run \
-v /path/to/ca-cert.pem:/usr/local/share/ca-certificates/ca.crt \
-e GERRIT_URL=$GERRIT_URL \
-e GERRIT_TOKEN=$GERRIT_TOKEN \
rinekri/karandash:latest karandash validate
Examples
Minimal Configuration
# .karandash/config.yaml
platforms:
gerrit:
url: "https://gerrit.example.com"
username: "${GERRIT_USERNAME}"
token: "${GERRIT_TOKEN}"
rules:
title-format:
pattern: "^[A-Z].+"
max-length: 72
commit-messages:
max-length: 72
reporters:
console: true
Gerrit-Optimized Configuration
# .karandash/config.yaml
platforms:
gerrit:
url: "${GERRIT_URL}"
token: "${GERRIT_TOKEN}"
rules:
# Gerrit typically uses one commit per change
title-format:
pattern: "^[A-Z].*[^.]$"
min-length: 10
max-length: 72
commit-messages:
max-length: 72
min-length: 10
size-limits:
max-files: 30
max-lines: 500
# Gerrit changes typically have 1 commit
max-commits: 5
security:
scan-for-secrets: true
sensitive-files:
- "**/.env"
- "**/*.pem"
- "**/*.key"
reporters:
console: true
Jenkins Pipeline with Gerrit Trigger
pipeline {
agent {
docker {
image 'rinekri/karandash:latest'
}
}
environment {
GERRIT_URL = 'https://gerrit.example.com'
GERRIT_TOKEN = credentials('gerrit-http-password')
}
stages {
stage('Validate') {
when {
expression { env.GERRIT_CHANGE_NUMBER != null }
}
steps {
sh """
karandash validate \\
--platform gerrit \\
--project "\${GERRIT_PROJECT}" \\
--mr-id "\${GERRIT_CHANGE_NUMBER}" \\
--format json --output results.json
"""
}
post {
always {
archiveArtifacts artifacts: 'results.json', allowEmptyArchive: true
}
}
}
}
}
Authentication Edge Cases
HTTP Password vs Token Confusion
Issue: "401 Unauthorized" when using standard login password instead of HTTP password.
Root cause: Gerrit distinguishes between login passwords (for web UI) and HTTP passwords (for API access). They are different.
Fix:
1. Go to Settings > HTTP Credentials
2. Generate a new HTTP password (not your login password)
3. Use the generated HTTP password for GERRIT_TOKEN
Gerrit Token Format Variations
Issue: Different Gerrit instances support different authentication formats (HTTP password, OAuth, LDAP, etc.).
Root cause: Gerrit's authentication is pluggable. Enterprise instances may use custom auth plugins.
Mitigation:
- Ask your Gerrit administrator which auth method is supported
- Test authentication: curl -u "username:$GERRIT_TOKEN" "$GERRIT_URL/a/changes/?q=status:open&n=1"
- Switch to a different auth method if one doesn't work
HTTP Password Expiration
Issue: Validation fails with "401 Unauthorized" after HTTP password is manually reset.
Root cause: HTTP passwords can be manually invalidated or expire based on instance policy.
Fix:
1. Regenerate a new HTTP password in Settings > HTTP Credentials
2. Update GERRIT_TOKEN in your CI/CD configuration
3. Test the new password immediately
Authentication on Public Gerrit Instances
Issue: Validation works locally but fails in CI/CD on public instances like googlesource.com.
Root cause: Public Gerrit instances (googlesource.com) typically do not require authentication for read-only operations, but some CI/CD environments may need explicit token configuration.
Expected behavior: Public instances work without a token. Set GERRIT_TOKEN only if needed.
Rate Limiting Considerations
No Standard Rate Limits
Issue: Karandash makes many API calls to a self-hosted Gerrit without errors, but is very slow.
Root cause: Self-hosted Gerrit typically has no rate limits, but the server may be slow or under load.
Mitigation: - Check Gerrit server CPU/memory usage - Verify network latency to the Gerrit server - Contact your Gerrit administrator for performance diagnostics
Custom Rate Limiting on Enterprise Instances
Issue: Validation fails intermittently with "429 Too Many Requests" on enterprise Gerrit.
Root cause: Enterprise Gerrit installations may have custom rate limiting configured.
Check with administrator: - Ask if rate limiting is enabled - Get the configured request limit - Implement backoff in your CI/CD pipeline
Platform-Specific Limitations
Single Commit Per Change Assumption
Issue: Karandash validates only the current revision. Changes with multiple commits may not validate all commits.
Root cause: Gerrit traditionally enforces one commit per change. Karandash validates commits from the current revision only.
Expected behavior: This is by design. For changes with multiple commits, only the latest revision's commits are validated.
Limited File Change Information
Issue: File change detection is incomplete or unavailable.
Root cause: Gerrit's API provides limited change details. Full diff information requires complex API queries.
Expected behavior: Karandash reports available file stats. For detailed diffs, check the Gerrit web UI.
No Review Score Setting
Issue: Karandash cannot set Code-Review or Verified labels.
Root cause: These are Gerrit's voting labels. Setting them requires explicit permissions and is not implemented in Karandash.
Workaround: Use Gerrit's native review interface or bots with label-voting permissions.
Legacy URL Format Deprecated
Issue: Using /#/change-number format fails with "project name required" error.
Root cause: Gerrit deprecated hash-based URLs. Modern URLs use /c/{project}/+/{id} format.
Fix: Update URLs to the modern format:
Old: https://gerrit.example.com/#/c/12345
New: https://gerrit.example.com/c/myproject/+/12345
XSRF Token Handling
XSRF Protection in Gerrit API
Issue: Raw API responses appear to have extra characters at the start.
Root cause: Gerrit's REST API prefixes responses with )]}'\n for XSRF protection. Karandash handles this automatically.
Expected behavior: No action needed. Karandash strips the XSRF prefix internally.
CI/CD Integration Edge Cases
Jenkins Gerrit Trigger Environment Variables
Issue: Required Gerrit variables are empty or missing in Jenkins jobs.
Root cause: Gerrit Trigger plugin must be installed and configured. Without it, Gerrit environment variables are not set.
Fix:
1. Install the Gerrit Trigger plugin in Jenkins
2. Configure the trigger in your Jenkins job
3. Variables like GERRIT_CHANGE_NUMBER will be populated
Zuul CI Change Metadata
Issue: Change information passed to Zuul is incomplete or formatted differently.
Root cause: Zuul's Gerrit driver handles change data differently than other CI systems.
Workaround: Use Zuul's built-in context variables:
- name: Run Karandash
shell: |
karandash validate \
--platform gerrit \
--project "{{ zuul.project.name }}" \
--mr-id "{{ zuul.change }}"
API Differences from Other Platforms
Gerrit-Specific Terminology
Issue: Confusion between Gerrit terms and Karandash expectations.
Mapping: - Gerrit "Change" = PR/MR in other systems - Gerrit "Patchset" = Revision/update - Gerrit "Subject" = PR/MR title - Gerrit "Change-Id" = MR ID
Limited Approval Metadata
Issue: Karandash cannot distinguish between different review states or voting levels.
Root cause: Gerrit API provides limited review state information. Detailed voting is available but not exposed in Karandash.
Expected behavior: Karandash validates basic commit/change metadata only.
XSRF Token Security
Issue: Understanding why API responses start with )]}'\n.
Root cause: XSRF protection. Gerrit prefixes JSON responses to prevent browser-based XSRF attacks.
Expected behavior: Karandash automatically strips this prefix. No configuration needed.
Self-Hosted Gerrit Considerations
SSL Certificate Issues on Internal Gerrit
Issue: "Certificate verification failed" or "SSL: CERTIFICATE_VERIFY_FAILED" errors.
Root cause: Internal Gerrit instances use self-signed or internal CA certificates not trusted by default.
Fix:
For Java JAR:
java -Djavax.net.ssl.trustStore=/path/to/truststore.jks \
-Djavax.net.ssl.trustStorePassword=password \
-jar karandash.jar validate \
--platform gerrit \
--project "myproject" \
--mr-id 12345
For Docker:
docker run \
-v /path/to/ca-cert.pem:/usr/local/share/ca-certificates/ca.crt \
-e GERRIT_URL=$GERRIT_URL \
-e GERRIT_TOKEN=$GERRIT_TOKEN \
rinekri/karandash:latest karandash validate \
--platform gerrit \
--project "myproject" \
--mr-id 12345
Custom Gerrit Plugins
Issue: Karandash validation fails with "unexpected API response" on customized Gerrit instances.
Root cause: Some Gerrit plugins modify API behavior or add non-standard endpoints.
Mitigation: - Report the plugin name and behavior to Karandash developers - Use vanilla Gerrit if possible - Check plugin documentation for API changes
URL Parsing and Project Identification
Project Path Case Sensitivity
Issue: Validation fails with "404" even though the project exists.
Root cause: Gerrit project paths are case-sensitive. MyProject differs from myproject.
Fix:
1. Use exact casing from the Gerrit web UI
2. Test with: curl "$GERRIT_URL/a/projects/exact%2Fproject%2Fpath"
Nested Project Paths
Issue: Validation fails for projects in nested directories (e.g., team/backend/auth).
Root cause: Nested paths require proper encoding and handling.
Expected behavior: Karandash handles nested paths correctly. URL-encode slashes: team%2Fbackend%2Fauth.
Change Number vs Change ID Confusion
Change Number (Legacy)
Issue: Using change number in modern format fails.
Root cause: Legacy Gerrit used numeric change IDs. Modern Gerrit uses Change-IDs (SHA-1 style).
Fix: Use the modern /c/{project}/+/{change-id} format, which accepts numeric IDs or Change-IDs.