Wikimedia Gerrit

Wikimedia Gerrit Skill

This skill provides Wikimedia Gerrit code review integration using git-review and SSH commands. Use git-review for submitting/downloading changes and SSH gerrit query for reading/changing information.

Wikimedia Gerrit server: gerrit.wikimedia.org (port 29418)

Prerequisites

Install git-review: https://docs.opendev.org/opendev/git-review/latest/installation.html

Quick install:

# Using pip (recommended)
pip install git-review

# macOS
brew install git-review

# Debian/Ubuntu
sudo apt install git-review

# Fedora/RHEL/CentOS
sudo dnf install git-review

Wikimedia Developer Account

Create a Wikimedia Developer account at https://idm.wikimedia.org/signup/. This username and password is used for both Gerrit and Phabricator.

Authentication

SSH Configuration

Configure Git to use SSH for Gerrit:

# Replace 'shell_user' with your Wikimedia Developer account username
git config --global url."ssh://shell_user@gerrit.wikimedia.org:29418/".insteadOf "https://gerrit.wikimedia.org/r/"

# Set your Gerrit username
git config --global gitreview.username your_wikimedia_username

Test SSH Connection

# Test connection to Wikimedia Gerrit
ssh -p 29418 your_username@gerrit.wikimedia.org gerrit version

# Expected output: gerrit version 3.x.x

SSH key setup:

1. Generate SSH key: ssh-keygen -t ed25519
2. Add public key to Gerrit: https://gerrit.wikimedia.org/r/settings/ssh-keys
3. Verify connection as shown above

Initial Setup

Configure Repository

# Clone a Wikimedia repository
git clone ssh://gerrit.wikimedia.org:29418/mediawiki/core.git
cd mediawiki

# Or clone from HTTPS (after SSH configuration above)
git clone https://gerrit.wikimedia.org/r/mediawiki/core

# Setup git-review (one-time per repository)
git review -s --verbose

# Verify setup
cat .gitreview

Common Wikimedia Repositories

# MediaWiki core
git clone ssh://gerrit.wikimedia.org:29418/mediawiki/core.git

# Extensions (example)
git clone ssh://gerrit.wikimedia.org:29418/mediawiki/extensions/CiteThisPage.git

# Skins (example)
git clone ssh://gerrit.wikimedia.org:29418/mediawiki/skins/Vector.git

# Operations/puppet
git clone ssh://gerrit.wikimedia.org:29418/operations/puppet.git

# Sandbox (for practice)
git clone ssh://gerrit.wikimedia.org:29418/sandbox.git

Branch Configuration

Some repositories use main instead of master:

# Configure for main branch
git config --add gitreview.branch main

Querying Changes (SSH)

Use SSH gerrit query commands to search and view changes:

# Check SSH connection
ssh -p 29418 youruser@gerrit.wikimedia.org gerrit version

# List your open changes
ssh -p 29418 youruser@gerrit.wikimedia.org gerrit query "owner:self status:open"

# Query changes for a project
ssh -p 29418 youruser@gerrit.wikimedia.org gerrit query "status:open project:mediawiki/core"

# View specific change details
ssh -p 29418 youruser@gerrit.wikimedia.org gerrit query change:123456 --all-approvals --details

# Query with JSON output (for scripting)
ssh -p 29418 youruser@gerrit.wikimedia.org gerrit query --format=JSON "status:open" | jq '.subject'

Submitting Changes (git-review)

git review                          # Submit current branch for review
git review -t topic-name            # Submit with topic
git review -f                       # Submit and close local branch
git review --reviewers user1,user2 # Add reviewers
git review -n                       # Dry-run (show what would be done)
git review -D                       # Draft mode (WIP changes)

Downloading Changes

git review -d 12345                 # Download change 12345
git review -d 12345,3              # Download patchset 3 of change 12345
git review -x 12345                # Cherry-pick change (no branch)
git review -m 12345                # Compare local changes to remote

Downloads create a local branch named review/username/topic.

Updating Changes

# Make changes to downloaded review
git commit --amend
git review                          # Upload new patchset

# Update to latest patchset
git review -d 12345                # Re-download updates the branch

Advanced Options

git review -R                       # Don't rebase (submit as-is)
git review --no-cache               # Skip local cache
git review -v                       # Verbose output
git review --track                  # Track remote branch

Configuration

Per-Repository Settings

File: .gitreview (repository root)

[gerrit]
host=gerrit.wikimedia.org
port=29418
project=mediawiki/extensions/CiteThisPage
defaultbranch=master
defaultremote=origin

Global Settings

# Set Gerrit username
git config --global gitreview.username myuser

# Set default remote
git config --global gitreview.remote origin

# Configure scheme (ssh/http/https)
git config --global gitreview.scheme ssh

Commit Message Guidelines

Follow Wikimedia's commit message guidelines: https://www.mediawiki.org/wiki/Gerrit/Commit_message_guidelines

# Example commit message
Bug: T123456
Summary of changes (imperative mood, max 72 chars)

