mozilla/geckoview: the documentation site, not the embedding code

A repository whose first job is to redirect you elsewhere

The first line of the README sets the whole scope. This GitHub repository contains the documentation for GeckoView, and if you are looking for the code for GeckoView you can find it at Mozilla Central. The link goes to a searchfox path for mobile/android/geckoview.

That is unusual enough to be worth pausing on. A repository named after a software project, with the project homepage in the metadata and a steady stream of commits, that contains no implementation at all. The description in the repository metadata says GeckoView is a set of components for embedding Gecko in Android apps, so the subject is a shipping product, but the repository is only its manual.

The reason is visible in the tree. There is an _includes directory, a _layouts directory, a _sass directory, an _config.yml file, a Gemfile and a Gemfile.lock, and an assets directory, which is the layout of a Jekyll site. The default branch is gh-pages, which is the branch GitHub Pages serves. The content directories are consumer, contributor and javadoc, alongside an index.md at the root. The primary language being listed as HTML is consistent with all of that: this is a documentation website, not an application.

So the repository is best understood as the published manual with a public issue tracker attached to it, and the manual is what you are adopting if you embed Gecko.

The homepage is geckoview.dev, and the README notes that you can read more about GeckoView on the wiki at wiki.mozilla.org/Mobile/GeckoView. There is also a link to the source on searchfox, which is Mozilla's code search tool, so the code is browsable even though it is not here.

The consumer path: a quick start and the WebExtension story

The Get Started with GeckoView section has two entries, and they are aimed at exactly two different people.

The first is the GeckoView Quick Start Guide, in the consumer section of the site. That is the document for someone building an Android application that shows web content, and it is the one to read first. The consumer directory in the repository tree holds this material, and it is where a new integrator should start.

The second is Interacting with Web content and WebExtension, which is also in the consumer area. WebExtensions are the browser extension format, and a GeckoView application can host them, so this document covers the interface between an app and the extensions running inside its embedded Gecko instance. This is the part of GeckoView that differs most from a plain web view, and it is where a product decision gets made: whether the embedded browser exposes an extension API at all.

The two-document structure is worth noting because it reflects a deliberate separation between using GeckoView and building it. The consumer documents assume you are embedding the component; the contributor documents assume you are changing it. That separation is why the README's bug guidance is also split, and it is the reason a reader who is unsure which set to follow can decide in seconds by asking whether they want to consume the component or work on it.

The API documentation sits alongside the guides rather than inside them. There is a Changelog link, pointing at the javadoc directory on the site for the mozilla-central documentation set, and an API link, pointing at the index of the same generated documentation. The changelog is a javadoc doc-file, which is the usual way to publish a release note inside a generated API set.

The API reference is generated from mozilla-central

The API links resolve to paths that contain the string mozilla-central, and that is the mechanism that explains the whole site.

The javadoc at geckoview.dev/javadoc/mozilla-central/index.html and the changelog at the corresponding doc-files path are generated from the mozilla-central tree, not written by hand in this repository. The javadoc directory in the repository tree is the source for that generation, and the links in the README are the output.

This has two consequences that matter to an integrator.

The first is that the reference tracks the development branch. A generated reference built from a moving branch describes the API as it is now in mozilla-central, which is the tip of the tree, not the release you are shipping. If you depend on a specific GeckoView build, the reference you want is the one matching that build, and the version pinned in your own build configuration is the thing that decides which documentation is accurate. The changelog is the tool for finding out what changed between builds, and it is the first thing to read when an API call behaves differently than the reference you read three months ago.

The second is that the documentation is close to the code by construction. There is no separate writing step that could fall behind, because the API documentation is generated from the annotations on the code itself. That is a structural advantage over a manual, and it is also why a change in the API shows up in the reference as soon as it lands in the tree.

The other end of the documentation is more hand written. The consumer and contributor guides are prose in the repository, which means they are reviewable through the GitHub issue tracker, which brings us to how problems get reported.

Two issue trackers, and knowing which one to use

The README draws a distinction that is easy to get wrong and that will cost a day if you do.

If there is documentation that is missing, or an existing document does not cover the aspect you are looking for, the request goes to the GitHub issue tracker for this repository. That is the documentation's own backlog, and it is the right place for a missing section, an unclear explanation or a stale example.

If you have a GeckoView bug, the README says to raise it on Bugzilla, with the link pointing at the Bugzilla new bug entry for the GeckoView product. So a defect in the component is a Mozilla bug, filed against the GeckoView product, with the data, the steps to reproduce and the build information that a Mozilla bug report expects.

