How to Integrate MediaWiki with Git for Source Control

Why Git Matters for MediaWiki Projects

MediaWiki is a living codebase. The core software, skins, and extensions evolve constantly, and most Wikimedia projects host their source on Gerrit or GitLab. Using Git locally gives you three practical benefits:

• History on your machine. Every edit, branch, and tag is available offline, which makes debugging and feature experimentation fast.
• Atomic changes. A single commit can contain a complete set of wiki page edits or extension updates, making review and rollback straightforward.
• Collaboration. Git’s branching model lets multiple developers work in parallel, then merge cleanly via Gerrit or GitHub.

Below is a step‑by‑step guide that covers the most common workflows: cloning the core repository, handling extensions with submodules, using the git-remote-mediawiki helper to edit wiki content directly, and wiring the setup into a CI pipeline.

Prerequisites

Before you start, make sure you have the following tools installed:

# Git (>= 2.30) – the version control engine
sudo apt-get install git   # Debian/Ubuntu
# Composer – dependency manager for PHP libraries
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php --install-dir=/usr/local/bin --filename=composer
# Optional: Python 3 (for git‑remote‑mediawiki scripts)
sudo apt-get install python3

You also need a Wikimedia developer account with SSH access to gerrit.wikimedia.org. The account provides the git user name used in remote URLs.

Cloning MediaWiki Core

The official MediaWiki core repository lives at https://gerrit.wikimedia.org/r/mediawiki/core.git. To get a development copy:

# Create a directory for the project
mkdir -p ~/mediawiki && cd ~/mediawiki
# Clone the master branch (cutting‑edge development)
git clone https://gerrit.wikimedia.org/r/mediawiki/core.git
cd core
# Initialise submodules (extensions bundled with core)
git submodule update --init --recursive

If you prefer a stable release, replace --branch master with a tag such as REL1_44:

git clone https://gerrit.wikimedia.org/r/mediawiki/core.git --branch REL1_44 mediawiki

After cloning, run Composer to pull external PHP libraries:

composer install --no-dev

Finally, run the MediaWiki maintenance script to create the database schema (replace the DB credentials with your own):

php maintenance/install.php \
    --dbname=mywiki \
    --dbuser=root \
    --dbpass=secret \
    "My Wiki" "admin"

Managing Extensions with Git Submodules

Most extensions are stored in their own repositories under https://gerrit.wikimedia.org/r/mediawiki/extensions/. The recommended pattern is to keep each extension as a submodule of the core checkout. This keeps version alignment simple – you can lock an extension to a specific tag that matches the core release.

# Add the Extension:Echo as a submodule
cd ~/mediawiki/core
git submodule add https://gerrit.wikimedia.org/r/mediawiki/extensions/Echo.git extensions/Echo
# Checkout a stable tag that matches the core version
cd extensions/Echo
git checkout REL1_44
# Return to the core root and commit the submodule reference
cd ../../
git add extensions/Echo
git commit -m "Add Echo extension at REL1_44"

When you later update the core, you can refresh all submodules with a single command:

git submodule foreach 'git pull && git checkout $(git describe --tags $(git rev-parse HEAD))'

Remember to run composer update --no-dev after pulling new extensions, because many extensions declare additional Composer dependencies.

Editing Wiki Pages Directly with git-remote-mediawiki

The Git‑remote‑mediawiki helper lets you treat a live wiki as a Git remote. The workflow mirrors a normal Git clone:

1. Clone the remote as a bare repository.
2. Check out a working tree, edit pages as plain text files.
3. Commit locally.
4. Push the commit back to the wiki, where the tool translates the changes into API calls.

Because the helper works over the MediaWiki API, you only need read/write credentials (a bot password or OAuth token). Here is a minimal setup:

