最終更新日

香川研究室でのGerritの使い方

このページについて

このページでは、香川研究室での Gerrit のセットアップ方法、Gerrit の日常の使い方、 などを紹介します。

はじめに

香川研究室の Gerrit は、 http://ymir.eng.kagawa-u.ac.jp/gerrit/ にあります。ただし、NGINX によって転送されていて、実際には woden.eng.kagawa-u.ac.jp で動いています。（大学内からは、 http://woden.eng.kagawa-u.ac.jp/gerrit/ でもアクセスできます。）

こういう構成になっているので、Gerrit の Web ページ内の表示で ssh のホスト名が ymir.eng.kagawa-u.ac.jp になっているところは、 woden.eng.kagawa-u.ac.jp に読み替える必要があります。

なお、Woden の Gerrit で運用している Git リポジトリ―は、 バックアップとして見なさないようしてください。トラブルが起これば、 すぐにリポジトリーや Gerrit 全体を初期化するような運用を考えています。 必ず別の場所 （GitHub、Bitbucket など）にもリポジトリ―のバックアップを 取っておいて（push しておいて）ください。

Gerrit インストール方法メモ

Woden 上の Gerrit がどういう設定で動いているかを、インストール方法とともにメモしておきます。 通常時は、読み飛ばしてもらっても構いません。 （「最初の作業」にジャンプする。）

ダウンロード

WAR ファイル (gerrit-X.XX.XX.war) を Gerrit Code Review からダウンロードしてきます。（現在のバージョンは 2.15.1 です。） さらに、Google Account でログインできるように、 OAuth authentication provider プラグインをダウンロードしておきます。

Gerrit の 初期化

Standalone Daemon Installation Guide に従って、Gerrit をインストールします。 データベースは H2 を使うので、特に事前のインストール作業はありません。

ymir# adduser gerrit
ymir# su gerrit
ymir$ mkdir /var/gerrit
ymir$ mkdir /var/gerrit/plugins 

この plugins というディレクトリーに、OAuth authentication provider からダウンロードした JAR ファイル (gerrit-oauth-provider.jar) を置きます。続いて、次のコマンドを実行します。

ymir$ java -jar gerrit-X.XX.XX.war init -d /var/gerrit

途中でいくつかの質問に答える必要があります。 ほとんどの質問にデフォルトで答えますが、そうでないところを表にまとめました。

これで、/var/gerritの下にいくつかのディレクトリーができます。

Google Auth authentication provider に対する答は こちらの説明に従って入手しておきます。

次のコマンドでサービスを起動しておく必要があります。 自動起動サービスにしていないので、Woden を再起動したときは、 このコマンドを実行しなおします。

ymir# su gerrit
ymir$ /var/gerrit/bin/gerrit.sh start

NGINX の設定

Woden の NGINX には次のように reverse proxy （とパスワード）の設定を入れておきます。 （woden:/etc/nginx/conf.d/default.conf）

  location /gerrit/ {
      proxy_pass http://localhost:8081;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      auth_basic "Gerrit Restricted";
      auth_basic_user_file /etc/nginx/.htpasswd;
  }

Ymir の NGINX のほうは、Woden に飛ばす従来の設定のみです。 （ymir:/etc/nginx/conf.d/default.conf）

  location / {
      proxy_set_header Host $http_host;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_pass http://woden.eng.kagawa-u.ac.jp/;
  }

最初の作業

サインイン

最初に使用するときはサインインする必要があります。 ページの右上の 「sign in」というリンクをクリックしてください。続いて Google アカウントでログイン します。

ログインできたら、ページの右上の表示が自分の名前に変っているはずです。 ここで、「Settings」をクリックして、「Profile」で「Username」を設定しておいてください。 この「Username」はあとで、Gerrit に対して、ssh または scp するときに使います。 Woden のログイン名と同じもので良いと思います。（注: 一度、「Username」をつけると、後で変更できないようなので注意してください。 大文字と小文字が区別されることにも注意してください。）

また、「SSH Public Keys」で「Add SSH Public Key」から、自分のマシンの SSH Public Key を登録しておいてください。あとで、Gerrit に ssh/scp するときに必要です。

プロジェクトの作成

最初に Gerrit にプロジェクトを作成する必要があります。 より詳しい説明は以下にあります。

• Project Creation

Gerrit のページで、「Projects」 > 「Create New Project」 とたどり、 「Project Name:」に名前を入力して、「Create Project」してください。 このプロジェクトに既存のプロジェクトを push したいときは、 「Create initial empty commit」のチェックを外しておくほうが良いようです。 以下では、この「Project Name」を GerritTest として説明します。

SSH トンネリング

以降の作業では、Woden に ssh や scp でアクセスすることがよくありますが、 Woden はポートを学外に公開していないので、学外の PC からは、 ssh や scp をすることができません。

