Skip to content

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:

  1. Log in to your Gerrit instance
  2. Go to Settings > HTTP Credentials (or Settings > HTTP Password)
  3. Click Generate Password (or Generate New Password)
  4. 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 )]}'\n to 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 doctor reports 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.