author Gregory Szorc <>
Tue, 12 Jan 2016 18:09:56 -0800
changeset 362089 cb01b0d61153146a1e42cf80fa9afa9c4f60be38
parent 362086 89b0c07dc6753b25677e62cc4bd816f5889be2e0
child 362127 630a877e789fa41f704c7b45b81bd15b65bdacfa
permissions -rw-r--r--
docs: link to SSH host key fingerprints Reduce the duplication of these values. Define them in a single point.

.. _mozreview_install:

Configuring Your Machine to Use MozReview

Obtaining Accounts, Credentials, and Privileges

Pushing to MozReview to **initiate** code review requires the following:

* An active ```` (BMO) account
* (optional) A Mozilla LDAP account with Mercurial access and a
  registered SSH key

A BMO account can be created at

Once you have an account, visit to generate a new
API Key. The API Key can have any description you want. We recommend
something like ``mercurial``. The API Key won't be used until later, so
you don't have to generate it right away.

Instructions for obtaining a Mozilla LDAP account with Mercurial access
are documented at
`Becoming A Mozilla Contributor <>`_.


Reviews are initiated with MozReview by pushing to a Mercurial *review*
repository using ``hg push``. Pushing via both SSH and HTTP are supported.

Pushing via HTTP is the easiest to configure **and is recommended for
new contributors**. All you need to push via HTTP is an active Bugzilla
account and Bugzilla API Key.

Pushing via SSH requires a Mozilla LDAP account configured with
Mercurial access and with a registered SSH key. This involves a little
more time and work to obtain. **This is recommended for Mozilla staff and
beyond-casual contributors.**

.. important::

   Pushing via SSH grants additional privileges in the MozReview web
   interface, such as the ability to trigger *Try* jobs and interact
   with the *Autoland* code landing service. If you push things via HTTP
   and have never pushed via SSH before, you will need someone else to
   trigger *Try* jobs for you.

Updating SSH Config

If you are using SSH to push to MozReview, you will want to configure your
SSH username for ````. See :ref:`auth_ssh` for
instructions on updating your SSH client configuration, including the SSH host
key fingerprints.

.. tip::

   If you have already configured ```` in your SSH config,
   it is typically sufficient to copy the settings to

Simple Client Configuration

If you already have a Firefox repository like
`mozilla-central <>`_ cloned, you
can run ``mach mercurial-setup`` from it and a guided wizard will walk
you through configuring Mercurial for optimal use at Mozilla.
Configuring Mercurial for MozReview is part of this wizard.

.. important::

   The wizard currently does not configure the ``autoreview``
   repository. See :ref:`mozreview_install_autoreview` for how to do
   this manually.

If you don't have a Firefox repository, have no fear: just follow the
instructions below.

Installing the Mercurial Extension

Interacting with MozReview from Mercurial **requires** a Mercurial
extension to be installed and configured.

To install that extension, clone the
`version-control-tools <>`_
repository and activate the ``hgext/reviewboard/`` extension in
your ``hgrc``. For example::

  $ hg clone ~/version-control-tools
  $ cat >> ~/.hgrc << EOF
  reviewboard = ~/version-control-tools/hgext/reviewboard/

.. note::

   You likely already have an ``[extensions]`` section in your Mercurial
   configuration. Run ``hg config --edit --global`` (or ``hg config -e
   -g`` for short) to open your global configuration in an editor and
   add the aforementioned extension under the ``[extensions]`` section.

Configuring the Mercurial Extension

The Mercurial extension requires additional Mercurial configuration file
options before it can be used.

Bugzilla Credentials

You will need to define your BMO credentials in your Mercurial
configuration in order to authenticate with MozReview. These are placed
under the ``[bugzilla]`` section in your configuration file. Again,
``hg config -e -g`` to open an editor and place something like the
following in your config file::

  ; Your Bugzilla username. This is an email address.
  username =
  ; A Bugzilla API key
  apikey = ojQBGzhDmFYRFSX4xWNCSyOEsJKqisU0l0EJqXh6

.. note::

   You can generate or obtain an already-generated API Key from

.. important::

   Logging into MozReview will create a Bugzilla API Key named
   ``mozreview``. This API Key has limited permissions and isn't
   suitable for general use. It is recommended to create an API
   Key named ``mercurial`` or ``hg`` and define that in your Mercurial

IRC Nickname

MozReview currently uses your IRC nickname as an identifier when
creating reviews. You will need to define it in your Mercurial
configuration file under the ``[mozilla]`` section.

Use the following as a template::

  ircnick = mynick

Configuring Review Repositories/Paths

You almost certainly want to define the URL you will be pushing to in
your Mercurial configuration so you can type a short name (e.g.
``review``) rather than a full URL (which is longer and harder to

The sections below describe how to do this.

.. _mozreview_install_autoreview:

Configuring the Auto Review Repository

There is a special repository called the ``autoreview`` repository that
will automatically see what you are pushing and *redirect* your push to
the appropriate code review repository. In other words, you don't need
to configure a review path/remote for each clone: you simply define an
alias to the ``autoreview`` repository in your global Mercurial
configuration file and it should *just work*.

Using ``hg config -e -g`` to edit your global Mercurial configuration
file, add an entry under the ``[paths]`` section like so (be sure to use
the appropriate HTTP or SSH URL depending on what you have configured)::

   # For HTTP pushing
   review =

   # For SSH pushing
   review = ssh://

Now, you can ``hg push review`` from any Mercurial repository and it
will go to the ``autoreview`` repository and redirect to the appropriate
review repository automatically!

Advanced Paths Configuration

If the *auto review* repository is too much magic for you, you can
define the review URL for each repository you wish to review from.

.. important::

   We highly recommend the ``autoreview`` repository because it is much
   simpler to manage.

You will want to define a named path in your per-repository hgrc file.
We recommend the name ``review``. The URL for the repository is
``<repo>`` or
``ssh://<repo>`` (depending on whether you
are pushing over HTTP or SSH, respectively) where ``<repo>`` is
the name of a repository.

You can find the list of available repositories at For SSH URls, Just replace ``https://``
with ``ssh://``.

Edit your repository-local config via ``hg config -e`` and adjust your
``[paths]`` section to resemble something like::

  default =
  default-push = ssh://

  # For HTTP pushing
  review =

  # For SSH pushing
  review = ssh://