Detailed description explaining what and why, not how.
Paragraphs separated by blank lines.

Change-Id: Iabc123def456

• Start with imperative mood ("Add feature" not "Added feature")
• First line max 72 characters
• Include Bug: T123456 for Phabricator task
• Include Change-Id: (auto-generated by commit hook)

Examples

Daily Workflow

# Start work on new feature (with Phabricator task)
git checkout -b T123456-feature-name origin/master
# ... make changes ...

# Commit with proper message
git commit -m "Add new feature for user profiles

This adds a REST endpoint that returns user profile data.

Bug: T123456
Change-Id: Ixxx
"

# Submit for review
git review -t T123456

# Address review comments
# ... make changes ...
git commit --amend
git review

Reviewing Others' Changes

# Download change for review
git review -d 123456

# Review the code
git log -p HEAD^..HEAD
git diff main..HEAD

# Test the change
# ... run tests ...

# Return to main branch
git checkout main
git branch -D review/username/topic

Working with Topics

# Submit with topic (groups related changes)
git review -t authentication-refactor

# All related changes will be grouped under this topic
git commit -m "Part 2: Update tests"
git review -t authentication-refactor

Working with Phabricator Tasks

# Create branch named after task
git checkout -b T12345-fix-bug origin/master

# Include task in commit message
git commit -m "Fix null pointer exception in user parser

The parser was throwing an exception when handling empty input.
Added null check to prevent crashes.

Bug: T12345
Change-Id: Iabc123
"

SSH Commands

For operations not covered by git-review:

# Query open changes
ssh -p 29418 youruser@gerrit.wikimedia.org gerrit query status:open project:mediawiki/core

# Query specific change
ssh -p 29418 youruser@gerrit.wikimedia.org gerrit query change:123456

# Query your changes
ssh -p 29418 youruser@gerrit.wikimedia.org gerrit query owner:self status:open

# Query changes by topic
ssh -p 29418 youruser@gerrit.wikimedia.org gerrit query topic:T123456

# Review from command line
ssh -p 29418 youruser@gerrit.wikimedia.org gerrit review 123456,3 --verified +1 --message "'Looks good!'"

# Abandon change
ssh -p 29418 youruser@gerrit.wikimedia.org gerrit review 123456 --abandon

JSON Output for Scripting

# Get change info as JSON
ssh -p 29418 youruser@gerrit.wikimedia.org gerrit query --format=JSON change:123456

# Process with jq
ssh -p 29418 youruser@gerrit.wikimedia.org gerrit query --format=JSON status:open project:mediawiki/core | jq '.subject'

Troubleshooting

# Re-run setup
git review -s

# Force setup (fixes common issues)
git review -s --force

# Verbose output for debugging
git review -v

# Check configuration
cat .gitreview
git config -l | grep gitreview

# Test SSH connection
ssh -p 29418 youruser@gerrit.wikimedia.org gerrit version

Common Issues

"We don't know where your gerrit is"

git review -s              # Run setup
# Or create .gitreview file manually

"fatal: 'gerrit' does not appear to be a git repository"

git review -s              # Setup remote
git remote -v              # Verify gerrit remote exists

"Permission denied (publickey)"

# Add SSH key to Gerrit: https://gerrit.wikimedia.org/r/settings/ssh-keys
# Or configure username:
git config --global gitreview.username youruser

Change-Id missing

# Install commit-msg hook
git review -s

# Verify hook is installed
ls -l .git/hooks/commit-msg

Git Configuration Issues

If git uses HTTPS instead of SSH:

# Fix: Configure SSH insteadOf HTTPS
git config --global url."ssh://your_username@gerrit.wikimedia.org:29418/".insteadOf "https://gerrit.wikimedia.org/r/"

Useful URLs

• Gerrit Web Interface: https://gerrit.wikimedia.org/r/
• Documentation: https://www.mediawiki.org/wiki/Gerrit
• Tutorial: https://www.mediawiki.org/wiki/Gerrit/Tutorial
• Advanced Usage: https://www.mediawiki.org/wiki/Gerrit/Advanced_usage
• Commit Guidelines: https://www.mediawiki.org/wiki/Gerrit/Commit_message_guidelines
• Troubleshooting: https://www.mediawiki.org/wiki/Gerrit/Troubleshooting
• Git-Review Manual: https://docs.opendev.org/opendev/git-review/latest/

Summary

Quick start:

1. Install git-review: pip install git-review
2. Configure SSH: git config --global url."ssh://user@gerrit.wikimedia.org:29418/".insteadOf "https://gerrit.wikimedia.org/r/"
3. Clone: git clone ssh://gerrit.wikimedia.org:29418/sandbox.git
4. Setup: git review -s
5. Verify: ssh -p 29418 youruser@gerrit.wikimedia.org gerrit version
6. Query: ssh -p 29418 youruser@gerrit.wikimedia.org gerrit query "owner:self status:open"
7. Submit: git review, git review -d 123456, etc.

For detailed command reference, use git review --help or visit https://docs.opendev.org/opendev/git-review/latest/.