The two trackers have different audiences and different expectations, and the split is not arbitrary. The documentation repository is a small community site with a GitHub issue tracker and a maintainer who reads it. Bugzilla is the system Mozilla uses for the product itself, with triaging, milestones and the build metadata that an engine bug needs to be actionable.

There is a third route for getting started as a contributor, and it is where the real cost of embedding Gecko becomes visible. The Get Started as a Contributor section lists four documents: the GeckoView Contributor Quick Start Guide, the Mozilla Central Quick Start Guide, the Mozilla Central Contributor Guide, and a Guide to Native Debugging in Android Studio.

Two of those are about GeckoView and two are about Mozilla Central, which is the accurate picture of the work. GeckoView is a component inside the larger Gecko tree, and the GeckoView build is part of a much larger build. The debugging guide is called out separately for a reason: debugging a native component embedded in an Android application means attaching a native debugger to the Gecko process inside the app, and that setup is its own documented procedure. Anyone budgeting for this should read that guide before starting, because it is the step where a small integration becomes a large one.

The site build, and what the repository does not give you

The repository has no GitHub releases, and the default branch is gh-pages, so the site is the release. That is a coherent arrangement for documentation, and it has a consequence for anyone looking for a versioned artifact: there is none. There is no archive of the manual at a given version, because the site always describes the current state of the tree.

The build tooling is visible in the tree. The Gemfile and Gemfile.lock pin the Jekyll dependencies, the _config.yml holds the site configuration, and the _includes, _layouts and _sass directories hold the templates and the stylesheet, with the assets directory for the static files. The Gemfile.lock in particular means the site builds reproducibly, which matters for a site that is published from a branch rather than from a tagged release.

The licence situation needs a note. No licence file appears in the repository, and the README does not state one. For a documentation site that is mostly prose and configuration, that is a smaller issue than it would be for code, but it is a question worth raising on the issue tracker if you intend to reuse the guides or translate them, and it is a question your own organisation may need answered if you fork the site to run it internally.

The last push to the repository was on 2026-10-19, so the documentation is being worked on. The README asks contributors to request missing documentation through the issue tracker, which is a reasonable way to steer a manual whose scope is defined by what the component actually exposes.

Where GeckoView fits, and what it costs to adopt

GeckoView is described as a set of components for embedding Gecko in Android apps, and the practical question for any team considering it is what that buys over the alternatives.

The alternative is a platform web view, the Android System WebView, which is a Chromium build maintained by Google, updated through the operating system and available with no integration work at all. The difference is the engine: Gecko is Firefox's engine, so an application that embeds it gets Firefox's rendering, its security model, and the WebExtension support that Chromium does not offer in a comparable way. For an application that needs extensions inside the embedded content, or that needs to ship a browser whose behaviour it controls rather than one that changes under it when the OS updates, that is the reason to choose Gecko.

The cost is the integration work that the four contributor guides describe. You are embedding a large native component, you are building against a build of mozilla-central rather than a stable binary, and the debug loop for anything that goes wrong below the Java API requires the native debugging procedure. None of that is hidden, and the documentation is the honest way to find out about it, but it is a project, not an afternoon.

The other practical decision is where to look for support. Firefox for Android itself uses GeckoView, and the documentation and the bug tracker are the same ones you would use for any large Firefox-derived component. The wiki page is where the background material lives, and the GitHub issues are where a documentation improvement is fastest to land.

So the honest summary of this repository is that it is a well-organised, actively maintained manual for a component whose integration cost is high and whose documentation is the main thing you can read before committing. It contains no code, so it cannot be wrong about what the code does in the way a stale wiki can; it can only be incomplete, and it has a public tracker for exactly that.

Editorial conclusion

Adopt this repository as your reference if you are embedding Gecko in an Android application, since it is where the consumer quick start, the WebExtension guidance, the contributor setup instructions and the generated API reference live, and it is the right place to report a document that is missing. Do not adopt it as a source of code or a dependency, because the GeckoView implementation is in Mozilla Central and the repository publishes no releases and no versioned artifacts. Verify first which GeckoView version you are targeting, since the API reference is generated from mozilla-central and the changelog is the record of what changed in it, that your bug report goes to Bugzilla under the GeckoView product rather than to the GitHub issue tracker, which is for documentation problems, and that the documentation for the exact revision you depend on is the one that matches your build, since a site built from a moving branch can describe APIs newer than the ones you have.

Frequently asked questions

Official sources

1. Issues
2. mozilla/geckoview on GitHub
3. Project website
4. README