Your first contribution to Collabora Online
Hello 
Collabora Online has moved code review from GitHub pull requests to Gerrit, and the online and core repositories have been unified into a single monorepo (the LibreOffice core now lives under engine/ inside online). New pull requests opened against main on GitHub are automatically closed with a pointer to Gerrit — so please do not start there.
This post walks you through pushing your first patch the new way.
TL;DR: Pushing to gerrit
# 1. Sign in once at https://gerrit.collaboraoffice.com (use your GitHub account)
# 2. Add your SSH key at https://gerrit.collaboraoffice.com/settings/#SSHKeys
# 3. Clone the monorepo
git clone ssh://YOUR_USERNAME@gerrit.collaboraoffice.com:29418/online
cd online
# 4. Install the commit-msg hook (adds the Change-Id automatically)
scp -p -P 29418 YOUR_USERNAME@gerrit.collaboraoffice.com:hooks/commit-msg .git/hooks/
# 5. Hack, build, test
# 6. Commit with signoff
git commit -s
# 7a). Send the patch for review
git push origin HEAD:refs/for/main
# 7b) Or use the g script in the root of the repository
./g review [branch]
# assuming:
# 1) You have a remote pointing at ssh://<user>@gerrit.collaboraoffice.com:29418/online
# (typically named 'origin' or 'cogerrit').
# 2) All commits but the topmost are pushed as WIP; the topmost commit is the
# actual review.
# If [branch] is given (e.g. 'main' or 'distro/collabora/co-26-04'), the
# current branch's upstream is set to <gerrit-remote>/<branch> first.
The terminal prints a Gerrit URL — that is your change. Reviewers will leave comments there, and CI will vote on it.
Step by step
1. Sign in to Gerrit
Go to https://gerrit.collaboraoffice.com and sign in with your GitHub account. The first sign-in creates your Gerrit profile.
2. Add your SSH key
Open https://gerrit.collaboraoffice.com/settings/#SSHKeys and paste the public half of an SSH key you control. If you don’t have one yet, generate it with ssh-keygen -t ed25519.
3. Clone the monorepo
git clone ssh://YOUR_USERNAME@gerrit.collaboraoffice.com:29418/online
cd online
There is no separate core clone any more — the LibreOffice core sits under engine/ inside this repo. (Background reading: Open Source in Action #2 — monorepo unification.)
4. Install the commit-msg hook
Gerrit identifies a logical change by a Change-Id: trailer in the commit message. The hook adds it automatically:
scp -p -P 29418 YOUR_USERNAME@gerrit.collaboraoffice.com:hooks/commit-msg .git/hooks/
If you skip this step Gerrit will reject your push and tell you so.
5. Build it
- Linux: https://collaboraonline.github.io/post/build-code/
- Any platform in 5 minutes: https://forum.collaboraonline.com/t/start-developing-cool-on-any-platform-in-5-minutes/52
6. Pick something to work on and Commit with signoff
Browse the newcomer-friendly list: https://collaboraonline.github.io/post/easyhacks/
Work on main directly or on a local branch as Gerrit doesn’t care about your local branch names, only about the commit you push. Build, test, then:
git add path/to/changed/file
git commit -s # -s is short for --signoff: see DCO note below
An editor opens. Write a good commit message — see Best practices below.
7a). Push for review using refspec
git push origin HEAD:refs/for/main
The magic refspec is refs/for/main (not refs/heads/main). Gerrit replies with a URL to your change — open it, add reviewers if you know who should look, and watch CI run.
7b) Or use the g script in the root of the repository
./g review [branch]
# assuming:
# 1) You have a remote pointing at ssh://<user>@gerrit.collaboraoffice.com:29418/online
# (typically named 'origin' or 'cogerrit').
# 2) All commits but the topmost are pushed as WIP; the topmost commit is the
# actual review.
# If [branch] is given (e.g. 'main' or 'distro/collabora/co-26-04'), the
# current branch's upstream is set to <gerrit-remote>/<branch> first.
8. Address review feedback
When a reviewer asks for changes, amend the same commit rather than stacking a fix-up on top. Because the Change-Id: trailer stays the same, Gerrit recognises it as a new patchset of the same change:
# edit, build, test
git add ...
git commit --amend # keep the Change-Id line untouched
git push origin HEAD:refs/for/main # or ./g review
If you stacked several commits, each one becomes its own Gerrit change, reviewed in order.
9. Merging
Once a reviewer gives +2 and CI is happy, the change is submitted from the Gerrit web UI. There is no “merge button” on your side.
Project policies
Rather than duplicate text here (where it would drift), the canonical source is CONTRIBUTING.md in the repo:
- Sign your work (DCO) — every commit needs a
Signed-off-by:trailer with your real name.git commit -sadds it for you. - AI policy — AI tooling is allowed; you are accountable for every line you submit.
- For non-technical contributors — fixing a label or icon without using the command line.
- Translations — go to Weblate, not Gerrit.
Best practices for git commit messages
Read How to Write a Git Commit Message by Chris Beams. The short version:
- Imperative mood, present tense. “Fix hang in foo()”, not “Fixed hang in foo()”.
- Subject line under ~72 characters, no trailing period. It is a summary, not a sentence.
- Blank line, then a body explaining why the change is needed. The “how” is in the diff; the “why” is your responsibility.
- If the change is conceptually trivial, a one-line subject is fine.
A good Gerrit commit ends up looking like:
Fix hang in foo() when bar is empty
Previously foo() spun forever if bar arrived empty because the
exit condition only checked size > 0 after the first iteration.
Check the condition up front so we bail out cleanly.
Signed-off-by: Random J Developer <random@developer.example.org>
Change-Id: Iabc123...
The Change-Id line is added by the commit-msg hook — don’t write it by hand.
Stuck?
Drop into one of our communication channels: #cool-dev on matrix, Telegram, or this forum. Happy hacking!