# Install the helper (requires Python 3)
pip3 install git-remote-mediawiki
# Register the remote helper with Git
git config --global url."git-remote-mediawiki::".insteadOf "mediawiki://"
# Clone a wiki (replace example.org with your domain)
git clone mediawiki://example.org/mywiki mywiki
cd mywiki
# List pages – each page appears as a file under the "pages" directory
ls pages
# Edit a page with your favourite editor
nano pages/Main_Page.txt
# Stage and commit the change
git add pages/Main_Page.txt
git commit -m "Update the front page with a new banner"
# Push back to the live wiki
git push origin master

Important notes:

• The helper stores a local cache of page revisions, so the first clone can be slow for large wikis.
• It works best for wikis under 1 000 pages; performance degrades beyond that.
• Never commit binary files (e.g., uploaded images) – the helper only supports textual page content.

Automating Deployments with CI

Once you have a Git repository that contains core, extensions, and possibly a git-remote-mediawiki working tree, you can automate testing and deployment with any CI system that supports Git. The MediaWiki documentation recommends Jenkins, but GitHub Actions, GitLab CI, or Travis work equally well. Below is a generic GitHub Actions workflow that runs the MediaWiki test suite on every push to a branch:

name: MediaWiki CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: true
      - name: Set up PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.1'
          extensions: mbstring, intl, mysql
      - name: Install Composer dependencies
        run: composer install --no-dev
      - name: Set up MySQL
        run: |
          sudo service mysql start
          mysql -e 'CREATE DATABASE testwiki;'
      - name: Run MediaWiki update
        run: php maintenance/run.php update
      - name: Run parser tests
        run: php tests/parserTests.php

For a production deployment you would replace the test steps with a maintenance/run.php update against a staging database, then copy the built files to the web server. If you also use git-remote-mediawiki, you can add a step that pushes a set of documentation pages to the live wiki after a successful build:

# Assuming the working tree is in ./wiki
cd wiki
# Generate a markdown file from the CI build output
echo "# Release notes" > pages/Release_Notes.txt
git add pages/Release_Notes.txt
git commit -m "Add CI release notes"
git push origin master

Best Practices and Gotchas

• Never edit master directly. Create a feature branch, push it for review, and let Gerrit merge it after automated tests pass.
• Keep extensions in sync with core. When you upgrade core to a new release, verify that each extension still builds against the new API. Use the git submodule foreach command shown earlier to batch‑update.
• Store secrets safely. Bot passwords, OAuth tokens, and database credentials should live in CI secret stores, not in the repository.

Beware of large wikis. The git-remote-mediawiki helper caches the full revision history. For wikis with many pages, consider cloning only the namespace you need:

git clone "mediawiki://example.org/mywiki?namespace=User"

Use signed commits. MediaWiki’s Gerrit instance can be configured to reject unsigned commits. Set up GPG signing in your ~/.gitconfig:

git config --global commit.gpgsign true
git config --global user.signingkey YOUR_KEY_ID

Putting It All Together – A Sample Project Layout

Here is a directory structure that many teams adopt:

mywiki-project/
├─ core/                # MediaWiki core (git submodule of core.git)
│   └─ extensions/
│       ├─ Echo/       # Submodule for Echo extension
│       └─ VisualEditor/
├─ wiki/                # Working tree managed by git-remote-mediawiki
│   └─ pages/
│       ├─ Main_Page.txt
│       └─ Help/…
├─ .gitignore
├─ composer.json        # Project‑level Composer file
└─ .github/workflows/ci.yml

With this layout you can:

1. Version core and extensions together.
2. Edit wiki content in wiki/pages and push changes back to the live site.
3. Run automated tests on every branch push.
4. Deploy a new release by merging a release branch into master, updating submodule references, and running the CI deployment job.

Conclusion

Integrating MediaWiki with Git gives you the full power of modern version control: granular history, easy branching, and seamless CI/CD pipelines. The essential pieces are:

• Clone the core repository from Gerrit.
• Use submodules for extensions and keep them on matching tags.
• Leverage git-remote-mediawiki if you want to treat wiki pages as files.
• Automate testing and deployment with a CI system.

Following the steps and best practices outlined above will let you manage a MediaWiki installation confidently, whether you run a small community wiki or a large Wikimedia‑style deployment.