一方、Ymir は学外に公開されているので、 学外の PC からの場合は、次のコマンドを実行して一旦 Ymir にログインしておいてください。

yourPC$ ssh yourname@ymir.eng.kagawa-u.ac.jp -L 1022:133.92.145.23:22 -L 29418:133.92.145.23:29418

これで、yourPC の 1022 番ポートが Woden (133.92.145.23) の 22 番ポートに、 yourPC の 29418 番ポートが Woden の 29418 番ポートにつながります。 以降の ssh/scp コマンドを使う説明では、woden.eng.kagawa-u.ac.jp となっているところを locahost（または 127.0.0.1）に読み替えてください。

既存リポジトリーのプッシュ

手元の既存の Git リポジトリーを Gerrit にプッシュします。まず、 Gerrit のリポジトリーに名前をつけます。yourname と GerritTestの部分は適切なものに変更してください。 （※ SSH トンネリング のところの説明も読んで下さい。）

yourPC$ git remote add gerrit ssh://yourname@woden.eng.kagawa-u.ac.jp:29418/GerritTest

これで gerrit という名前で、Ymir の Gerrit 上の GerritTest リポジトリーを参照することができます。

次のコマンドで実際にプッシュします。

yourPC$ git push -u gerrit master

もし、プロジェクトをつくるときに、「Create initial empty commit」のチェックを外すのを忘れていたら、このプッシュは拒絶されますので、--force （または -f）オプションをつけてプッシュします。

yourPC$ git push -f -u gerrit master

master 以外のブランチも必要に応じてプッシュしておきます。

既存リポジトリーのクローン

逆に、Gerrit に元々あるリポジトリーをローカルにクローンしてくるには、git clone コマンドを使います。

yourPC$ git clone ssh://yourname@woden.eng.kagawa-u.ac.jp:29418/GerritTest

Change ID フックの導入

以降の Gerrit の日々の作業では、Git のコミットメッセージのなかに、Change-Id という一意のタグを挿入しておく必要があります。 これをコミット時に自動的に挿入するようなフックを仕掛けておきます。

ローカルの Git リポジトリーのトップディレクトリーで次のコマンドを実行しておきます。 （※ SSH トンネリング のところの説明も読んで下さい。）

yourPC$ scp -p -P 29418 yourname@woden.eng.kagawa-u.ac.jp:hooks/commit-msg .git/hooks/

日々の作業

Gerrit の日々の作業を説明します。より詳しい説明は以下にあります。

• Working with Gerrit: An Example

リポジトリーの変更

自分の手元にあるリポジトリーを変更したら、ふつうにコミットします。 （Change Id フックは導入済みである必要があります。）

yourPC$ git commit -a -m "..."

それを Gerrit にプッシュします。 普通の方法でプッシュすると、レビューを経ずに直ちにマージされてしまいます。 （また、権限がない場合は拒絶されます。）

yourPC$ git push gerrit master ※普段は、このコマンドは使わない

通常の作業では、refs/for/master という特別なブランチにプッシュします。

yourPC$ git commit -a -m "..."
yourPC$ git push gerrit HEAD:refs/for/master

これでレビューの準備ができました。

もちろん、master 以外のブランチの場合は上記の master の部分をそのブランチ名に変えます。

変更のレビュー

変更のレビュー用のページは、Gerrit ページ から 「All」ー「Open」とたどると選択することができます。

現在の Gerrit の構成では、自分でレビューすることも可能な訳ですが、 卒業論文・修士論文のプロジェクトの場合は私（香川）にレビューを依頼するようにしてください。

レビューが返って来たら、承認されて「+2」がついている場合は レビューを「Submit」できます。「Submit」をクリックすると、 本来のブランチにマージされます。承認されていない場合は、 このレビューを「Abandon」します。

変更の再作業

承認されなかった場合は、ローカルのリポジトリーに戻って修正し、 再度コミット・プッシュします。 このとき、コミットに「--amend」オプションをつけます。

yourPC$ git commit --amend -a -m "..."
yourPC$ git push gerrit HEAD:refs/for/master

yourPC$ git revert -n ハッシュ値
yourPC$ git commit -a -m "revert previous commit"

さいごに

上記の作業例ではすべて master ブランチを使っていましたが、 これは本来の形ではありません。 実際には、適切なブランチをつくって、master には、 安定動作するバージョンだけをコミットするようにして下さい。

Todo

Gitフロー, GitHubフローの説明

参考リンク

• Gerrit Code Review
• Gerrit Code Review for Git (Documentation)
• Working with Gerrit: An Example 普段の使いかた
• Project Owner Guide プロジェクトの管理
  • Import Exsiting History
• gerrit-oauth-provider
  • configuration