A useful review starts with understanding the change. Galley is a free, open-source browser extension that helps your team read the explanation, inspect the edits and discuss the details in one view.
Press Read on a GitHub pull request or GitLab merge request. Documents open as readable articles, with changed words shown inside their sentences. Turn on Code files to include supported source files with line numbers, syntax colours and wrapped lines. JavaScript and TypeScript tests open as readable specifications: scan the behavior names, see which cases changed, then review the code. Comments and replies sit beside the text they discuss and go back to the original review.
Your team gets more context for its feedback, using the GitHub or GitLab workflow it already knows.
Between reviews, press Read the project on a repository, folder or Markdown file to read the project's own documentation at one commit. Follow links between specs, decisions and guides without losing your place, and open the Map to see which documents link to the one you are reading, with each link as evidence. Switch the map to Architecture, Infrastructure or Decisions for what the configuration declares and what the decision records state, keep private Notes you save only when you choose, and from a review, read the docs that link to each chapter's files in the sheet beside it, with the Library and its search there too. Library reading starts in Focus; choose Balanced or Wide text in Reading settings → Layout, or cycle them with L, without changing the review's layout.
Prefer a clear platform page? In the toolbar popup, choose Settings… and turn off Read button on the page. Open with Read this review or Read the project in the popup, or Alt Shift R (changeable in your browser's extension shortcuts). With the page button off, Galley fetches files only when you ask.
Before / after
The same merge request, files and comments, shown in a more readable view. Teammates can read and respond to your comments on GitHub or GitLab without installing Galley.
How Galley helps
- Make the content readable. Documents keep their headings, tables, task lists, footnotes, alerts, images and Mermaid diagrams. Code keeps its line numbers, syntax colours and diff signs, with long lines that wrap to fit the screen.
- See edits in context. Added words are highlighted and removed words struck through inside their sentences. Table edits appear in their cells. Changed link destinations are called out even when the link text stays the same.
- Focus on what changed. Changes to paragraph wrapping are not marked as text edits. Unchanged sections fold away; open them whenever you need more context. Lockfiles, generated files and whitespace-only edits fold to one line each, code that moved says where it went, tests follow the code they test, and JavaScript and TypeScript files start with a short list of the functions, classes and types that changed. Come back tomorrow and Galley offers to continue where you stopped. Your scrollbar gets a breather.
- Discuss it beside the text. Read threads beside their paragraph or code line. Select text to add a comment, reply in the thread, and keep drafts while you read on. Comments and replies go to the original GitHub or GitLab review.
- Find your reading comfort. Choose from nineteen palettes, six typefaces, five text sizes and six layouts, with light and dark modes, compact spacing and keyboard shortcuts.
- Read the project, not just the change. Read a repository's docs at one commit, follow their links and come back to the same paragraph. Build an optional reading chapter from documents or headings you choose; the full library stays available. The project map shows what links to a document and what it links to, the exact link behind each connection, and links that lead nowhere; its architecture, infrastructure and decision views say where every item comes from, and never call declared configuration running. Your own notes and proposals stay on your device, are saved only when you choose, and leave it only through an export you preview.
- Keep your work on your code host. Files render in your browser. Galley has no server, account or analytics. External images load only when you choose.
Source changes that do not appear in the rendered document, such as HTML comments and link definitions, are counted and linked to the platform diff.
At a glance
| |
|---|
| 0 | Galley accounts needed. Use your existing GitHub or GitLab access. |
| 1 | Read button to open changed documents and supported code files. |
| 19 | reading palettes, each available in light and dark. |
| 6 · 5 · 6 | typefaces, text sizes and layouts to suit your screen and your eyes. |
| 20 | review keyboard shortcuts for navigation, comments and settings; the library also has its own navigation keys. |
| 120 | characters of code per line on a wide screen, before wrapping. |
Install
- Add Galley to Chrome. Edge, Brave and Arc take the same build.
- Open a GitHub pull request or a GitLab merge request.
- Press Read in the bottom-right corner.
No Galley account needed. Private repositories and self-hosted sites have a few setup steps below.
- Private GitHub repositories need a fine-grained token with read-only Contents and Pull requests access, pasted into the Galley popup. Commenting also needs Pull requests: read and write. The token stays in extension storage that web pages cannot read.
- GitLab uses your signed-in session. Self-managed GitLab and GitHub Enterprise Server are enabled one domain at a time from the popup.
- Want to look first? The live demo runs the real reader on a sample merge request in your browser.
- Firefox builds are attached to every release; the add-ons listing is not published yet. Building from source is in CONTRIBUTING.md.
The user guide covers every setting, token and platform detail. Everything else, from architecture and design decisions to proposals and how-to guides, starts at docs/README.md.
Keys
| Key | |
|---|
| J K | Next / previous change |
| N P | Next / previous conversation |
| ] [ | Next / previous file |
| F | Go to a file |
| / | Search the review, including folded parts |
| M | Chapters and the Library: ↑ ↓ move through a list, ↵ opens, ← → step through chapters, Esc goes back a sheet |
| R | Comment on the selection, or on the paragraph in focus |
| ⌘/Ctrl Enter | Post the comment or reply |
| V | Mark the file viewed |
| C | Change marks on / off |
| A | Changed parts / whole files |
| U | Only what changed since you last looked / the whole review |
| L · D | Next layout · comfortable / compact |
| + − 0 | Larger / smaller / default text |
| , · ? | Settings · these shortcuts |
| Esc | Close the innermost thing, and finally the reader. Drafts are kept. |
Reading Project library: Alt ← → back and forward, / find a document, L next reading layout, M map or document, C chapters, N notes, , settings, ? these keys.
FAQ
Do my teammates need Galley?
No. Comments and replies appear in the original GitHub or GitLab review. Teammates can read and respond there, whether or not they use Galley.
Can I review code as well as documents?
Yes. Markdown documents open as readable articles. Turn on Code files in Reading settings → Review to include supported source and configuration files, with syntax colours, wrapped lines and comments beside the code.
Where do my files and comments go?
Galley loads files from your GitHub or GitLab site and renders them in your browser. Comments go back to that review when you post. There is no Galley server or analytics. The demo keeps comments in your browser session and does not post to either platform.
How does it help my team review changes?
Galley puts readable content, edits and discussion in one view. Reviewers can follow the proposal, inspect a change in context and ask a question beside it. We have not measured review speed; the focus is helping people understand the work.
Can I approve a request from Galley?
You can read, comment, reply and mark files as viewed in Galley. Return to GitHub or GitLab to approve the request, request changes or resolve a thread.
Why “Galley”?
A galley proof lets editors read a book's text and leave notes before publication. Galley brings that approach to code and document reviews, with readable content and space for feedback.
Privacy and security, the short version
- Galley contacts only the GitHub or GitLab site you are on. No backend, no analytics, no telemetry.
- Documents render in a shadow DOM after sanitising. Raw HTML in a pull request cannot run scripts, load trackers, or imitate Galley's change markers.
- Mermaid and syntax highlighting run in sandboxed frames with no access to the page, your session or the network.
- Text Galley adds to a comment (the file path and the quote) is posted as code, so a pull request cannot make your comment mention people or show images.
- The GitHub token never enters the page. Only Galley's background worker uses it, for an allowlist of the reader's own API calls.
The privacy policy has the details. Security reports go through SECURITY.md.
Limitations
- Comments anchor to whole source blocks (paragraphs, list items, code lines), and GitHub and GitLab threads are flat, so replies are one level deep. Resolving happens on the platform for now.
- Platform-specific syntax renders approximately: GitLab's
[[_TOC_]], math and PlantUML show as text or code, and #123 / @user are not linked.
- The whole pull or merge request is shown; a commit range picked in the platform is not.
- A paragraph rewritten by more than 60% shows as old removed and new added, not as word edits.
- Large requests are listed up to 1,000 files on GitHub and 2,000 on GitLab.
- Repository docs: Markdown only, up to 2,000 documents per repository. The map reads 150 documents at a time; types and connections come from what the documents say. Configuration (Compose, GitHub Actions, GitLab CI, Kubernetes, Terraform) is read statically, on request, up to 60 files; templated or included configuration is not followed. Notes are per browser and do not sync.
Roadmap
- Conversation in the margin. Resolve threads from the reader.
- Review flow. Approve or request changes without leaving it.
- Richer rendering. Math, issue and user references.
- Project understanding. Architecture and infrastructure views, private notes on the map, and project docs beside a review (RFC #49).
- Distribution. A Firefox Add-ons listing.
Contributing
Tell us what makes your reviews harder: a long document, missing context, an accessibility barrier, a conversation that is hard to follow. Issues and pull requests shape the project. CONTRIBUTING.md has the setup, architecture and contribution guidelines, PUBLISHING.md the store release steps, and store/ARTWORK.md how every image in this README is made. Larger ideas start as RFCs; the decisions behind the code are in the architecture decision records.
Project map design prototype
For issue #68, run npm run demo and open http://localhost:4173/?atlas. The demo uses the real local document index and safe renderer; it does not change the extension's Map. ?atlas=dense adds 300 linked demo documents, ?atlas=sparse adds 30 disconnected documents, and ?atlas=partial leaves the real handbook partly indexed. Add &doc=docs/adr/0003-queue-for-reviews.md to open a document directly. Preview settings stay in the session.
The design proposal and Proposed ADR 0030 explain the decision and reader-validation gates before production adoption.
License
GPL-3.0-or-later © Marcin Urbanski. Free to use, study, change and share. If you distribute a modified version, publish its source under the same license. The licences of the bundled libraries ship in THIRD_PARTY_NOTICES.txt inside every build.
Commercial license. Building Galley into a closed-source product, or shipping a modified version without its source? A separate commercial license is available: open an issue titled "Commercial license", leave your contact details out, and you'll get a private way to talk.
